debian/changelog: Prepare for next version.

[sod] / doc / refintro.tex

%%% -*-latex-*-
%%%
%%% Introduction to the reference section
%%%
%%% (c) 2016 Straylight/Edgeware
%%%

%%%----- Licensing notice ---------------------------------------------------
%%%
%%% This file is part of the Sensible Object Design, an object system for C.
%%%
%%% SOD is free software; you can redistribute it and/or modify
%%% it under the terms of the GNU General Public License as published by
%%% the Free Software Foundation; either version 2 of the License, or
%%% (at your option) any later version.
%%%
%%% SOD is distributed in the hope that it will be useful,
%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
%%% GNU General Public License for more details.
%%%
%%% You should have received a copy of the GNU General Public License
%%% along with SOD; if not, write to the Free Software Foundation,
%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

\chapter{Introduction} \label{ch:refintro}

This part describes Sod in detail, from the perspective of a developer using
the system to write their own programs.  This task is complicated by the fact
that Sod is intrinsically open-ended and flexible: it allows programmers to
extend and alter its behaviour arbitrarily.  As a result, pretty much every
statement made in this part must be hedged around with disclaimers that it
might not be true if Sod has been extended in a particular way.  Rather than
mention this repeatedly, this part will describe Sod as it is provided,
rather than as it might be when modified.

