X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/1f7d590d9c7b87442c8d8b6424ed4f769d377692..c32aa709ec47cee02e46fc9e74e58eb6a9b430a6:/doc/syntax.tex

diff --git a/doc/syntax.tex b/doc/syntax.tex
index de85ce8..0d1c65e 100644
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -7,7 +7,7 @@
 
 %%%----- Licensing notice ---------------------------------------------------
 %%%
-%%% This file is part of the Sensble Object Design, an object system for C.
+%%% This file is part of the Sensible Object Design, an object system for C.
 %%%
 %%% SOD is free software; you can redistribute it and/or modify
 %%% it under the terms of the GNU General Public License as published by
@@ -27,30 +27,45 @@
 
 %%%--------------------------------------------------------------------------
 
-Fortunately, Sod is syntactically quite simple.  I've used a little slightly
-unusual notation in order to make the presentation easier to read.  For any
-nonterminal $x$:
+Fortunately, Sod is syntactically quite simple.  The notation is slightly
+unusual in order to make the presentation shorter and easier to read.
+
+Anywhere a simple nonterminal name $x$ may appear in the grammar, an
+\emph{indexed} nonterminal $x[a_1, \ldots, a_n]$ may also appear.  On the
+left-hand side of a production rule, the indices $a_1$, \ldots, $a_n$ are
+variables which vary over all nonterminal and terminal symbols, and the
+variables may also appear on the right-hand side in place of a nonterminal.
+Such a rule stands for a family of rules, in each variable is replaced by
+each possible simple nonterminal or terminal symbol.
+
+The letter $\epsilon$ denotes the empty nonterminal
+\begin{quote}
+  \syntax{$\epsilon$ ::=}
+\end{quote}
+
+The following indexed productions are used throughout the grammar, some often
+enough that they deserve special notation.
 \begin{itemize}
-\item $\epsilon$ denotes the empty nonterminal:
-  \begin{quote}
-    $\epsilon$ ::=
-  \end{quote}
-\item @[$x$@] means an optional $x$:
+\item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence
+  of $x$:
   \begin{quote}
-    \syntax{@[$x$@] ::= $\epsilon$ @! $x$}
+    \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$}
   \end{quote}
-\item $x^*$ means a sequence of zero or more $x$s:
+\item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or
+  more occurrences of $x$:
   \begin{quote}
-    \syntax{$x^*$ ::= $\epsilon$ @! $x^*$ $x$}
+    \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::=
+      $\epsilon$ @! <zero-or-more>$[x]$ $x$}
   \end{quote}
-\item $x^+$ means a sequence of one or more $x$s:
+\item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of zero or
+  more occurrences of $x$:
   \begin{quote}
-    \syntax{$x^+$ ::= $x$ $x^*$}
+    \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$}
   \end{quote}
-\item $x$@<-list> means a sequence of one or more $x$s separated
-  by commas:
+\item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$
+  separated by commas:
   \begin{quote}
-    \syntax{$x$<-list> ::= $x$ @! $x$<-list> "," $x$}
+    \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$}
   \end{quote}
 \end{itemize}
 
@@ -131,7 +146,7 @@ discouraged.
 \alt <octal-integer>
 \alt <hex-integer>
 
-<decimal-integer> ::= <nonzero-digit-char> @<digit-char>^*
+<decimal-integer> ::= "0" | <nonzero-digit-char> @<digit-char>^*
 
 <binary-integer> ::= "0" @("b"|"B"@) @<binary-digit-char>^+
 
@@ -311,18 +326,19 @@ depends on Common Lisp.)
 
 The @<s-expression> is evaluated immediately.  It can do anything it likes.
 
