X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~mdw/git/sod/blobdiff_plain/020b9e2b4364c61a668d47c4c5405295349817d8..0e5c0b9edba8966aba72acb2b101b7a13d80f45a:/doc/syntax.tex diff --git a/doc/syntax.tex b/doc/syntax.tex index 65bd727..0e14e17 100644 --- a/doc/syntax.tex +++ b/doc/syntax.tex @@ -25,51 +25,6 @@ \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 @$[x]$, denoting an optional occurrence - of $x$: - \begin{quote} - \syntax{@[$x$@] ::= $[x]$ ::= $\epsilon$ @! $x$} - \end{quote} -\item $x^*$ abbreviates @$[x]$, denoting a sequence of zero or - more occurrences of $x$: - \begin{quote} - \syntax{$x^*$ ::= $[x]$ ::= - $\epsilon$ @! $[x]$ $x$} - \end{quote} -\item $x^+$ abbreviates @$[x]$, denoting a sequence of one or - more occurrences of $x$: - \begin{quote} - \syntax{$x^+$ ::= $[x]$ ::= $[x]$ $x$} - \end{quote} -\item @$[x]$ denotes a sequence of one or more occurrences of $x$ - separated by commas: - \begin{quote} - \syntax{$[x]$ ::= $x$ @! $[x]$ "," $x$} - \end{quote} -\end{itemize} - %%%-------------------------------------------------------------------------- \section{Lexical syntax} \label{sec:syntax.lex} @@ -196,16 +151,16 @@ binary. However, length and signedness indicators are not permitted. ::= any character other than "*" or "/" - ::= "//" @^* + ::= "/\,/" @^* ::= a newline character ::= any character other than newline \end{grammar} -Comments are exactly as in C99: both traditional block comments `\texttt{/*} -\dots\ \texttt{*/}' and \Cplusplus-style `\texttt{//} \dots' comments are -permitted and ignored. +Comments are exactly as in C99: both traditional block comments `@|/*| \dots\ +@|*/|' and \Cplusplus-style `@|/\,/| \dots' comments are permitted and +ignored. \subsection{Special nonterminals} \label{sec:syntax.lex.special} @@ -255,6 +210,16 @@ brackets, braces or parenthesis ends the fragment. A @ 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} @@ -407,14 +372,15 @@ though the only operators currently defined act on integer values only. \subsubsection{The expression evaluator} \begin{grammar} - ::= | "+" | "-" + ::= | "+" | "--" ::= | "*" | "/" - ::= | "+" | "-" + ::= | "+" | "--" ::= | | | +\alt "<" ">" \alt "?" \alt "(" ")" \end{grammar} @@ -456,8 +422,10 @@ recognized. ::= | "const" | "volatile" | "restrict" + ::= @^+ + ::= - "(" @^+ ")" + "(" ")" ::= "atomic" | "_Atomic" @@ -517,14 +485,15 @@ All of these have their usual C meanings. $[a]$ ::= "[" "]" \alt "(" $a$ ")" - ::= $\epsilon$ | "..." -\alt $[\mbox{@}]$ @["," "..."@] + ::= $\epsilon$ | "\dots" +\alt $[\mbox{@}]$ @["," "\dots"@] ::= @^+ ::= $[\epsilon, \mbox{@}]$ ::= $[\mbox{@ @! $\epsilon$}]$ + ::= $[\mbox{@ @! $\epsilon$}, \mbox{@}]$ @@ -581,11 +550,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} @@ -634,7 +603,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 @@ -661,19 +630,28 @@ It is not possible to declare a slot with function type: such an item is interpreted as being a @ or @. 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. +\end{description} + An @, if present, is treated as if a separate @ 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; \-\\ \}; @@ -696,10 +674,18 @@ The first component of the @ 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. @@ -711,6 +697,11 @@ initializer expression for a given slot. @^+ $[\mbox{@}]$ ";" \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} @@ -726,6 +717,45 @@ initializer expression for a given slot. $[\mbox{@}]$ @[@] \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. +\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[@"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} @@ -736,6 +766,14 @@ initializer expression for a given slot. ::= "{" "}" | "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 --------------------------------------------------