\Xref{p:lisp} describes Sod's internal API and protocols.  A reader
interested in understanding the design space of object systems covered by Sod
will have to read that in order to grasp fully what the system is (and isn't)
capable of.

The following chapters in this part will describe the Sod object model, the
syntax read by the translator, and how the two

\begin{itemize}

\item The remainder of this chapter describes some notational conventions
  which will be used throughout the present part, and describes various
  aspects of the \emph{module files} which the Sod translator reads.

\item \Xref{ch:class} describes \emph{classes}, which are the primary
  concepts of interest in Sod.

\end{itemize}

%%%--------------------------------------------------------------------------
\section{Operational model} \label{sec:refintro.model}

The Sod translator runs as a preprocessor, similar in nature to the
traditional Unix \man{lex}{1} and \man{yacc}{1} tools.  The translator reads
a \emph{module} file containing class definitions and other information, and
writes C~source and header files.  The source files contain function
definitions and static tables which are fed directly to a C~compiler; the
header files contain declarations for functions and data structures, and are
included by source files -- whether hand-written or generated by Sod -- which
makes use of the classes defined in the module.

Sod is not like \Cplusplus: it makes no attempt to `enhance' the C language
itself.  Sod module files describe classes, messages, methods, slots, and
other kinds of object-system things, and some of these descriptions need to
contain C code fragments, but this code is entirely uninterpreted by the Sod
translator.\footnote{%
  As long as a code fragment broadly follows C's lexical rules, and properly
  matches parentheses, brackets, and braces, the Sod translator will copy it
  into its output unchanged.  It might, in fact, be some other kind of C-like
  language, such as Objective~C or \Cplusplus.  Or maybe even
  Objective~\Cplusplus, because if having an object system is good, then
  having three must be really awesome.} %

The Sod translator is not a closed system.  It is written in Common Lisp, and
can load extension modules which add new input syntax, output formats, or
altered behaviour.  The interface for writing such extensions is described in
\xref{p:lisp}.  Extensions can change almost all details of the Sod object
system, so the material in this manual must be read with this in mind: this
manual describes the base system as provided in the distribution.

%%%--------------------------------------------------------------------------
\section{Syntax notation} \label{sec:refintro.synnote}

Fortunately, Sod is syntactically quite simple.  The notation is slightly
unusual in order to make the presentation shorter and easier to read.


\subsection{Empty production}

The letter $\epsilon$ denotes the empty nonterminal
\begin{quote}
  \syntax{$\epsilon$ ::=}
\end{quote}


\subsection{Parentheses}

Parentheses are used for grouping of alternatives within the right-hand side
of a production rule.  Specifically, a right-hand side
\begin{quote}
  \syntax{$\alpha$ @($\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@) $\gamma$}
\end{quote}
where $\alpha$, $\beta_i$, and $\gamma$ are any sequence of nonterminal
symbols or parenthesized groups, is equivalent to the right-hand side
\begin{quote}
  \syntax{$\alpha$ $b$ $\gamma$}
\end{quote}
together with the new production
\begin{quote}
  \syntax{$b$ ::= $\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$}
\end{quote}
where $b$ is a new nonterminal symbol.

Given the indexed-nonterminal notation described below, one might consider a
group \syntax{@($\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@)} equivalent to
\syntax{<group>@[$\beta_1$ | $\beta_2$ | $\cdots$ | $\beta_n$@]}, where
\begin{quote}
  \syntax{<group>@[$x$@] ::= $x$}
\end{quote}


\subsection{Indexed nonterminals}

Anywhere a simple nonterminal name $x$ may appear in the grammar, an
\emph{indexed} nonterminal $x[a_1, \ldots, a_n]$ may also appear.  On the
left-hand side of a production rule, the indices $a_1$, \ldots, $a_n$ are
variables which vary over all nonterminal and terminal symbols, and the
variables may also appear on the right-hand side in place of a nonterminal.
Such a rule stands for a family of rules, in which each variable is replaced
by each possible simple nonterminal or terminal symbol.

As a notational convenience, where an indexed nonterminal appears on the
right-hand side of a production rule, each actual argument may be a sequence
of alternative right-hand sides, separated by `$|$', rather than a a simple
terminal or nonterminal symbol.  A complex indexing of this form, say
\syntax{$x$@[$\alpha_1^1$ | $\alpha_1^2$ | $\cdots$ | $\alpha_1^{m_1},
\ldots,$ $\alpha_n^1$ | $\alpha_n^2$ | $\cdots$ | $\alpha_n^{m_n}$@]} means
exactly the same as \syntax{$x$@[$a_1, \ldots, a_n$@]} with the additional
rules
\begin{quote}
  \syntax{$a_1$ ::= $\alpha_1^1$ | $\alpha_1^2$ | $\cdots$ | $\alpha_1^{m_1}$} \\*
  \hbox{}\qquad $\vdots$ \\*
  \syntax{$a_n$ ::= $\alpha_n^1$ | $\alpha_n^2$ | $\cdots$ | $\alpha_1^{m_n}$}
\end{quote}
where $a_1$, \ldots, $a_n$ are new nonterminal symbols.


\subsection{Common indexed productions}

The following indexed productions are used throughout the grammar, some often
enough that they deserve special notation.
\begin{itemize}
\item @[$x$@] abbreviates @<optional>$[x]$, denoting an optional occurrence
  of $x$:
  \begin{quote}
    \syntax{@[$x$@] ::= <optional>$[x]$ ::= $\epsilon$ | $x$}
  \end{quote}
\item $x^*$ abbreviates @<zero-or-more>$[x]$, denoting a sequence of zero or
  more occurrences of $x$:
  \begin{quote}
    \syntax{$x^*$ ::= <zero-or-more>$[x]$ ::=
      $\epsilon$ | <zero-or-more>$[x]$ $x$}
  \end{quote}
\item $x^+$ abbreviates @<one-or-more>$[x]$, denoting a sequence of one or
  more occurrences of $x$:
  \begin{quote}
    \syntax{$x^+$ ::= <one-or-more>$[x]$ ::= <zero-or-more>$[x]$ $x$}
  \end{quote}
\item @<list>$[x]$ denotes a sequence of one or more occurrences of $x$
  separated by commas:
  \begin{quote}
    \syntax{<list>$[x]$ ::= $x$ | <list>$[x]$ "," $x$}
  \end{quote}
\end{itemize}

%%%--------------------------------------------------------------------------


%% properties

%%%----- That's all, folks --------------------------------------------------