X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/4307347660f48628e307f299eb4fac58ba35fd1a..7119ea4ebe5d0bd756adfb12dde51a113ae408b0:/doc/syntax.tex

diff --git a/doc/syntax.tex b/doc/syntax.tex
index 1090262..0b7456f 100644
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -58,7 +58,7 @@ enough that they deserve special notation.
     \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::=
       $\epsilon$ @! <zero-or-more>$[x]$ $x$}
   \end{quote}
-\item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of zero or
+\item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of one or
   more occurrences of $x$:
   \begin{quote}
     \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$}
@@ -451,8 +451,19 @@ recognized.
 \alt "bool" | "_Bool"
 \alt "imaginary" | "_Imaginary" | "complex" | "_Complex"
 \alt <qualifier>
+\alt <storage-specifier>
+\alt <atomic-type>
 
-<qualifier> ::= "const" | "volatile" | "restrict"
+<qualifier> ::= <atomic> | "const" | "volatile" | "restrict"
+
+<atomic-type> ::=
+  <atomic> "(" @<declaration-specifier>^+ <abstract-declarator> ")"
+
+<atomic> ::= "atomic" | "_Atomic"
+
+<storage-specifier> ::= <alignas> "(" <c-fragment> ")"
+
+<alignas> ::= "alignas" "_Alignas"
 
 <type-name> ::= <identifier>
 \end{grammar}
@@ -469,9 +480,11 @@ defined in the built-in module.
 
 Declaration specifiers may appear in any order.  However, not all
 combinations are permitted.  A declaration specifier must consist of zero or
-more @<qualifier>s, and one of the following, up to reordering.
+more @<qualifier>s, zero or more @<storage-specifier>s, and one of the
+following, up to reordering.
 \begin{itemize}
 \item @<type-name>
+\item @<atomic-type>
 \item @"struct" @<identifier>, @"union" @<identifier>, @"enum" @<identifier>
 \item @"void"
 \item @"_Bool", @"bool"
@@ -509,6 +522,9 @@ All of these have their usual C meanings.
 
 <argument> ::= @<declaration-specifier>^+ <argument-declarator>
 
+<abstract-declarator> ::= <declarator>$[\epsilon, \mbox{@<argument-list>}]$
+
+<argument-declarator> ::= <declarator>$[\mbox{@<identifier> @! $\epsilon$}]$
 <argument-declarator> ::=
   <declarator>$[\mbox{@<identifier> @! $\epsilon$}, \mbox{@<argument-list>}]$
 
@@ -562,17 +578,17 @@ keyword arguments.
 A @<class-forward-declaration> informs Sod that an @<identifier> will be used
 to name a class which is currently undefined.  Forward declarations are
 necessary in order to resolve certain kinds of circularity.  For example,
-\begin{listing}
+\begin{prog}
 class Sub;
-
-class Super : SodObject {
-  Sub *sub;
-};
-
-class Sub : Super {
-  /* ... */
-};
-\end{listing}
+\\+
+class Super : SodObject \{ \\ \ind
+  Sub *sub; \- \\
+\};
+\\+
+class Sub : Super \{ \\ \ind
+  /* \dots */ \- \\
+\};
+\end{prog}
 
 \subsubsection{Full class definitions}
 \begin{grammar}
@@ -585,6 +601,8 @@ class Sub : Super {
 
 <class-item> ::= <slot-item>
 \alt <initializer-item>
+\alt <initarg-item>
+\alt <fragment-item>
 \alt <message-item>
 \alt <method-item>
 \end{grammar}
@@ -598,7 +616,10 @@ names, to distinguish them from other kinds of identifiers.
 
 The @<list>$[\mbox{@<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.
+class.  The superclass list is required, and must not be empty; listing
+@|SodObject| as your class's superclass is a good choice if nothing else
+seems suitable.  It's not possible to define a \emph{root class} in the Sod
+language: you must use Lisp to do this, and it's quite involved.
 
 The @<properties> provide additional information.  The standard class
 properties are as follows.
@@ -643,28 +664,28 @@ functions are fine.
 An @<initializer>, if present, is treated as if a separate
 @<initializer-item> containing the slot name and initializer were present.
 For example,
-\begin{listing}
-[nick = eg]
-class Example : Super {
-  int foo = 17;
-};
-\end{listing}
+\begin{prog}
+[nick = eg] \\-
+class Example : Super \{ \\ \ind
+  int foo = 17; \- \\
+\};
+\end{prog}
 means the same as
-\begin{listing}
-[nick = eg]
-class Example : Super {
-  int foo;
-  eg.foo = 17;
-};
-\end{listing}
+\begin{prog}
+[nick = eg] \\-
+class Example : Super \{ \\ \ind
+  int foo; \\
+  eg.foo = 17; \- \\
+\};
+\end{prog}
 
 \subsubsection{Initializer items}
 \begin{grammar}
 <initializer-item> ::= @["class"@] <list>$[\mbox{@<slot-initializer>}]$ ";"
 
-<slot-initializer> ::= <dotted-name> "=" <initializer>
+<slot-initializer> ::= <dotted-name> @["=" <initializer>@]
 
-<initializer> :: "{" <c-fragment> "}" | <c-fragment>
+<initializer> :: <c-fragment>
 \end{grammar}
 
 An @<initializer-item> provides an initial value for one or more slots.  If
@@ -675,15 +696,28 @@ 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}
-\item A @<c-fragment> enclosed in braces denotes an aggregate initializer.
-  This is suitable for initializing structure, union or array slots.
-\item A @<c-fragment> \emph{not} beginning with an open brace is a `bare'
-  initializer, and continues until the next @`,' or @`;' which is not within
-  nested brackets.  Bare initializers are suitable for initializing scalar
-  slots, such as pointers or integers, and strings.
-\end{itemize}
+An @|initarg| property may be set on an instance slot initializer (or a
+direct slot definition).  See \xref{sec:concepts.lifecycle.birth} for the
+details.  An initializer item must have either an @|initarg| property, or an
+initializer expression, or both.
+
+Each class may define at most one initializer item with an explicit
+initializer expression for a given slot.
+
+\subsubsection{Initarg items}
+\begin{grammar}
+<initarg-item> ::=
+  "initarg"
+  @<declaration-specifier>^+
+  <list>$[\mbox{@<init-declarator>}]$ ";"
+\end{grammar}
+
+\subsubsection{Fragment items}
+\begin{grammar}
+<fragment-item> ::= <fragment-kind> "{" <c-fragment> "}"
+
+<fragment-kind> ::= "init" | "teardown"
+\end{grammar}
 
 \subsubsection{Message items}
 \begin{grammar}