mdw@git.distorted.org.uk Git - sod/blob - doc/refintro.tex

   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{Indexed nonterminals}
 103
 104 Anywhere a simple nonterminal name $x$ may appear in the grammar, an
 105 \emph{indexed} nonterminal $x[a_1, \ldots, a_n]$ may also appear.  On the
 106 left-hand side of a production rule, the indices $a_1$, \ldots, $a_n$ are
 107 variables which vary over all nonterminal and terminal symbols, and the
 108 variables may also appear on the right-hand side in place of a nonterminal.
 109 Such a rule stands for a family of rules, in which each variable is replaced
 110 by each possible simple nonterminal or terminal symbol.
 111
 112 As a notational convenience, where an indexed nonterminal appears on the
 113 right-hand side of a production rule, each actual argument may be a sequence
 114 of alternative right-hand sides, separated by `$|$', rather than a a simple
 115 terminal or nonterminal symbol.  A complex indexing of this form, say
 116 \syntax{$x$@[$\alpha_1^1$ @! $\alpha_1^2$ $| \cdots |$ $\alpha_1^{m_1},
 117 \ldots,$ $\alpha_n^1$ @! $\alpha_n^2$ $| \cdots |$ $\alpha_n^{m_n}$@]}
 118 means exactly the same as \syntax{$x$@[$a_1, \ldots, a_n$@]} with the
 119 additional rules
 120 \begin{quote}
 121   \syntax{$a_1$ ::= $\alpha_1^1$ @! $\alpha_1^2$ $| \cdots |$ $\alpha_1^{m_1}$} \\*
 122   \hbox{}\qquad $\vdots$ \\*
 123   \syntax{$a_n$ ::= $\alpha_n^1$ @! $\alpha_n^2$ $| \cdots |$ $\alpha_1^{m_n}$}
 124 \end{quote}
 125 where $a_1$, \ldots, $a_n$ are new nonterminal symbols.
 126
 127
 128 \subsection{Common indexed productions}
 129
 130 The following indexed productions are used throughout the grammar, some often
 131 enough that they deserve special notation.
 132 \begin{itemize}
 133 \item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence
 134   of $x$:
 135   \begin{quote}
 136     \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ @! $x$}
 137   \end{quote}
 138 \item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or
 139   more occurrences of $x$:
 140   \begin{quote}
 141     \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::=
 142       $\epsilon$ @! <zero-or-more>$[x]$ $x$}
 143   \end{quote}
 144 \item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of one or
 145   more occurrences of $x$:
 146   \begin{quote}
 147     \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$}
 148   \end{quote}
 149 \item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$
 150   separated by commas:
 151   \begin{quote}
 152     \syntax{<list>$[x]$ ::= $x$ @! <list>$[x]$ "," $x$}
 153   \end{quote}
 154 \end{itemize}
 155
 156 %%%--------------------------------------------------------------------------
 157
 158
 159 %% properties
 160
 161 %%%----- That's all, folks --------------------------------------------------