| 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. |
| 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. |
| 100 | |
| 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 | |
| 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 -------------------------------------------------- |