\chapter{Concepts} \label{ch:concepts}
-%%%--------------------------------------------------------------------------
-\section{Operational model} \label{sec:concepts.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{Modules} \label{sec:concepts.modules}
--- /dev/null
+%%% -*-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.
+
+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 each variable is replaced by
+each possible simple nonterminal or terminal symbol.
+
+The letter $\epsilon$ denotes the empty nonterminal
+\begin{quote}
+ \syntax{$\epsilon$ ::=}
+\end{quote}
+
+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 --------------------------------------------------
\chapter{Module syntax} \label{ch:syntax}
-%%%--------------------------------------------------------------------------
-\section{Notation} \label{sec:syntax.notation}
-
-Fortunately, Sod is syntactically quite simple. The notation is slightly
-unusual in order to make the presentation shorter and easier to read.
-
-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 each variable is replaced by
-each possible simple nonterminal or terminal symbol.
-
-The letter $\epsilon$ denotes the empty nonterminal
-\begin{quote}
- \syntax{$\epsilon$ ::=}
-\end{quote}
-
-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}
-
%%%--------------------------------------------------------------------------
\section{Lexical syntax} \label{sec:syntax.lex}
~mdw / sod / commitdiff