diff options
Diffstat (limited to 'language')
| -rw-r--r-- | language/functions.rst | 30 | ||||
| -rw-r--r-- | language/include.rst | 7 | ||||
| -rw-r--r-- | language/index.rst | 3 | ||||
| -rw-r--r-- | language/scanning.rst | 24 | ||||
| -rw-r--r-- | language/source-file.rst | 4 | ||||
| -rw-r--r-- | language/statements/index.rst | 23 | ||||
| -rw-r--r-- | language/statements/structure.rst | 21 | ||||
| -rw-r--r-- | language/statements/variables.rst | 24 | ||||
| -rw-r--r-- | language/type-definition.rst | 12 |
9 files changed, 124 insertions, 24 deletions
diff --git a/language/functions.rst b/language/functions.rst index 86d1144..22a61a3 100644 --- a/language/functions.rst +++ b/language/functions.rst @@ -3,18 +3,36 @@ Functions .. crowbar:element:: FunctionDeclaration <- FunctionSignature ';' - A function declaration defines the return type, name, and arguments of a function without specifying its behavior. - It is generally used as part of an API boundary. + Compile-time Behavior: + + Provides a declaration of a function with the name, return type, and arguments specified by the signature, but does not specify any behavior. + This is generally used as part of an API boundary. + + Runtime Behavior: + + A function declaration has no runtime behavior. .. crowbar:element:: FunctionDefinition <- FunctionSignature Block - A function definition provides the actual behavior of a function, which may have been declared previously or may not. + Compile-time Behavior: + + Provides the actual behavior of a function, which may have been declared previously or may not. + If the function was declared in some ``.hro`` file which was :crowbar:ref:`include <IncludeStatement>`\ d, the function must be exported and available for external use in the compiler's output. + Otherwise, the function should not be exported. + + If the function signature specifies a return type other than ``void``, but there are paths through the block that do not execute a :crowbar:ref:`ReturnStatement`, the compiler must give an error. - .. todo:: + Runtime Behavior: - define function linkage/exportedness + When the function is called, the arguments must be populated and the block must be executed. .. crowbar:element:: FunctionSignature <- Type identifier '(' SignatureArguments? ')' SignatureArguments <- Type identifier (',' Type identifier)* ','? - + + Compile-time Behavior: + A function signature specifies the return type, name, and arguments of a function. + + Runtime Behavior: + + A function signature has no runtime behavior. diff --git a/language/include.rst b/language/include.rst index cc2964a..4667a49 100644 --- a/language/include.rst +++ b/language/include.rst @@ -3,5 +3,10 @@ Including Headers .. crowbar:element:: IncludeStatement <- 'include' string-literal ';' + Compile-time Behavior: + 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. + + Runtime Behavior: + + This statement has no runtime behavior. diff --git a/language/index.rst b/language/index.rst index 66492a9..e1e2b01 100644 --- a/language/index.rst +++ b/language/index.rst @@ -13,9 +13,10 @@ Syntax elements in this document are given in the form of `parsing expression gr .. toctree:: :maxdepth: 1 - + scanning source-file include type-definition functions + statements/index diff --git a/language/scanning.rst b/language/scanning.rst index 3ed9bfe..a141b41 100644 --- a/language/scanning.rst +++ b/language/scanning.rst @@ -13,18 +13,18 @@ Scanning keyword One of the literal words ``bool``, ``break``, ``case``, ``char``, ``const``, ``continue``, ``default``, ``do``, ``double``, - ``else``, ``enum``, ``extern``, ``float``, ``for``, ``fragile``, + ``else``, ``enum``, ``extern``, ``false``, ``float``, ``for``, ``fragile``, ``function``, ``if``, :crowbar:ref:`include <IncludeStatement>`, ``int``, ``long``, ``opaque``, ``return``, - ``short``, ``signed``, ``sizeof``, ``struct``, ``switch``, ``union``, + ``short``, ``signed``, ``sizeof``, ``struct``, ``switch``, ``true``, ``union``, ``unsigned``, ``void``, or ``while``. - + identifier A nonempty sequence of characters blah blah blah .. todo:: figure out https://www.unicode.org/reports/tr31/tr31-33.html - + constant A numeric (or numeric-equivalent) value specified directly within the code. May be a :term:`decimal constant`, a :term:`binary constant` , an :term:`octal constant`, @@ -50,12 +50,12 @@ Scanning floating-point constant A sequence of characters matching the regular expression ``[0-9_]+\.[0-9_]+([eE][+-]?[0-9_]+)?``. - + .. note:: Unlike in C and many other languages, ``6e3`` in Crowbar is not a valid floating-point constant. The Crowbar-compatible spelling is ``6.0e3``. - + Denotes the numeric value of the given decimal number, optionally expressed in scientific notation. That is, ``XeY`` denotes :math:`X * 10^Y`. @@ -63,12 +63,12 @@ Scanning A sequence of characters matching the regular expression ``0(fx|FX)[0-9a-fA-F_]+\.[0-9a-fA-F_]+[pP][+-]?[0-9_]+``. Denotes the numeric value of the given hexadecimal number expressed in binary scientific notation. That is, ``XpY`` denotes :math:`X * 2^Y`. - + 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 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: @@ -79,7 +79,7 @@ Scanning * ``\n``, denoting the line feed, or newline (U+000A) * ``\t``, denoting the (horizontal) tab (U+0009) * ``\0``, denoting a null character (U+0000) - + Or a sequence of characters matching one of the following regular expressions: * ``\\x[0-9a-fA-F]{2}``, denoting the numeric value of the given two hexadecimal digits @@ -101,13 +101,13 @@ Scanning whitespace A nonempty sequence of characters that each has a Unicode general category of either Control (``Cc``) or Separator (``Z``). Separates tokens. - + comment Text that the compiler should ignore. May be a :term:`line comment` or a :term:`block comment`. - + line comment A sequence of characters beginning with the characters ``//`` (outside of a :term:`string literal` or :term:`comment`) and ending with a newline character U+000A. - + block comment A sequence of characters beginning with the characters ``/*`` (outside of a :term:`string literal` or :term:`comment`) and ending with the characters ``*/``. diff --git a/language/source-file.rst b/language/source-file.rst index 2fc3ba0..162bb88 100644 --- a/language/source-file.rst +++ b/language/source-file.rst @@ -2,14 +2,14 @@ Source Files ------------ .. crowbar:element:: HeaderFile <- IncludeStatement* HeaderFileElement+ -.. crowbar:element:: HeaderFileElement <- TypeDefinition / FunctionDeclaration / ConstantDefinition / VariableDeclaration + HeaderFileElement <- TypeDefinition / FunctionDeclaration / ConstantDefinition / VariableDeclaration 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 + 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. diff --git a/language/statements/index.rst b/language/statements/index.rst new file mode 100644 index 0000000..38bfbb1 --- /dev/null +++ b/language/statements/index.rst @@ -0,0 +1,23 @@ +Statements +---------- + +.. crowbar:element:: Block <- '{' Statement* '}' + + Compile-time Behavior: + + A block is a possibly-empty sequence of statements surrounded by curly braces. + Any declaration or definition within the block must not be visible outside of the block. + + Runtime Behavior: + + When a block is executed, each of the containing statements, in linear order, is executed. + +.. crowbar:element:: Statement <- VariableDefinition / StructureStatement / FlowControlStatement / AssignmentStatement / FragileStatement / ExpressionStatement + + Crowbar has many different types of statement. + +.. toctree:: + :maxdepth: 1 + + variables + structure diff --git a/language/statements/structure.rst b/language/statements/structure.rst new file mode 100644 index 0000000..9330bf6 --- /dev/null +++ b/language/statements/structure.rst @@ -0,0 +1,21 @@ +Structure Statements +^^^^^^^^^^^^^^^^^^^^ + +.. crowbar:element:: StructureStatement <- IfStatement / SwitchStatement / WhileStatement / DoWhileStatement / ForStatement + + A structure statement creates some nonlinear control structure. + There are several types of these structures. + +.. crowbar:element:: IfStatement <- 'if' '(' Expression ')' Block ('else' Block)? + + An if statement allows some action to be performed only sometimes, based on the value of the expression. + + Compile-time Behavior: + + If the expression does not have type bool, the compiler must emit an error. + + Runtime Behavior: + + First, the expression is evaluated. + If the expression evaluates to a ``bool`` value of ``true``, then the first block will be executed. + If the expression evaluates to a ``bool`` value of ``false``, either the second block is executed or nothing is executed. diff --git a/language/statements/variables.rst b/language/statements/variables.rst new file mode 100644 index 0000000..6bc1a6f --- /dev/null +++ b/language/statements/variables.rst @@ -0,0 +1,24 @@ +Variables +^^^^^^^^^ + +.. crowbar:element:: VariableDeclaration <- Type identifier ';' + + Compile-time Behavior: + + A variable declaration specifies the type and name of a variable but not its initial value. + This is only used in :crowbar:ref:`HeaderFile`\ s as part of API boundaries. + + Runtime Behavior: + + A variable declaration has no runtime behavior. + +.. crowbar:element:: VariableDefinition <- Type identifier '=' Expression ';' + + Compile-time Behavior: + + A variable definition specifies the type, name, and initial value of a variable. + If the expression has a type which is not the type specified for the variable, an error must be emitted. + + Runtime Behavior: + + When a variable definition is executed, the expression is evaluated, and its result is made available with the given name. diff --git a/language/type-definition.rst b/language/type-definition.rst index b596d0a..9e3d7c4 100644 --- a/language/type-definition.rst +++ b/language/type-definition.rst @@ -5,6 +5,14 @@ Defining Types Crowbar has three different kinds of user-defined types. + Compile-time Behavior: + + When a type is defined, the compiler must then allow that type to be used. + + Runtime Behavior: + + The definition of a type has no runtime behavior. + .. crowbar:element:: StructDefinition <- NormalStructDefinition / OpaqueStructDefinition NormalStructDefinition <- 'struct' identifier '{' VariableDeclaration+ '}' @@ -25,7 +33,7 @@ Defining Types An ``enum`` defines a type which can take one of several specified values. .. todo:: - + define enum value assignment, type-related behavior .. crowbar:element:: UnionDefinition <- RobustUnionDefinition / FragileUnionDefinition @@ -65,7 +73,7 @@ Defining Types case Whitespace: ; } } - + defines a ``union Token`` type, where the ``type`` field controls which of the other fields in the union is valid. .. todo:: |