diff options
Diffstat (limited to 'language')
| -rw-r--r-- | language/flow-control.rst | 6 | ||||
| -rw-r--r-- | language/include.rst | 7 | ||||
| -rw-r--r-- | language/index.rst | 18 | ||||
| -rw-r--r-- | language/scanning.rst | 6 | ||||
| -rw-r--r-- | language/source-file.rst | 17 | ||||
| -rw-r--r-- | language/type-definition.rst | 23 |
6 files changed, 56 insertions, 21 deletions
diff --git a/language/flow-control.rst b/language/flow-control.rst deleted file mode 100644 index 853b5bd..0000000 --- a/language/flow-control.rst +++ /dev/null @@ -1,6 +0,0 @@ -Flow Control -============ - -.. crowbar:keyword:: break - - This keyword exits the containing loop. diff --git a/language/include.rst b/language/include.rst new file mode 100644 index 0000000..cc2964a --- /dev/null +++ b/language/include.rst @@ -0,0 +1,7 @@ +Including Headers +----------------- + +.. crowbar:element:: IncludeStatement <- 'include' string-literal ';' + + When encountering this statement at the beginning of a file, the compiler should interpret the string literal as a relative file path, look up the corresponding file in an implementation-defined way, and load the definitions from the given :crowbar:ref:`HeaderFile`. + This statement has no runtime effect. diff --git a/language/index.rst b/language/index.rst index 79702c5..eb2d92c 100644 --- a/language/index.rst +++ b/language/index.rst @@ -4,23 +4,17 @@ Language The syntax of Crowbar is designed to be similar to the syntax of C. A Crowbar source file is UTF-8. +Unless otherwise specified, a *character* in this specification refers to a `Unicode scalar value <https://www.unicode.org/glossary/#unicode_scalar_value>`_. Crowbar source files can come in two varieties: -.. glossary:: - - header file - A Crowbar source file declaring types and functions. - Can be intended for internal use within a project, or to define the public API of a library. - Conventionally has the ``.hro`` file extension. - - implementation file - A Crowbar source file providing function definitions, and sometimes its own type declarations. - Conventionally has the ``.cro`` file extension. - A Crowbar source file is read into memory in two phases: *scanning* (which converts text into an unstructured sequence of tokens) and *parsing* (which converts an unstructured sequence of tokens into a parse tree). +Syntax elements in this document are given in the form of `parsing expression grammar <https://en.wikipedia.org/wiki/Parsing_expression_grammar>`_ rules. + .. toctree:: :maxdepth: 1 scanning - flow-control + source-file + include + type-definition diff --git a/language/scanning.rst b/language/scanning.rst index 86177ac..ed85ead 100644 --- a/language/scanning.rst +++ b/language/scanning.rst @@ -11,10 +11,10 @@ Scanning Punctuators, string literals, and character constants do not require explicit separation from adjacent tokens. keyword - One of the literal words ``bool``, :crowbar:ref:`break`, ``case``, + One of the literal words ``bool``, ``break``, ``case``, ``char``, ``const``, ``continue``, ``default``, ``do``, ``double``, ``else``, ``enum``, ``extern``, ``float``, ``for``, ``fragile``, - ``function``, ``if``, ``include``, ``int``, ``long``, ``return``, + ``function``, ``if``, :crowbar:ref:`include <IncludeStatement>`, ``int``, ``long``, ``return``, ``short``, ``signed``, ``sizeof``, ``struct``, ``switch``, ``unsigned``, ``void``, or ``while``. @@ -67,7 +67,7 @@ Scanning character constant A pair of single quotes ``'`` surrounding either a single character or an :term:`escape sequence`. The single character may not be a single quote or a backslash ``\``. - Denotes the Unicode code point number for either the single surrounded character or the character denoted by the escape sequence. + Denotes the Unicode scalar value for either the single surrounded character or the character denoted by the escape sequence. escape sequence One of the following pairs of characters: diff --git a/language/source-file.rst b/language/source-file.rst new file mode 100644 index 0000000..6522ea8 --- /dev/null +++ b/language/source-file.rst @@ -0,0 +1,17 @@ +Source Files +------------ + +.. crowbar:element:: HeaderFile <- IncludeStatement* HeaderFileElement+ +.. crowbar:element:: HeaderFileElement <- TypeDefinition / FunctionDeclaration / ConstantDefinition / UninitializedVariableDeclaration + + A Crowbar header file defines an API boundary, either at the surface of a library or between pieces of a library or application. + :crowbar:ref:`IncludeStatement`\ s can only appear at the beginning of the header file, and header files cannot define behavior directly. + Conventionally, a header file has a ``.hro`` file extension. + +.. crowbar:element:: ImplementationFile <- IncludeStatement* ImplementationFileElement+ +.. crowbar:element:: ImplementationFileElement <- TypeDefinition / VariableDefinition / FunctionDefinition + + A Crowbar implementation file defines the actual behavior of some piece of a library or application. + It can also define internal types, functions, and variables. + :crowbar:ref:`IncludeStatement`\ s can only appear at the beginning of the implementation file. + Conventionally, an implementation file has a ``.cro`` file extension. diff --git a/language/type-definition.rst b/language/type-definition.rst new file mode 100644 index 0000000..02616b8 --- /dev/null +++ b/language/type-definition.rst @@ -0,0 +1,23 @@ +Defining Types +-------------- + +.. crowbar:element:: TypeDefinition <- StructDefinition / EnumDefinition / UnionDefinition + + Crowbar has three different kinds of user-defined types. + +.. crowbar:element:: StructDefinition <- 'struct' identifier '{' VariableDeclaration+ '}' ';' + + A ``struct`` defines a composite type with several members. + + .. todo:: + + define struct layout in memory + +.. crowbar:element:: EnumDefinition <- 'enum' identifier '{' EnumMember (',' EnumMember)* ','? '}' ';' + EnumMember <- identifier ('=' Expression)? + + An ``enum`` defines a type which can take one of several specified values. + + .. todo:: + + define enum value assignment, type-related behavior |