define and annotate some language elements

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