aboutsummaryrefslogtreecommitdiff
path: root/language
diff options
context:
space:
mode:
Diffstat (limited to 'language')
-rw-r--r--language/flow-control.rst6
-rw-r--r--language/include.rst7
-rw-r--r--language/index.rst18
-rw-r--r--language/scanning.rst6
-rw-r--r--language/source-file.rst17
-rw-r--r--language/type-definition.rst23
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