define compile-time vs runtime behavior

17 files changed, 181 insertions, 96 deletions

diff --git a/.editorconfig b/.editorconfig
index f4dfbaa..f7a7f0f 100644
--- a/.editorconfig
+++ b/.editorconfig
@@ -6,6 +6,7 @@ insert_final_newline = true
 indent_style = space
 indent_size = 4
 charset = utf-8
+trim_trailing_whitespace = true
 
 [Makefile]
 indent_style = tab
diff --git a/_ext/crowbar_domain.py b/_ext/crowbar_domain.py
index 619487d..673f756 100644
--- a/_ext/crowbar_domain.py
+++ b/_ext/crowbar_domain.py
@@ -52,7 +52,7 @@ class ElementDirective(ObjectDescription):
                 else:
                     peg_rule += addnodes.desc_sig_operator('', '', nodes.literal(text=token))
         return element
-    
+
     def add_target_and_index(self, name, sig, signode):
         signode['ids'].append('element' + '-' + name)
         if 'noindex' not in self.options:
diff --git a/_ext/gemtext_builder.py b/_ext/gemtext_builder.py
index c26b053..9c7326d 100644
--- a/_ext/gemtext_builder.py
+++ b/_ext/gemtext_builder.py
@@ -14,7 +14,7 @@ class GemtextWriter(writers.Writer):
     def __init__(self, builder):
         super().__init__()
         self.builder = builder
-    
+
     def translate(self):
         visitor = self.builder.create_translator(self.document, self.builder)
         self.document.walkabout(visitor)
@@ -33,25 +33,25 @@ class GemtextTranslator(SphinxTranslator):
         if self.current_line != '':
             self.body.append(self.current_line)
             self.current_line = ''
-    
+
     def visit_document(self, node: nodes.document):
         self.heading_level = 1
         self.current_line = ''
         self.body = []
         self.literal = False
         self.pending_links = []
-    
+
     def depart_document(self, node: nodes.document):
         self._finish_line()
-    
+
     def visit_section(self, node: nodes.section):
         self.heading_level += 1
         if len(self.body) > 0 and self.body[-1] != '':
             self.body.append('')
-    
+
     def depart_section(self, node: nodes.section):
         self.heading_level -= 1
-    
+
     def visit_title(self, node: nodes.title):
         pass
 
@@ -65,7 +65,7 @@ class GemtextTranslator(SphinxTranslator):
         if not self.literal:
             text = text.replace('\n', ' ')
         self.current_line += text
-    
+
     def depart_Text(self, node: nodes.Text):
         pass
 
@@ -95,7 +95,7 @@ class GemtextTranslator(SphinxTranslator):
             self.body.append('=> {} {}'.format(node.attributes['uri'], node.attributes['alt']))
         else:
             raise NotImplementedError('inline images')
-    
+
     def depart_image(self, node: nodes.image):
         pass
 
@@ -104,12 +104,12 @@ class GemtextTranslator(SphinxTranslator):
 
     def visit_strong(self, node: nodes.strong):
         self.current_line += '**'
-    
+
     depart_strong = visit_strong
 
     def visit_emphasis(self, node: nodes.emphasis):
         self.current_line += '_'
-    
+
     depart_emphasis = visit_emphasis
 
     def visit_target(self, node: nodes.target):
@@ -165,16 +165,16 @@ class GemtextTranslator(SphinxTranslator):
         self.body.append('```')
         self.body.append('')
         self.literal = False
-    
+
     def visit_index(self, node: nodes.Node):
         pass
-    
+
     def depart_index(self, node: nodes.Node):
         pass
 
     def visit_desc(self, node: nodes.Node):
         pass
-    
+
     def depart_desc(self, node: nodes.Node):
         pass
 
@@ -250,10 +250,10 @@ class GemtextBuilder(Builder):
     def get_outdated_docs(self):
         yield from self.env.found_docs # can't be fucked to implement this right
         yield 'genindex'
