| 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 | |
| 94 | \subsection{Empty production} |
| 95 | |
| 96 | The letter $\epsilon$ denotes the empty nonterminal |
| 97 | \begin{quote} |
| 98 | \syntax{$\epsilon$ ::=} |
| 99 | \end{quote} |
| 100 | |
| 101 | |
| 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} |
| 107 | \syntax{$\alpha$ @($\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$@) $\gamma$} |
| 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} |
| 116 | \syntax{$b$ ::= $\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$} |
| 117 | \end{quote} |
| 118 | where $b$ is a new nonterminal symbol. |
| 119 | |
| 120 | Given the indexed-nonterminal notation described below, one might consider a |
| 121 | group \syntax{@($\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$@)} equivalent |
| 122 | to \syntax{<group>@[$\beta_1$ @! $\beta_2$ $| \cdots |$ $\beta_n$@]}, where |
| 123 | \begin{quote} |
| 124 | \syntax{<group>@[$x$@] ::= $x$} |
| 125 | \end{quote} |
| 126 | |
| 127 | |
| 128 | \subsection{Indexed nonterminals} |
| 129 | |
| 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. |
| 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. |
| 137 | |
| 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 |
| 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}$@]} |
| 144 | means exactly the same as \syntax{$x$@[$a_1, \ldots, a_n$@]} with the |
| 145 | additional rules |
| 146 | \begin{quote} |
| 147 | \syntax{$a_1$ ::= $\alpha_1^1$ @! $\alpha_1^2$ $| \cdots |$ $\alpha_1^{m_1}$} \\* |
| 148 | \hbox{}\qquad $\vdots$ \\* |
| 149 | \syntax{$a_n$ ::= $\alpha_n^1$ @! $\alpha_n^2$ $| \cdots |$ $\alpha_1^{m_n}$} |
| 150 | \end{quote} |
| 151 | where $a_1$, \ldots, $a_n$ are new nonterminal symbols. |
| 152 | |
| 153 | |
| 154 | \subsection{Common indexed productions} |
| 155 | |
| 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} |
| 162 | \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$} |
| 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]$ ::= |
| 168 | $\epsilon$ @! <zero-or-more>$[x]$ $x$} |
| 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} |
| 178 | \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$} |
| 179 | \end{quote} |
| 180 | \end{itemize} |
| 181 | |
| 182 | %%%-------------------------------------------------------------------------- |
| 183 | |
| 184 | |
| 185 | %% properties |
| 186 | |
| 187 | %%%----- That's all, folks -------------------------------------------------- |