chiark / gitweb /
doc/list-exports.lisp, doc/SYMBOLS: Report on condition classes.
[sod] / doc / syntax.tex
CommitLineData
1f7d590d
MW
1%%% -*-latex-*-
2%%%
3%%% Module syntax
4%%%
5%%% (c) 2015 Straylight/Edgeware
6%%%
7
8%%%----- Licensing notice ---------------------------------------------------
9%%%
e0808c47 10%%% This file is part of the Sensible Object Design, an object system for C.
1f7d590d
MW
11%%%
12%%% SOD is free software; you can redistribute it and/or modify
13%%% it under the terms of the GNU General Public License as published by
14%%% the Free Software Foundation; either version 2 of the License, or
15%%% (at your option) any later version.
16%%%
17%%% SOD is distributed in the hope that it will be useful,
18%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
19%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20%%% GNU General Public License for more details.
21%%%
22%%% You should have received a copy of the GNU General Public License
23%%% along with SOD; if not, write to the Free Software Foundation,
24%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25
26\chapter{Module syntax} \label{ch:syntax}
27
28%%%--------------------------------------------------------------------------
68a620ab 29\section{Notation} \label{sec:syntax.notation}
1f7d590d 30
0bc19f1c
MW
31Fortunately, Sod is syntactically quite simple. The notation is slightly
32unusual in order to make the presentation shorter and easier to read.
33
34Anywhere a simple nonterminal name $x$ may appear in the grammar, an
35\emph{indexed} nonterminal $x[a_1, \ldots, a_n]$ may also appear. On the
36left-hand side of a production rule, the indices $a_1$, \ldots, $a_n$ are
37variables which vary over all nonterminal and terminal symbols, and the
38variables may also appear on the right-hand side in place of a nonterminal.
39Such a rule stands for a family of rules, in each variable is replaced by
40each possible simple nonterminal or terminal symbol.
41
42The letter $\epsilon$ denotes the empty nonterminal
43\begin{quote}
44 \syntax{$\epsilon$ ::=}
45\end{quote}
46
47The following indexed productions are used throughout the grammar, some often
48enough that they deserve special notation.
1f7d590d 49\begin{itemize}
0bc19f1c
MW
50\item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence
51 of $x$:
1f7d590d 52 \begin{quote}
0bc19f1c 53 \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$}
1f7d590d 54 \end{quote}
0bc19f1c
MW
55\item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or
56 more occurrences of $x$:
1f7d590d 57 \begin{quote}
0bc19f1c
MW
58 \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::=
59 $\epsilon$ @! <zero-or-more>$[x]$ $x$}
1f7d590d 60 \end{quote}
0bc19f1c
MW
61\item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of zero or
62 more occurrences of $x$:
1f7d590d 63 \begin{quote}
0bc19f1c 64 \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$}
1f7d590d 65 \end{quote}
0bc19f1c
MW
66\item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$
67 separated by commas:
1f7d590d 68 \begin{quote}
0bc19f1c 69 \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$}
1f7d590d
MW
70 \end{quote}
71\end{itemize}
72
68a620ab
MW
73%%%--------------------------------------------------------------------------
74\section{Lexical syntax} \label{sec:syntax.lex}
1f7d590d
MW
75
76Whitespace and comments are discarded. The remaining characters are
77collected into tokens according to the following syntax.
78
79\begin{grammar}
80<token> ::= <identifier>
81\alt <string-literal>
82\alt <char-literal>
83\alt <integer-literal>
84\alt <punctuation>
85\end{grammar}
86
87This syntax is slightly ambiguous, and is disambiguated by the \emph{maximal
88munch} rule: at each stage we take the longest sequence of characters which
89could be a token.
90
68a620ab
MW
91
92\subsection{Identifiers} \label{sec:syntax.lex.id}
1f7d590d
MW
93
94\begin{grammar}
95<identifier> ::= <id-start-char> @<id-body-char>^*
96
97<id-start-char> ::= <alpha-char> | "_"
98
99<id-body-char> ::= <id-start-char> @! <digit-char>
100
101<alpha-char> ::= "A" | "B" | \dots\ | "Z"
102\alt "a" | "b" | \dots\ | "z"
103\alt <extended-alpha-char>
104
105<digit-char> ::= "0" | <nonzero-digit-char>
106
107<nonzero-digit-char> ::= "1" | "2" $| \cdots |$ "9"
108\end{grammar}
109
110The precise definition of @<alpha-char> is left to the function
111\textsf{alpha-char-p} in the hosting Lisp system. For portability,
112programmers are encouraged to limit themselves to the standard ASCII letters.
113
114There are no reserved words at the lexical level, but the higher-level syntax
115recognizes certain identifiers as \emph{keywords} in some contexts. There is
116also an ambiguity (inherited from C) in the declaration syntax which is
117settled by distinguishing type names from other identifiers at a lexical
118level.
119
68a620ab
MW
120
121\subsection{String and character literals} \label{sec:syntax.lex.string}
1f7d590d
MW
122
123\begin{grammar}
124<string-literal> ::= "\"" @<string-literal-char>^* "\""
125
126<char-literal> ::= "'" <char-literal-char> "'"
127
128<string-literal-char> ::= any character other than "\\" or "\""
129\alt "\\" <char>
130
131<char-literal-char> ::= any character other than "\\" or "'"
132\alt "\\" <char>
133
134<char> ::= any single character
135\end{grammar}
136
137The syntax for string and character literals differs from~C. In particular,
138escape sequences such as @`\textbackslash n' are not recognized. The use
139of string and character literals in Sod, outside of C~fragments, is limited,
140and the simple syntax seems adequate. For the sake of future compatibility,
141the use of character sequences which resemble C escape sequences is
142discouraged.
143
144\subsubsection{Integer literals} \label{sec:syntax.lex.int}
145
146\begin{grammar}
147<integer-literal> ::= <decimal-integer>
148\alt <binary-integer>
149\alt <octal-integer>
150\alt <hex-integer>
151
cc0bcf39 152<decimal-integer> ::= "0" | <nonzero-digit-char> @<digit-char>^*
1f7d590d
MW
153
154<binary-integer> ::= "0" @("b"|"B"@) @<binary-digit-char>^+
155
156<binary-digit-char> ::= "0" | "1"
157
158<octal-integer> ::= "0" @["o"|"O"@] @<octal-digit-char>^+
159
160<octal-digit-char> ::= "0" | "1" $| \cdots |$ "7"
161
162<hex-integer> ::= "0" @("x"|"X"@) @<hex-digit-char>^+
163
164<hex-digit-char> ::= <digit-char>
165\alt "A" | "B" | "C" | "D" | "E" | "F"
166\alt "a" | "b" | "c" | "d" | "e" | "f"
167\end{grammar}
168
169Sod understands only integers, not floating-point numbers; its integer syntax
170goes slightly beyond C in allowing a @`0o' prefix for octal and @`0b' for
171binary. However, length and signedness indicators are not permitted.
172
68a620ab
MW
173
174\subsection{Punctuation} \label{sec:syntax.lex.punct}
1f7d590d
MW
175
176\begin{grammar}
177<punctuation> ::= any nonalphanumeric character other than "_", "\"" or "'"
178\end{grammar}
179
68a620ab
MW
180
181\subsection{Comments} \label{sec:syntax.lex.comment}
1f7d590d
MW
182
183\begin{grammar}
184<comment> ::= <block-comment>
185\alt <line-comment>
186
187<block-comment> ::=
188 "/*"
189 @<not-star>^* @(@<star>^+ <not-star-or-slash> @<not-star>^*@)^*
190 @<star>^*
191 "*/"
192
193<star> ::= "*"
194
195<not-star> ::= any character other than "*"
196
197<not-star-or-slash> ::= any character other than "*" or "/"
198
199<line-comment> ::= "//" @<not-newline>^* <newline>
200
201<newline> ::= a newline character
202
203<not-newline> ::= any character other than newline
204\end{grammar}
205
206Comments are exactly as in C99: both traditional block comments `\texttt{/*}
207\dots\ \texttt{*/}' and \Cplusplus-style `\texttt{//} \dots' comments are
208permitted and ignored.
209
68a620ab
MW
210
211\subsection{Special nonterminals} \label{sec:syntax.lex.special}
1f7d590d
MW
212
213Aside from the lexical syntax presented above (\xref{sec:lexical-syntax}),
214two special nonterminals occur in the module syntax.
215
68a620ab 216\subsubsection{S-expressions}
1f7d590d
MW
217\begin{grammar}
218<s-expression> ::= an S-expression, as parsed by the Lisp reader
219\end{grammar}
220
221When an S-expression is expected, the Sod parser simply calls the host Lisp
68a620ab
MW
222system's @|read| function. Sod modules are permitted to modify the read
223table to extend the S-expression syntax.
1f7d590d
MW
224
225S-expressions are self-delimiting, so no end-marker is needed.
226
68a620ab 227\subsubsection{C fragments}
1f7d590d
MW
228\begin{grammar}
229<c-fragment> ::= a sequence of C tokens, with matching brackets
230\end{grammar}
231
232Sequences of C code are simply stored and written to the output unchanged
233during translation. They are read using a simple scanner which nonetheless
234understands C comments and string and character literals.
235
236A C fragment is terminated by one of a small number of delimiter characters
237determined by the immediately surrounding context -- usually a closing brace
238or bracket. The first such delimiter character which is not enclosed in
239brackets, braces or parenthesis ends the fragment.
240
68a620ab
MW
241%%%--------------------------------------------------------------------------
242\section{Module syntax} \label{sec:syntax.module}
1f7d590d
MW
243
244\begin{grammar}
245<module> ::= @<definition>^*
246
247<definition> ::= <import-definition>
248\alt <load-definition>
249\alt <lisp-definition>
250\alt <code-definition>
251\alt <typename-definition>
252\alt <class-definition>
253\end{grammar}
254
68a620ab
MW
255A @<module> is the top-level syntactic item. A module consists of a sequence
256of definitions.
1f7d590d 257
68a620ab 258\subsection{Simple definitions} \label{sec:syntax.module.simple}
1f7d590d 259
68a620ab 260\subsubsection{Importing modules}
1f7d590d
MW
261\begin{grammar}
262<import-definition> ::= "import" <string> ";"
263\end{grammar}
264
265The module named @<string> is processed and its definitions made available.
266
267A search is made for a module source file as follows.
268\begin{itemize}
269\item The module name @<string> is converted into a filename by appending
270 @`.sod', if it has no extension already.\footnote{%
271 Technically, what happens is \textsf{(merge-pathnames name (make-pathname
272 :type "SOD" :case :common))}, so exactly what this means varies
273 according to the host system.} %
274\item The file is looked for relative to the directory containing the
275 importing module.
276\item If that fails, then the file is looked for in each directory on the
277 module search path in turn.
278\item If the file still isn't found, an error is reported and the import
279 fails.
280\end{itemize}
281At this point, if the file has previously been imported, nothing further
282happens.\footnote{%
283 This check is done using \textsf{truename}, so it should see through simple
284 tricks like symbolic links. However, it may be confused by fancy things
285 like bind mounts and so on.} %
286
287Recursive imports, either direct or indirect, are an error.
288
68a620ab 289\subsubsection{Loading extensions}
1f7d590d
MW
290\begin{grammar}
291<load-definition> ::= "load" <string> ";"
292\end{grammar}
293
294The Lisp file named @<string> is loaded and evaluated.
295
296A search is made for a Lisp source file as follows.
297\begin{itemize}
298\item The name @<string> is converted into a filename by appending @`.lisp',
299 if it has no extension already.\footnote{%
300 Technically, what happens is \textsf{(merge-pathnames name (make-pathname
301 :type "LISP" :case :common))}, so exactly what this means varies
302 according to the host system.} %
303\item A search is then made in the same manner as for module imports
304 (\xref{sec:syntax-module}).
305\end{itemize}
306If the file is found, it is loaded using the host Lisp's \textsf{load}
307function.
308
309Note that Sod doesn't attempt to compile Lisp files, or even to look for
310existing compiled files. The right way to package a substantial extension to
311the Sod translator is to provide the extension as a standard ASDF system (or
312similar) and leave a dropping @"foo-extension.lisp" in the module path saying
313something like
314\begin{quote}
315 \textsf{(asdf:load-system :foo-extension)}
316\end{quote}
317which will arrange for the extension to be compiled if necessary.
318
319(This approach means that the language doesn't need to depend on any
320particular system definition facility. It's bad enough already that it
321depends on Common Lisp.)
322
68a620ab 323\subsubsection{Lisp escapes}
1f7d590d
MW
324\begin{grammar}
325<lisp-definition> ::= "lisp" <s-expression> ";"
326\end{grammar}
327
328The @<s-expression> is evaluated immediately. It can do anything it likes.
329
eae50115
MW
330\begin{boxy}[Warning!]
331 This means that hostile Sod modules are a security hazard. Lisp code can
332 read and write files, start other programs, and make network connections.
333 Don't install Sod modules from sources that you don't trust.\footnote{%
334 Presumably you were going to run the corresponding code at some point, so
335 this isn't as unusually scary as it sounds. But please be careful.} %
336\end{boxy}
1f7d590d 337
68a620ab 338\subsubsection{Declaring type names}
1f7d590d
MW
339\begin{grammar}
340<typename-definition> ::=
ea08dc56 341 "typename" <list>$[\mbox{@<identifier>}]$ ";"
1f7d590d
MW
342\end{grammar}
343
344Each @<identifier> is declared as naming a C type. This is important because
345the C type syntax -- which Sod uses -- is ambiguous, and disambiguation is
346done by distinguishing type names from other identifiers.
347
348Don't declare class names using @"typename"; use @"class" forward
349declarations instead.
350
68a620ab
MW
351
352\subsection{Literal code} \label{sec:syntax.module.literal}
1f7d590d
MW
353
354\begin{grammar}
355<code-definition> ::=
4fc52153 356 "code" <identifier> ":" <item-name> @[<constraints>@]
1f7d590d
MW
357 "{" <c-fragment> "}"
358
ea08dc56 359<constraints> ::= "[" <list>$[\mbox{@<constraint>}]$ "]"
1f7d590d 360
4fc52153
MW
361<constraint> ::= @<item-name>^+
362
363<item-name> ::= <identifier> @! "(" @<identifier>^+ ")"
1f7d590d
MW
364\end{grammar}
365
366The @<c-fragment> will be output unchanged to one of the output files.
367
368The first @<identifier> is the symbolic name of an output file. Predefined
369output file names are @"c" and @"h", which are the implementation code and
370header file respectively; other output files can be defined by extensions.
371
4fc52153
MW
372Output items are named with a sequence of identifiers, separated by
373whitespace, and enclosed in parentheses. As an abbreviation, a name
374consisting of a single identifier may be written as just that identifier,
375without the parentheses.
1f7d590d
MW
376
377The @<constraints> provide a means for specifying where in the output file
378the output item should appear. (Note the two kinds of square brackets shown
379in the syntax: square brackets must appear around the constraints if they are
380present, but that they may be omitted.) Each comma-separated @<constraint>
4fc52153
MW
381is a sequence of names of output items, and indicates that the output items
382must appear in the order given -- though the translator is free to insert
383additional items in between them. (The particular output items needn't be
384defined already -- indeed, they needn't be defined ever.)
1f7d590d
MW
385
386There is a predefined output item @"includes" in both the @"c" and @"h"
387output files which is a suitable place for inserting @"\#include"
388preprocessor directives in order to declare types and functions for use
389elsewhere in the generated output files.
390
1f7d590d 391
68a620ab 392\subsection{Property sets} \label{sec:syntax.module.properties}
1f7d590d 393\begin{grammar}
ea08dc56 394<properties> ::= "[" <list>$[\mbox{@<property>}]$ "]"
1f7d590d
MW
395
396<property> ::= <identifier> "=" <expression>
397\end{grammar}
398
399Property sets are a means for associating miscellaneous information with
400classes and related items. By using property sets, additional information
401can be passed to extensions without the need to introduce idiosyncratic
402syntax.
403
404A property has a name, given as an @<identifier>, and a value computed by
405evaluating an @<expression>. The value can be one of a number of types,
406though the only operators currently defined act on integer values only.
407
68a620ab 408\subsubsection{The expression evaluator}
1f7d590d
MW
409\begin{grammar}
410<expression> ::= <term> | <expression> "+" <term> | <expression> "-" <term>
411
412<term> ::= <factor> | <term> "*" <factor> | <term> "/" <factor>
413
414<factor> ::= <primary> | "+" <factor> | "-" <factor>
415
416<primary> ::=
417 <integer-literal> | <string-literal> | <char-literal> | <identifier>
418\alt "?" <s-expression>
419\alt "(" <expression> ")"
420\end{grammar}
421
422The arithmetic expression syntax is simple and standard; there are currently
423no bitwise, logical, or comparison operators.
424
425A @<primary> expression may be a literal or an identifier. Note that
426identifiers stand for themselves: they \emph{do not} denote values. For more
427fancy expressions, the syntax
428\begin{quote}
429 @"?" @<s-expression>
430\end{quote}
431causes the @<s-expression> to be evaluated using the Lisp \textsf{eval}
432function.
433%%% FIXME crossref to extension docs
434
68a620ab
MW
435
436\subsection{C types} \label{sec:syntax.module.types}
1f7d590d
MW
437
438Sod's syntax for C types closely mirrors the standard C syntax. A C type has
439two parts: a sequence of @<declaration-specifier>s and a @<declarator>. In
440Sod, a type must contain at least one @<declaration-specifier> (i.e.,
441`implicit @"int"' is forbidden), and storage-class specifiers are not
442recognized.
443
68a620ab 444\subsubsection{Declaration specifiers}
1f7d590d
MW
445\begin{grammar}
446<declaration-specifier> ::= <type-name>
447\alt "struct" <identifier> | "union" <identifier> | "enum" <identifier>
448\alt "void" | "char" | "int" | "float" | "double"
449\alt "short" | "long"
450\alt "signed" | "unsigned"
2e01fd8b
MW
451\alt "bool" | "_Bool"
452\alt "imaginary" | "_Imaginary" | "complex" | "_Complex"
1f7d590d 453\alt <qualifier>
db56b1d3 454\alt <storage-specifier>
ae0f15ee 455\alt <atomic-type>
1f7d590d 456
ae0f15ee
MW
457<qualifier> ::= <atomic> | "const" | "volatile" | "restrict"
458
459<atomic-type> ::=
460 <atomic> "(" @<declaration-specifier>^+ <abstract-declarator> ")"
461
462<atomic> ::= "atomic" | "_Atomic"
1f7d590d 463
db56b1d3
MW
464<storage-specifier> ::= <alignas> "(" <c-fragment> ")"
465
466<alignas> ::= "alignas" "_Alignas"
1f7d590d
MW
467
468<type-name> ::= <identifier>
469\end{grammar}
470
471A @<type-name> is an identifier which has been declared as being a type name,
2e01fd8b
MW
472using the @"typename" or @"class" definitions. The following type names are
473defined in the built-in module.
474\begin{itemize}
475\item @"va_list"
476\item @"size_t"
477\item @"ptrdiff_t"
478\item @"wchar_t"
479\end{itemize}
1f7d590d
MW
480
481Declaration specifiers may appear in any order. However, not all
482combinations are permitted. A declaration specifier must consist of zero or
db56b1d3
MW
483more @<qualifier>s, zero or more @<storage-specifier>s, and one of the
484following, up to reordering.
1f7d590d
MW
485\begin{itemize}
486\item @<type-name>
ae0f15ee 487\item @<atomic-type>
1f7d590d
MW
488\item @"struct" @<identifier>, @"union" @<identifier>, @"enum" @<identifier>
489\item @"void"
2e01fd8b 490\item @"_Bool", @"bool"
1f7d590d
MW
491\item @"char", @"unsigned char", @"signed char"
492\item @"short", @"unsigned short", @"signed short"
493\item @"short int", @"unsigned short int", @"signed short int"
494\item @"int", @"unsigned int", @"signed int", @"unsigned", @"signed"
495\item @"long", @"unsigned long", @"signed long"
496\item @"long int", @"unsigned long int", @"signed long int"
497\item @"long long", @"unsigned long long", @"signed long long"
498\item @"long long int", @"unsigned long long int", @"signed long long int"
499\item @"float", @"double", @"long double"
2e01fd8b
MW
500\item @"float _Imaginary", @"double _Imaginary", @"long double _Imaginary"
501\item @"float imaginary", @"double imaginary", @"long double imaginary"
502\item @"float _Complex", @"double _Complex", @"long double _Complex"
503\item @"float complex", @"double complex", @"long double complex"
1f7d590d
MW
504\end{itemize}
505All of these have their usual C meanings.
506
68a620ab 507\subsubsection{Declarators}
1f7d590d 508\begin{grammar}
43073476 509<declarator>$[k, a]$ ::= @<pointer>^* <primary-declarator>$[k, a]$
1f7d590d 510
43073476
MW
511<primary-declarator>$[k, a]$ ::= $k$
512\alt "(" <primary-declarator>$[k, a]$ ")"
513\alt <primary-declarator>$[k, a]$ @<declarator-suffix>$[a]$
1f7d590d
MW
514
515<pointer> ::= "*" @<qualifier>^*
516
43073476
MW
517<declarator-suffix>$[a]$ ::= "[" <c-fragment> "]"
518\alt "(" $a$ ")"
1f7d590d 519
ea08dc56
MW
520<argument-list> ::= $\epsilon$ | "..."
521\alt <list>$[\mbox{@<argument>}]$ @["," "..."@]
1f7d590d
MW
522
523<argument> ::= @<declaration-specifier>^+ <argument-declarator>
524
f64eb323 525<abstract-declarator> ::= <declarator>$[\epsilon, \mbox{@<argument-list>}]$
ae0f15ee 526
ea08dc56 527<argument-declarator> ::= <declarator>$[\mbox{@<identifier> @! $\epsilon$}]$
43073476
MW
528<argument-declarator> ::=
529 <declarator>$[\mbox{@<identifier> @! $\epsilon$}, \mbox{@<argument-list>}]$
1f7d590d 530
43073476
MW
531<simple-declarator> ::=
532 <declarator>$[\mbox{@<identifier>}, \mbox{@<argument-list>}]$
1f7d590d
MW
533\end{grammar}
534
535The declarator syntax is taken from C, but with some differences.
536\begin{itemize}
537\item Array dimensions are uninterpreted @<c-fragments>, terminated by a
538 closing square bracket. This allows array dimensions to contain arbitrary
539 constant expressions.
540\item A declarator may have either a single @<identifier> at its centre or a
541 pair of @<identifier>s separated by a @`.'; this is used to refer to
542 slots or messages defined in superclasses.
543\end{itemize}
544The remaining differences are (I hope) a matter of presentation rather than
545substance.
546
43073476
MW
547There is additional syntax to support messages and methods which accept
548keyword arguments.
549
550\begin{grammar}
551<keyword-argument> ::= <argument> @["=" <c-fragment>@]
552
553<keyword-argument-list> ::=
554 @[<list>$[\mbox{@<argument>}]$@]
555 "?" @[<list>$[\mbox{@<keyword-argument>}]$@]
556
557<method-argument-list> ::= <argument-list> @! <keyword-argument-list>
558
559<dotted-name> ::= <identifier> "." <identifier>
560
561<keyword-declarator>$[k]$ ::=
562 <declarator>$[k, \mbox{@<method-argument-list>}]$
563\end{grammar}
564
68a620ab
MW
565
566\subsection{Class definitions} \label{sec:syntax.module.class}
1f7d590d
MW
567
568\begin{grammar}
569<class-definition> ::= <class-forward-declaration>
570\alt <full-class-definition>
571\end{grammar}
572
68a620ab 573\subsubsection{Forward declarations}
1f7d590d
MW
574\begin{grammar}
575<class-forward-declaration> ::= "class" <identifier> ";"
576\end{grammar}
577
578A @<class-forward-declaration> informs Sod that an @<identifier> will be used
579to name a class which is currently undefined. Forward declarations are
580necessary in order to resolve certain kinds of circularity. For example,
581\begin{listing}
582class Sub;
583
584class Super : SodObject {
585 Sub *sub;
586};
587
588class Sub : Super {
589 /* ... */
590};
591\end{listing}
592
68a620ab 593\subsubsection{Full class definitions}
1f7d590d
MW
594\begin{grammar}
595<full-class-definition> ::=
596 @[<properties>@]
ea08dc56
MW
597 "class" <identifier> ":" <list>$[\mbox{@<identifier>}]$
598 "{" @<properties-class-item>^* "}"
1f7d590d 599
391c5a34
MW
600<properties-class-item> ::= @[<properties>@] <class-item>
601
602<class-item> ::= <slot-item>
603\alt <initializer-item>
b2983f35 604\alt <initarg-item>
a42893dd 605\alt <fragment-item>
1f7d590d
MW
606\alt <message-item>
607\alt <method-item>
1f7d590d
MW
608\end{grammar}
609
610A full class definition provides a complete description of a class.
611
612The first @<identifier> gives the name of the class. It is an error to
613give the name of an existing class (other than a forward-referenced class),
614or an existing type name. It is conventional to give classes `MixedCase'
615names, to distinguish them from other kinds of identifiers.
616
ea08dc56
MW
617The @<list>$[\mbox{@<identifier>}]$ names the direct superclasses for the new
618class. It is an error if any of these @<identifier>s does not name a defined
619class.
1f7d590d
MW
620
621The @<properties> provide additional information. The standard class
622properties are as follows.
623\begin{description}
624\item[@"lisp_class"] The name of the Lisp class to use within the translator
625 to represent this class. The property value must be an identifier; the
626 default is @"sod_class". Extensions may define classes with additional
627 behaviour, and may recognize additional class properties.
628\item[@"metaclass"] The name of the Sod metaclass for this class. In the
629 generated code, a class is itself an instance of another class -- its
630 \emph{metaclass}. The metaclass defines which slots the class will have,
631 which messages it will respond to, and what its behaviour will be when it
632 receives them. The property value must be an identifier naming a defined
633 subclass of @"SodClass". The default metaclass is @"SodClass".
634 %%% FIXME xref to theory
635\item[@"nick"] A nickname for the class, to be used to distinguish it from
636 other classes in various limited contexts. The property value must be an
637 identifier; the default is constructed by forcing the class name to
638 lower-case.
639\end{description}
640
641The class body consists of a sequence of @<class-item>s enclosed in braces.
642These items are discussed on the following sections.
643
68a620ab 644\subsubsection{Slot items}
1f7d590d
MW
645\begin{grammar}
646<slot-item> ::=
ea08dc56 647 @<declaration-specifier>^+ <list>$[\mbox{@<init-declarator>}]$ ";"
1f7d590d 648
0bc19f1c 649<init-declarator> ::= <simple-declarator> @["=" <initializer>@]
1f7d590d
MW
650\end{grammar}
651
652A @<slot-item> defines one or more slots. All instances of the class and any
653subclass will contain these slot, with the names and types given by the
654@<declaration-specifiers> and the @<declarators>. Slot declarators may not
bc7dff5c 655contain dotted names.
1f7d590d
MW
656
657It is not possible to declare a slot with function type: such an item is
658interpreted as being a @<message-item> or @<method-item>. Pointers to
659functions are fine.
660
661An @<initializer>, if present, is treated as if a separate
662@<initializer-item> containing the slot name and initializer were present.
663For example,
664\begin{listing}
665[nick = eg]
666class Example : Super {
667 int foo = 17;
668};
669\end{listing}
670means the same as
671\begin{listing}
672[nick = eg]
673class Example : Super {
674 int foo;
675 eg.foo = 17;
676};
677\end{listing}
678
68a620ab 679\subsubsection{Initializer items}
1f7d590d 680\begin{grammar}
391c5a34 681<initializer-item> ::= @["class"@] <list>$[\mbox{@<slot-initializer>}]$ ";"
1f7d590d 682
b2983f35 683<slot-initializer> ::= <dotted-name> @["=" <initializer>@]
1f7d590d 684
a888e3ac 685<initializer> :: <c-fragment>
1f7d590d
MW
686\end{grammar}
687
688An @<initializer-item> provides an initial value for one or more slots. If
689prefixed by @"class", then the initial values are for class slots (i.e.,
690slots of the class object itself); otherwise they are for instance slots.
691
bc7dff5c
MW
692The first component of the @<dotted-name> must be the nickname of one of the
693class's superclasses (including itself); the second must be the name of a
694slot defined in that superclass.
1f7d590d 695
b2983f35
MW
696An @|initarg| property may be set on an instance slot initializer (or a
697direct slot definition). See \xref{sec:concepts.lifecycle.birth} for the
698details. An initializer item must have either an @|initarg| property, or an
699initializer expression, or both.
700
701Each class may define at most one initializer item with an explicit
702initializer expression for a given slot.
703
704\subsubsection{Initarg items}
705\begin{grammar}
706<initarg-item> ::=
707 "initarg"
708 @<declaration-specifier>^+
709 <list>$[\mbox{@<init-declarator>}]$ ";"
710\end{grammar}
711
a42893dd
MW
712\subsubsection{Fragment items}
713\begin{grammar}
714<fragment-item> ::= <fragment-kind> "{" <c-fragment> "}"
715
716<fragment-kind> ::= "init" | "teardown"
717\end{grammar}
718
68a620ab 719\subsubsection{Message items}
1f7d590d
MW
720\begin{grammar}
721<message-item> ::=
391c5a34
MW
722 @<declaration-specifier>^+
723 <keyword-declarator>$[\mbox{@<identifier>}]$
724 @[<method-body>@]
1f7d590d
MW
725\end{grammar}
726
68a620ab 727\subsubsection{Method items}
1f7d590d
MW
728\begin{grammar}
729<method-item> ::=
391c5a34
MW
730 @<declaration-specifier>^+
731 <keyword-declarator>$[\mbox{@<dotted-name>}]$
ea08dc56 732 <method-body>
1f7d590d
MW
733
734<method-body> ::= "{" <c-fragment> "}" | "extern" ";"
735\end{grammar}
736
1f7d590d
MW
737%%%----- That's all, folks --------------------------------------------------
738
739%%% Local variables:
740%%% mode: LaTeX
741%%% TeX-master: "sod.tex"
742%%% TeX-PDF-mode: t
743%%% End: