Commit | Line | Data |
---|---|---|
7292d6e1 MW |
1 | %%% -*-latex-*- |
2 | %%% | |
3 | %%% Introduction to the reference section | |
4 | %%% | |
5 | %%% (c) 2016 Straylight/Edgeware | |
6 | %%% | |
7 | ||
8 | %%%----- Licensing notice --------------------------------------------------- | |
9 | %%% | |
10 | %%% This file is part of the Sensible Object Design, an object system for C. | |
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{Introduction} \label{ch:refintro} | |
27 | ||
28 | This part describes Sod in detail, from the perspective of a developer using | |
29 | the system to write their own programs. This task is complicated by the fact | |
30 | that Sod is intrinsically open-ended and flexible: it allows programmers to | |
31 | extend and alter its behaviour arbitrarily. As a result, pretty much every | |
32 | statement made in this part must be hedged around with disclaimers that it | |
33 | might not be true if Sod has been extended in a particular way. Rather than | |
34 | mention this repeatedly, this part will describe Sod as it is provided, | |
35 | rather than as it might be when modified. | |
36 | ||
37 | \Xref{p:lisp} describes Sod's internal API and protocols. A reader | |
38 | interested in understanding the design space of object systems covered by Sod | |
39 | will have to read that in order to grasp fully what the system is (and isn't) | |
40 | capable of. | |
41 | ||
42 | The following chapters in this part will describe the Sod object model, the | |
43 | syntax read by the translator, and how the two | |
44 | ||
45 | \begin{itemize} | |
46 | ||
47 | \item The remainder of this chapter describes some notational conventions | |
48 | which will be used throughout the present part, and describes various | |
49 | aspects of the \emph{module files} which the Sod translator reads. | |
50 | ||
51 | \item \Xref{ch:class} describes \emph{classes}, which are the primary | |
52 | concepts of interest in Sod. | |
53 | ||
54 | \end{itemize} | |
55 | ||
56 | %%%-------------------------------------------------------------------------- | |
57 | \section{Operational model} \label{sec:refintro.model} | |
58 | ||
59 | The Sod translator runs as a preprocessor, similar in nature to the | |
60 | traditional Unix \man{lex}{1} and \man{yacc}{1} tools. The translator reads | |
61 | a \emph{module} file containing class definitions and other information, and | |
62 | writes C~source and header files. The source files contain function | |
63 | definitions and static tables which are fed directly to a C~compiler; the | |
64 | header files contain declarations for functions and data structures, and are | |
65 | included by source files -- whether hand-written or generated by Sod -- which | |
66 | makes use of the classes defined in the module. | |
67 | ||
68 | Sod is not like \Cplusplus: it makes no attempt to `enhance' the C language | |
69 | itself. Sod module files describe classes, messages, methods, slots, and | |
70 | other kinds of object-system things, and some of these descriptions need to | |
71 | contain C code fragments, but this code is entirely uninterpreted by the Sod | |
72 | translator.\footnote{% | |
73 | As long as a code fragment broadly follows C's lexical rules, and properly | |
74 | matches parentheses, brackets, and braces, the Sod translator will copy it | |
75 | into its output unchanged. It might, in fact, be some other kind of C-like | |
76 | language, such as Objective~C or \Cplusplus. Or maybe even | |
77 | Objective~\Cplusplus, because if having an object system is good, then | |
78 | having three must be really awesome.} % | |
79 | ||
80 | The Sod translator is not a closed system. It is written in Common Lisp, and | |
81 | can load extension modules which add new input syntax, output formats, or | |
82 | altered behaviour. The interface for writing such extensions is described in | |
83 | \xref{p:lisp}. Extensions can change almost all details of the Sod object | |
84 | system, so the material in this manual must be read with this in mind: this | |
85 | manual describes the base system as provided in the distribution. | |
86 | ||
87 | %%%-------------------------------------------------------------------------- | |
88 | \section{Syntax notation} \label{sec:refintro.synnote} | |
89 | ||
90 | Fortunately, Sod is syntactically quite simple. The notation is slightly | |
91 | unusual in order to make the presentation shorter and easier to read. | |
92 | ||
93 | Anywhere a simple nonterminal name $x$ may appear in the grammar, an | |
94 | \emph{indexed} nonterminal $x[a_1, \ldots, a_n]$ may also appear. On the | |
95 | left-hand side of a production rule, the indices $a_1$, \ldots, $a_n$ are | |
96 | variables which vary over all nonterminal and terminal symbols, and the | |
97 | variables may also appear on the right-hand side in place of a nonterminal. | |
b55c7856 MW |
98 | Such a rule stands for a family of rules, in which each variable is replaced |
99 | by each possible simple nonterminal or terminal symbol. | |
7292d6e1 | 100 | |
dfd65951 MW |
101 | As a notational convenience, where an indexed nonterminal appears on the |
102 | right-hand side of a production rule, each actual argument may be a sequence | |
103 | of alternative right-hand sides, separated by `$|$', rather than a a simple | |
104 | terminal or nonterminal symbol. A complex indexing of this form, say | |
105 | $x[\alpha_1 | \beta_1 | \cdots, \ldots, \alpha_n | \beta_n | \cdots]$ means | |
106 | exactly the same as $x[a_1, \ldots, a_n]$ with the additional rules | |
107 | \begin{quote} | |
108 | \syntax{$a_1$ ::= $\alpha_1$ @! $\beta_1$ @! $\cdots$} \\ | |
109 | \hbox{}\qquad $\vdots$ \\ | |
110 | \syntax{$a_n$ ::= $\alpha_n$ @! $\beta_n$ @! $\cdots$} | |
111 | \end{quote} | |
112 | where $a_1$, \ldots, $a_n$ are new nonterminal symbols. | |
113 | ||
7292d6e1 MW |
114 | The letter $\epsilon$ denotes the empty nonterminal |
115 | \begin{quote} | |
116 | \syntax{$\epsilon$ ::=} | |
117 | \end{quote} | |
118 | ||
119 | The following indexed productions are used throughout the grammar, some often | |
120 | enough that they deserve special notation. | |
121 | \begin{itemize} | |
122 | \item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence | |
123 | of $x$: | |
124 | \begin{quote} | |
125 | \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$} | |
126 | \end{quote} | |
127 | \item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or | |
128 | more occurrences of $x$: | |
129 | \begin{quote} | |
130 | \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::= | |
131 | $\epsilon$ @! <zero-or-more>$[x]$ $x$} | |
132 | \end{quote} | |
133 | \item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of one or | |
134 | more occurrences of $x$: | |
135 | \begin{quote} | |
136 | \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$} | |
137 | \end{quote} | |
138 | \item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$ | |
139 | separated by commas: | |
140 | \begin{quote} | |
141 | \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$} | |
142 | \end{quote} | |
143 | \end{itemize} | |
144 | ||
145 | %%%-------------------------------------------------------------------------- | |
146 | ||
147 | ||
148 | %% properties | |
149 | ||
150 | %%%----- That's all, folks -------------------------------------------------- |