-    
+
     def get_target_uri(self, docname: str, typ: str = None):
         return docname + '.gmi'
-    
+
     def prepare_writing(self, docnames: Set[str]):
         self.writer = GemtextWriter(self)
 
diff --git a/index.rst b/index.rst
index 92e9a4d..8155b3c 100644
--- a/index.rst
+++ b/index.rst
@@ -48,7 +48,7 @@ Chapters
 ========
 
 ..  toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :numbered:
 
     vs-c
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::
diff --git a/make.bat b/make.bat
index 2119f51..922152e 100644
--- a/make.bat
+++ b/make.bat
@@ -1,35 +1,35 @@
-@ECHO OFF

-

-pushd %~dp0

-

-REM Command file for Sphinx documentation

-

-if "%SPHINXBUILD%" == "" (

-	set SPHINXBUILD=sphinx-build

-)

-set SOURCEDIR=.

-set BUILDDIR=_build

-

-if "%1" == "" goto help

-

-%SPHINXBUILD% >NUL 2>NUL

-if errorlevel 9009 (

-	echo.

-	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx

-	echo.installed, then set the SPHINXBUILD environment variable to point

-	echo.to the full path of the 'sphinx-build' executable. Alternatively you

-	echo.may add the Sphinx directory to PATH.

-	echo.

-	echo.If you don't have Sphinx installed, grab it from

-	echo.http://sphinx-doc.org/

-	exit /b 1

-)

-

-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

-goto end

-

-:help

-%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%

-

-:end

-popd

+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=.
+set BUILDDIR=_build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd
diff --git a/safety.rst b/safety.rst
index 61cca97..6a73b85 100644
--- a/safety.rst
+++ b/safety.rst
@@ -58,7 +58,7 @@ Use after free
 --------------
 
 ``free(&x);`` will set ``x = NULL;``
-``owned`` and ``borrowed`` keywords 
+``owned`` and ``borrowed`` keywords
 
 Uninitialized variables
 =======================
diff --git a/syntax.md b/syntax.md
index e6ec9f1..b8e4554 100644
--- a/syntax.md
+++ b/syntax.md
@@ -3,31 +3,15 @@
 ### Statements
 
 ```PEG
-Block                   ← '{' Statement* '}'
-    
-Statement               ← VariableDefinition /
-                          VariableDeclaration /
-                          IfStatement /
-                          SwitchStatement /
-                          WhileStatement /
-                          DoWhileStatement /
-                          ForStatement /
-                          FlowControlStatement /
-                          AssignmentStatement /
-                          ExpressionStatement
-    
-VariableDefinition      ← Type identifier '=' Expression ';'
-VariableDeclaration     ← Type identifier ';'
-    
 IfStatement             ← 'if' Expression Block 'else' Block /
                           'if' Expression Block
-    
+
 SwitchStatement         ← 'switch' Expression '{' SwitchCase+ '}'
 SwitchCase              ← CaseSpecifier Block /
                           'default' Block
 CaseSpecifier           ← 'case' Expression ',' CaseSpecifier /
                           'case' Expression ','?
-    
+
 WhileStatement          ← 'while' Expression Block
 DoWhileStatement        ← 'do' Block 'while' Expression ';'
 ForStatement            ← 'for' VariableDefinition? ';' Expression ';' AssignmentStatementBody? Block
diff --git a/vs-c.rst b/vs-c.rst
index 8317155..42f8a38 100644
--- a/vs-c.rst
+++ b/vs-c.rst
@@ -70,7 +70,7 @@ Additions
 Anti-Footguns
 -------------
 
-*   C is generous with memory in ways that are unreliable by default. 
+*   C is generous with memory in ways that are unreliable by default.
     Crowbar adds :doc:`memory safety conventions <safety>` to make correctness the default behavior.
 *   C's conventions for error handling are unreliable by default.
     Crowbar adds :doc:`error propagation <errors>` to make correctness the default behavior.