From: Mark Wooding Date: Thu, 26 May 2016 08:26:09 +0000 (+0100) Subject: doc/refintro.tex: Introduction to reference section. X-Git-Url: https://git.distorted.org.uk/~mdw/sod/commitdiff_plain/7292d6e1bc85cca454f64353722ba78a9263f257?ds=sidebyside doc/refintro.tex: Introduction to reference section. This is the start of a major reorganization of the reference material. --- diff --git a/doc/concepts.tex b/doc/concepts.tex index b4e80ca..84e4062 100644 --- a/doc/concepts.tex +++ b/doc/concepts.tex @@ -26,37 +26,6 @@ \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} A \emph{module} is the top-level syntactic unit of input to the Sod diff --git a/doc/refintro.tex b/doc/refintro.tex new file mode 100644 index 0000000..ead5ace --- /dev/null +++ b/doc/refintro.tex @@ -0,0 +1,137 @@ +%%% -*-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 @$[x]$, denoting an optional occurrence + of $x$: + \begin{quote} + \syntax{@[$x$@] ::= $[x]$ ::= $\epsilon$ @! $x$} + \end{quote} +\item $x^*$ abbreviates @$[x]$, denoting a sequence of zero or + more occurrences of $x$: + \begin{quote} + \syntax{$x^*$ ::= $[x]$ ::= + $\epsilon$ @! $[x]$ $x$} + \end{quote} +\item $x^+$ abbreviates @$[x]$, denoting a sequence of one or + more occurrences of $x$: + \begin{quote} + \syntax{$x^+$ ::= $[x]$ ::= $[x]$ $x$} + \end{quote} +\item @$[x]$ denotes a sequence of one or more occurrences of $x$ + separated by commas: + \begin{quote} + \syntax{$[x]$ ::= $x$ @! $[x]$ "," $x$} + \end{quote} +\end{itemize} + +%%%-------------------------------------------------------------------------- + + +%% properties + +%%%----- That's all, folks -------------------------------------------------- diff --git a/doc/sod.tex b/doc/sod.tex index 51fa401..ca635bb 100644 --- a/doc/sod.tex +++ b/doc/sod.tex @@ -71,6 +71,7 @@ %%%-------------------------------------------------------------------------- \part{Reference} \label{p:ref} +\include{refintro} \include{concepts} \include{cmdline} \include{syntax} diff --git a/doc/syntax.tex b/doc/syntax.tex index 35ab100..18b46e1 100644 --- a/doc/syntax.tex +++ b/doc/syntax.tex @@ -26,51 +26,6 @@ \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 @$[x]$, denoting an optional occurrence - of $x$: - \begin{quote} - \syntax{@[$x$@] ::= $[x]$ ::= $\epsilon$ @! $x$} - \end{quote} -\item $x^*$ abbreviates @$[x]$, denoting a sequence of zero or - more occurrences of $x$: - \begin{quote} - \syntax{$x^*$ ::= $[x]$ ::= - $\epsilon$ @! $[x]$ $x$} - \end{quote} -\item $x^+$ abbreviates @$[x]$, denoting a sequence of one or - more occurrences of $x$: - \begin{quote} - \syntax{$x^+$ ::= $[x]$ ::= $[x]$ $x$} - \end{quote} -\item @$[x]$ denotes a sequence of one or more occurrences of $x$ - separated by commas: - \begin{quote} - \syntax{$[x]$ ::= $x$ @! $[x]$ "," $x$} - \end{quote} -\end{itemize} - -%%%-------------------------------------------------------------------------- \section{Lexical syntax} \label{sec:syntax.lex} Whitespace and comments are discarded. The remaining characters are