define compile-time vs runtime behavior

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::