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 | ||
e95c78ed MW |
93 | |
94 | \subsection{Empty production} | |
95 | ||
f736d657 MW |
96 | The letter $\epsilon$ denotes the empty nonterminal |
97 | \begin{quote} | |
98 | \syntax{$\epsilon$ ::=} | |
99 | \end{quote} | |
100 | ||
e95c78ed | 101 | |
e5c630fb MW |
102 | \subsection{Parentheses} |
103 | ||
104 | Parentheses are used for grouping of alternatives within the right-hand side | |
105 | of a production rule. Specifically, a right-hand side | |
106 | \begin{quote} | |
b04739d0 | 107 | \syntax{$\alpha$ @($\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@) $\gamma$} |
e5c630fb MW |
108 | \end{quote} |
109 | where $\alpha$, $\beta_i$, and $\gamma$ are any sequence of nonterminal | |
110 | symbols or parenthesized groups, is equivalent to the right-hand side | |
111 | \begin{quote} | |
112 | \syntax{$\alpha$ $b$ $\gamma$} | |
113 | \end{quote} | |
114 | together with the new production | |
115 | \begin{quote} | |
b04739d0 | 116 | \syntax{$b$ ::= $\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$} |
e5c630fb MW |
117 | \end{quote} |
118 | where $b$ is a new nonterminal symbol. | |
119 | ||
120 | Given the indexed-nonterminal notation described below, one might consider a | |
b04739d0 MW |
121 | group \syntax{@($\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@)} equivalent to |
122 | \syntax{<group>@[$\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@]}, where | |
e5c630fb MW |
123 | \begin{quote} |
124 | \syntax{<group>@[$x$@] ::= $x$} | |
125 | \end{quote} | |
126 | ||
127 | ||
e95c78ed MW |
128 | \subsection{Indexed nonterminals} |
129 | ||
7292d6e1 MW |
130 | Anywhere a simple nonterminal name $x$ may appear in the grammar, an |
131 | \emph{indexed} nonterminal $x[a_1, \ldots, a_n]$ may also appear. On the | |
132 | left-hand side of a production rule, the indices $a_1$, \ldots, $a_n$ are | |
133 | variables which vary over all nonterminal and terminal symbols, and the | |
134 | variables may also appear on the right-hand side in place of a nonterminal. | |
b55c7856 MW |
135 | Such a rule stands for a family of rules, in which each variable is replaced |
136 | by each possible simple nonterminal or terminal symbol. | |
7292d6e1 | 137 | |
dfd65951 MW |
138 | As a notational convenience, where an indexed nonterminal appears on the |
139 | right-hand side of a production rule, each actual argument may be a sequence | |
140 | of alternative right-hand sides, separated by `$|$', rather than a a simple | |
141 | terminal or nonterminal symbol. A complex indexing of this form, say | |
b04739d0 MW |
142 | \syntax{$x$@[$\alpha_1^1$ | $\alpha_1^2$ | $\cdots$ | $\alpha_1^{m_1}, |
143 | \ldots,$ $\alpha_n^1$ | $\alpha_n^2$ | $\cdots$ | $\alpha_n^{m_n}$@]} means | |
144 | exactly the same as \syntax{$x$@[$a_1, \ldots, a_n$@]} with the additional | |
145 | rules | |
dfd65951 | 146 | \begin{quote} |
b04739d0 | 147 | \syntax{$a_1$ ::= $\alpha_1^1$ | $\alpha_1^2$ | $\cdots$ | $\alpha_1^{m_1}$} \\* |
48c123c9 | 148 | \hbox{}\qquad $\vdots$ \\* |
b04739d0 | 149 | \syntax{$a_n$ ::= $\alpha_n^1$ | $\alpha_n^2$ | $\cdots$ | $\alpha_1^{m_n}$} |
dfd65951 MW |
150 | \end{quote} |
151 | where $a_1$, \ldots, $a_n$ are new nonterminal symbols. | |
152 | ||
e95c78ed MW |
153 | |
154 | \subsection{Common indexed productions} | |
155 | ||
7292d6e1 MW |
156 | The following indexed productions are used throughout the grammar, some often |
157 | enough that they deserve special notation. | |
158 | \begin{itemize} | |
159 | \item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence | |
160 | of $x$: | |
161 | \begin{quote} | |
b04739d0 | 162 | \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ | $x$} |
7292d6e1 MW |
163 | \end{quote} |
164 | \item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or | |
165 | more occurrences of $x$: | |
166 | \begin{quote} | |
167 | \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::= | |
b04739d0 | 168 | $\epsilon$ | <zero-or-more>$[x]$ $x$} |
7292d6e1 MW |
169 | \end{quote} |
170 | \item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of one or | |
171 | more occurrences of $x$: | |
172 | \begin{quote} | |
173 | \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$} | |
174 | \end{quote} | |
175 | \item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$ | |
176 | separated by commas: | |
177 | \begin{quote} | |
b04739d0 | 178 | \syntax{<list>$[x]$ ::= $x$ | <list>$[x]$ "," $x$} |
7292d6e1 MW |
179 | \end{quote} |
180 | \end{itemize} | |
181 | ||
182 | %%%-------------------------------------------------------------------------- | |
183 | ||
184 | ||
185 | %% properties | |
186 | ||
187 | %%%----- That's all, folks -------------------------------------------------- |