-\textbf{Warning!}  This means that hostile Sod modules are a security hazard.
-Lisp code can read and write files, start other programs, and make network
-connections.  Don't install Sod modules from sources that you don't
-trust.\footnote{%
-  Presumably you were going to run the corresponding code at some point, so
-  this isn't as unusually scary as it sounds.  But please be careful.} %
+\begin{boxy}[Warning!]
+  This means that hostile Sod modules are a security hazard.  Lisp code can
+  read and write files, start other programs, and make network connections.
+  Don't install Sod modules from sources that you don't trust.\footnote{%
+    Presumably you were going to run the corresponding code at some point, so
+    this isn't as unusually scary as it sounds.  But please be careful.} %
+\end{boxy}
 
 \subsubsection{Declaring type names} \label{sec:syntax.defs.typename}
 
 \begin{grammar}
 <typename-definition> ::=
-  "typename" <identifier-list> ";"
+  "typename" <list>@[<identifier>@] ";"
 \end{grammar}
 
 Each @<identifier> is declared as naming a C type.  This is important because
@@ -339,7 +355,7 @@ declarations instead.
   "code" <identifier> ":" <identifier> @[<constraints>@]
   "{" <c-fragment> "}"
 
-<constraints> ::= "[" <constraint-list> "]"
+<constraints> ::= "[" <list>@[<constraint>@] "]"
 
 <constraint> ::= @<identifier>^+
 \end{grammar}
@@ -371,7 +387,7 @@ elsewhere in the generated output files.
 \subsection{Property sets} \label{sec:syntax.propset}
 
 \begin{grammar}
-<properties> ::= "[" <property-list> "]"
+<properties> ::= "[" <list>@[<property>@] "]"
 
 <property> ::= <identifier> "=" <expression>
 \end{grammar}
@@ -441,7 +457,7 @@ using the @"typename" or @"class" definitions.
 
 Declaration specifiers may appear in any order.  However, not all
 combinations are permitted.  A declaration specifier must consist of zero or
-more @<qualifiers>, and one of the following, up to reordering.
+more @<qualifier>s, and one of the following, up to reordering.
 \begin{itemize}
 \item @<type-name>
 \item @"struct" @<identifier>, @"union" @<identifier>, @"enum" @<identifier>
@@ -465,7 +481,7 @@ All of these have their usual C meanings.
 
 <primary-declarator>$[k]$ ::= $k$
 \alt "(" <primary-declarator>$[k]$ ")"
-\alt <primary-declarator>$[k]$ @<declarator-suffix>^*
+\alt <primary-declarator>$[k]$ @<declarator-suffix>
 
 <pointer> ::= "*" @<qualifier>^*
 
@@ -473,7 +489,7 @@ All of these have their usual C meanings.
 \alt "(" <arguments> ")"
 
 <arguments> ::= $\epsilon$ | "..."
-\alt <argument-list> @["," "..."@]
+\alt <list>@[<argument>@] @["," "..."@]
 
 <argument> ::= @<declaration-specifier>^+ <argument-declarator>
 
@@ -531,13 +547,13 @@ class Sub : Super {
 \begin{grammar}
 <full-class-definition> ::=
   @[<properties>@]
-  "class" <identifier> ":" <identifier-list>
+  "class" <identifier> ":" <list>@[<identifier>@]
   "{" @<class-item>^* "}"
 
 <class-item> ::= <slot-item> ";"
+\alt <initializer-item> ";"
 \alt <message-item>
 \alt <method-item>
-\alt  <initializer-item> ";"
 \end{grammar}
 
 A full class definition provides a complete description of a class.
@@ -547,7 +563,7 @@ give the name of an existing class (other than a forward-referenced class),
 or an existing type name.  It is conventional to give classes `MixedCase'
 names, to distinguish them from other kinds of identifiers.
 
-The @<identifier-list> names the direct superclasses for the new class.  It
+The @<list>@[<identifier>@] names the direct superclasses for the new class.  It
 is an error if any of these @<identifier>s does not name a defined class.
 
 The @<properties> provide additional information.  The standard class
@@ -578,15 +594,15 @@ These items are discussed on the following sections.
 \begin{grammar}
 <slot-item> ::=
   @[<properties>@]
-  @<declaration-specifier>^+ <init-declarator-list>
+  @<declaration-specifier>^+ <list>@[<init-declarator>@]
 
-<init-declarator> ::= <declarator> @["=" <initializer>@]
+<init-declarator> ::= <simple-declarator> @["=" <initializer>@]
 \end{grammar}
 
 A @<slot-item> defines one or more slots.  All instances of the class and any
 subclass will contain these slot, with the names and types given by the
 @<declaration-specifiers> and the @<declarators>.  Slot declarators may not
-contain qualified identifiers.
+contain dotted names.
 
 It is not possible to declare a slot with function type: such an item is
 interpreted as being a @<message-item> or @<method-item>.  Pointers to
@@ -613,9 +629,9 @@ class Example : Super {
 \subsubsection{Initializer items} \label{sec:syntax.class.init}
 
 \begin{grammar}
-<initializer-item> ::= @["class"@] <slot-initializer-list>
+<initializer-item> ::= @["class"@] <list>@[<slot-initializer>@]
 
-<slot-initializer> ::= <qualified-identifier> "=" <initializer>
+<slot-initializer> ::= <dotted-name> "=" <initializer>
 
 <initializer> :: "{" <c-fragment> "}" | <c-fragment>
 \end{grammar}
@@ -624,9 +640,9 @@ An @<initializer-item> provides an initial value for one or more slots.  If
 prefixed by @"class", then the initial values are for class slots (i.e.,
 slots of the class object itself); otherwise they are for instance slots.
 
-The first component of the @<qualified-identifier> must be the nickname of
-one of the class's superclasses (including itself); the second must be the
-name of a slot defined in that superclass.
+The first component of the @<dotted-name> must be the nickname of one of the
+class's superclasses (including itself); the second must be the name of a
+slot defined in that superclass.
 
 The initializer has one of two forms.
 \begin{itemize}