\chapter{Module syntax} \label{ch:syntax}
-%%%--------------------------------------------------------------------------
-\section{Notation} \label{sec:syntax.notation}
-
-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 @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence
- of $x$:
- \begin{quote}
- \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$}
- \end{quote}
-\item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or
- more occurrences of $x$:
- \begin{quote}
- \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 one or
- more occurrences of $x$:
- \begin{quote}
- \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$}
- \end{quote}
-\item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$
- separated by commas:
- \begin{quote}
- \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$}
- \end{quote}
-\end{itemize}
-
%%%--------------------------------------------------------------------------
\section{Lexical syntax} \label{sec:syntax.lex}
<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
<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>^+
A @<module> is the top-level syntactic item. A module consists of a sequence
of definitions.
+[FIXME]
+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}
<primary> ::=
<integer-literal> | <string-literal> | <char-literal> | <identifier>
+\alt "<" <plain-type> ">"
\alt "?" <s-expression>
\alt "(" <expression> ")"
\end{grammar}
<abstract-declarator> ::= <declarator>$[\epsilon, \mbox{@<argument-list>}]$
-<argument-declarator> ::= <declarator>$[\mbox{@<identifier> @! $\epsilon$}]$
-
<argument-declarator> ::=
<declarator>$[\mbox{@<identifier> @! $\epsilon$}, \mbox{@<argument-list>}]$
\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}
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
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; \-\\
\};
<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
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.
@<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}
<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}
<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 --------------------------------------------------
~mdw / sod / blobdiff