X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/7292d6e1bc85cca454f64353722ba78a9263f257..ec81a2ac1ca37f2cc198d29b358863cf487a65c4:/doc/syntax.tex?ds=sidebyside

diff --git a/doc/syntax.tex b/doc/syntax.tex
index 18b46e1..73a353a 100644
--- a/doc/syntax.tex
+++ b/doc/syntax.tex
@@ -59,7 +59,7 @@ could be a token.
 
 <digit-char> ::= "0" | <nonzero-digit-char>
 
-<nonzero-digit-char> ::= "1" | "2" $| \cdots |$ "9"
+<nonzero-digit-char> ::= "1" | "2" $| \ldots |$ "9"
 \end{grammar}
 
 The precise definition of @<alpha-char> is left to the function
@@ -112,7 +112,7 @@ discouraged.
 
 <octal-integer> ::= "0" @["o"|"O"@] @<octal-digit-char>^+
 
-<octal-digit-char> ::= "0" | "1" $| \cdots |$ "7"
+<octal-digit-char> ::= "0" | "1" $| \ldots |$ "7"
 
 <hex-integer> ::= "0" @("x"|"X"@) @<hex-digit-char>^+
 
@@ -210,6 +210,16 @@ brackets, braces or parenthesis ends the fragment.
 A @<module> is the top-level syntactic item.  A module consists of a sequence
 of definitions.
 
+\fixme{describe syntax; expand}
+Properties:
+\begin{description}
+\item[@"module_class"] A symbol naming the Lisp class to use to
+  represent the module.
+\item[@"guard"] An identifier to use as the guard symbol used to prevent
+  multiple inclusion in the header file.
+\end{description}
+
+
 \subsection{Simple definitions} \label{sec:syntax.module.simple}
 
 \subsubsection{Importing modules}
@@ -482,8 +492,6 @@ All of these have their usual C meanings.
 
 <abstract-declarator> ::= <declarator>$[\epsilon, \mbox{@<argument-list>}]$
 
-<argument-declarator> ::= <declarator>$[\mbox{@<identifier> @! $\epsilon$}]$
-
 <argument-declarator> ::=
   <declarator>$[\mbox{@<identifier> @! $\epsilon$}, \mbox{@<argument-list>}]$
 
@@ -540,11 +548,11 @@ necessary in order to resolve certain kinds of circularity.  For example,
 \begin{prog}
 class Sub;                                                      \\+
 
-class Super : SodObject \{                                      \\ \ind
+class Super: SodObject \{                                       \\ \ind
   Sub *sub;                                                   \-\\
 \};                                                             \\+
 
-class Sub : Super \{                                            \\ \ind
+class Sub: Super \{                                             \\ \ind
   /* \dots\ */                                                \-\\
 \};
 \end{prog}
@@ -593,7 +601,7 @@ properties are as follows.
   which messages it will respond to, and what its behaviour will be when it
   receives them.  The property value must be an identifier naming a defined
   subclass of @"SodClass".  The default metaclass is @"SodClass".
-  %%% FIXME xref to theory
+  See \xref{sec:concepts.metaclasses} for more details.
 \item[@"nick"] A nickname for the class, to be used to distinguish it from
   other classes in various limited contexts.  The property value must be an
   identifier; the default is constructed by forcing the class name to
@@ -620,19 +628,30 @@ 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
 functions are fine.
 
+Properties:
+\begin{description}
+\item[@"slot_class"] A symbol naming the Lisp class to use to represent the
+  direct slot.
+\item[@"initarg"] An identifier naming an initialization argument which can
+  be used to provide a value for the slot.  See
+  \xref{sec:concepts.lifecycle.birth} for the details.
+\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
+  the initarg.  Only permitted if @"initarg" is also set.
+\end{description}
+
 An @<initializer>, if present, is treated as if a separate
 @<initializer-item> containing the slot name and initializer were present.
 For example,
 \begin{prog}
 [nick = eg]                                                     \\
-class Example : Super \{                                        \\ \ind
+class Example: Super \{                                         \\ \ind
   int foo = 17;                                               \-\\
 \};
 \end{prog}
 means the same as
 \begin{prog}
 [nick = eg]                                                     \\
-class Example : Super \{                                        \\ \ind
+class Example: Super \{                                         \\ \ind
   int foo;                                                      \\
   eg.foo = 17;                                                \-\\
 \};
@@ -644,7 +663,7 @@ class Example : Super \{                                        \\ \ind
 
 <slot-initializer> ::= <dotted-name> @["=" <initializer>@]
 
-<initializer> :: <c-fragment>
+<initializer> ::= <c-fragment>
 \end{grammar}
 
 An @<initializer-item> provides an initial value for one or more slots.  If
@@ -655,10 +674,18 @@ 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.
 
-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.
+Properties:
+\begin{description}
+\item[@"initializer_class"] A symbol naming the Lisp class to use to
+  represent the initializer.
+\item[@"initarg"] An identifier naming an initialization argument which can
+  be used to provide a value for the slot.  See
+  \xref{sec:concepts.lifecycle.birth} for the details.  An initializer item
+  must have either an @|initarg| property, or an initializer expression, or
+  both.
+\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
+  the initarg.  Only permitted if @"initarg" is also set.
+\end{description}
 
 Each class may define at most one initializer item with an explicit
 initializer expression for a given slot.
@@ -670,6 +697,11 @@ initializer expression for a given slot.
   @<declaration-specifier>^+
   <list>$[\mbox{@<init-declarator>}]$ ";"
 \end{grammar}
+Properties:
+\begin{description}
+\item[@"initarg_class"] A symbol naming the Lisp class to use to represent
+  the initarg.
+\end{description}
 
 \subsubsection{Fragment items}
 \begin{grammar}
@@ -685,6 +717,49 @@ initializer expression for a given slot.
   <keyword-declarator>$[\mbox{@<identifier>}]$
   @[<method-body>@]
 \end{grammar}
+Properties:
+\begin{description}
+\item[@"message_class"] A symbol naming the Lisp class to use to represent
+  the message.
+\item[@"combination"] A keyword naming the aggregating method combination to
+  use.
+\item[@"most_specific"] A keyword, either @`first' or @`last', according to
+  whether the most specific applicable method should be invoked first or
+  last.
+\end{description}
+
+Properties for the @|custom| aggregating method combination:
+\begin{description}
+\item[@"retvar"] An identifier for the return value from the effective
+  method.  The default is @|sod__ret|.  Only permitted if the message return
+  type is not @|void|.
+\item[@"valvar"] An identifier holding each return value from a direct method
+  in the effective method.  The default is @|sod__val|.  Only permitted if
+  the method return type (see @"methty" below) is not @|void|.
+\item[@"methty"] A C type, which is the return type for direct methods of
+  this message.  The default is the return type of the message.
+\item[@"decls"] A code fragment containing declarations to be inserted at the
+  head of the effective method body.  The default is to insert nothing.
+\item[@"before"] A code fragment containing initialization to be performed at
+  the beginning of the effective method body.  The default is to insert
+  nothing.
+\item[@"empty"] A code fragment executed if there are no primary methods;
+  it should usually store a suitable (identity) value in @<retvar>.  The
+  default is not to emit an effective method at all if there are no primary
+  methods.
+\item[@"first"] A code fragment to set the return value after calling the
+  first applicable direct method.  The default is to use the @"each"
+  fragment.
+\item[@"each"] A code fragment to set the return value after calling a direct
+  method.  If @"first" is also set, then it is used after the first direct
+  method instead of this.  The default is to insert nothing, which is
+  probably not what you want.
+\item[@"after"] A code fragment inserted at the end of the effective method
+  body.  The default is to insert nothing.
+\item[@"count"] An identifier naming a variable to be declared in the
+  effective method body, of type @|size_t|, holding the number of applicable
+  methods.  The default is not to provide such a variable.
+\end{description}
 
 \subsubsection{Method items}
 \begin{grammar}
@@ -695,6 +770,14 @@ initializer expression for a given slot.
 
 <method-body> ::= "{" <c-fragment> "}" | "extern" ";"
 \end{grammar}
+Properties:
+\begin{description}
+\item[@"method_class"] A symbol naming the Lisp class to use to represent
+  the direct method.
+\item[@"role"] A keyword naming the direct method's rÃ´le.  For the built-in
+  `simple' message classes, the acceptable rÃ´le names are @|before|,
+  @|after|, and @|around|.  By default, a primary method is constructed.
+\end{description}
 
 %%%----- That's all, folks --------------------------------------------------
 
