doc/: Document where declarations are permitted in macros.

[sod] / doc / lispintro.tex

%%% -*-latex-*-
%%%
%%% Description of the internal class structure and protocol
%%%
%%% (c) 2009 Straylight/Edgeware
%%%

%%%----- Licensing notice ---------------------------------------------------
%%%
%%% This file is part of the Simple Object Definition system.
%%%
%%% 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{Protocol overview} \label{ch:proto}

This chapter provides an overview of the Sod translator's internal object
model.  It describes most of the important classes and generic functions, how
they are used to build a model of a Sod module and produce output code, and
how an extension might modify the translator's behaviour.

I assume familiarity with the Common Lisp Object System (CLOS).  Familiarity
with the CLOS Metaobject Protocol isn't necessary but may be instructive.

%%%--------------------------------------------------------------------------
\section{A tour through the translator}

At the very highest level, the Sod translator works in two phases: it
\emph{parses} source files into an internal representation, and then it
\emph{generates} output files from the internal representation.

The function @|read-module| is given a pathname for a file: it opens the
file, parses the program text, and returns a @|module| instance describing
the classes and other items found.  Parsing has a number of extension points
which allow extensions to add their own module syntax.  Properties can be
attached to modules and the items defined within them, which select which
internal classes are used to represent them, and possibly provide additional
parameters to them.

Modules contain a variety of objects, but the most important objects are
classes, which are associated with a menagerie of other objects representing
the slots, messages, methods and so on defined in the module.  These various
objects engage in a (fairly complicated) protocol to construct another
collection of \emph{layout objects} describing the low-level data structures
and tables which need to be creates.

At the far end, the main output function is @|output-module|, which is given
a module, an output stream and a \emph{reason}, which describes what kind of
output is wanted.  The module items and the layout objects then engage in
another protocol to work out what output needs to be produced, and which
order it needs to be written in.

%%%--------------------------------------------------------------------------
\section{Specification conventions} \label{sec:proto.conventions}

Throughout this specification, the phrase `it is an error' indicates that a
particular circumstance is erroneous and results in unspecified and possibly
incorrect behaviour.  In particular, the situation need not be immediately
diagnosed, and the consequences may be far-reaching.

The following conventions apply throughout this specification.

\begin{itemize}

\item If a specification describes an argument as having a particular type or
  syntax, then it is an error to provide an argument not having that
  particular type or syntax.

\item If a specification describes a function then that function might be
  implemented as a generic function; it is an error to attempt to (re)define
  it as a generic function, or to attempt to add methods to it.  A function
  specified as being a generic function will certainly be so; if user methods
  are permitted on the generic function then this will be specified.

\item Where a class precedence list is specified, either explicitly or
  implicitly by a class hierarchy, the implementation may include additional
  superclasses not specified here.  Such additional superclasses will not
  affect the order of specified classes in the class precedence lists either
  of specified classes themselves or of user-defined subclasses of specified
  classes.

\item Unless otherwise specified, generic functions use the standard method
  combination.

\item The specifications for methods are frequently brief; they should be
  read in conjunction with and in the context of the specification for the
  generic function and specializing classes, if any.

\item An object $o$ is a \emph{direct instance} of a class $c$ if @|(eq
  (class-of $o$) $c$)|; $o$ is an \emph{instance} of $c$ if it is a direct
  instance of any subclass of $c$.

\item If a class is specified as being \emph{abstract} then it is an error to
  construct direct instances of it, e.g., using @|make-instance|.

\item If an object is specified as being \emph{immutable} then it is an error
  to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|.  Programs
  may rely on immutable objects retaining their state.

\item A value is \emph{fresh} if it is guaranteed to be not @|eql| to any
  previously existing value.  A list is \emph{fresh} if it is guaranteed that
  none of the cons cells in its main cdr chain (i.e., the list head, its cdr,
  and so on) are @|eql| to any previously existing value.

\item Unless otherwise specified, it is an error to mutate any part of value
  passed as an argument to, or a non-fresh part of a value returned by, a
  function specified in this document.

\item Unless otherwise specified, it is an error to change the class of an
  instance of any class described here; and it is an error to change the
  class of an object to a class described here.

\end{itemize}

\subsection{Format of the entries} \label{sec:proto.conventions.format}

Most symbols defined by the protocol have their own entries.  An entry begins
with a header line, showing a synopsis of the symbol on the left, and the
category (function, class, macro, etc.) on the right.

\begin{describe}{fun}{example-function @<required>
    \&optional @<optional>
    \&rest @<rest>
    \&key :keyword
    @> @<result>}
  The synopsis for a function, generic function or method describes the
  function's lambda-list using the usual syntax.  Note that keyword arguments
  are shown by naming their keywords; in the description, the value passed
  for the keyword argument @|:keyword| is shown as @<keyword>.

  If no results are shown, then the return values (if any) are not
  specified.  Functions may return more than one result, e.g.,
  \begin{quote} \sffamily
    floor @<dividend> \&optional (@<divisor> 1) @> @<quotient> @<remainder>
  \end{quote}
  or possibly multiple results, e.g.,
  \begin{quote} \sffamily
    values \&rest @<values> @> @<value>^*
  \end{quote}

  For a method, specializers are shown using the usual @|defmethod| syntax,
  e.g.,
  \begin{quote} \sffamily
    some-generic-function ((@<specialized> list) @<unspecialized>)
      @> @<result>
  \end{quote}
\end{describe}

\begin{describe}{mac}
    {example-macro
        (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind
      @[[ @<declaration>^* @! @<doc-string> @]] \\
      @<form>^*
     \nlret @<value>^*}
  The synopsis for a macro describes the acceptable syntax using the
  following notation.
  \begin{itemize}
  \item Literal symbols, e.g., keywords and parenthesis, are shown in
    @|sans|.
  \item Metasyntactic variables are shown in (roman) @<italics>.
  \item Items are grouped together by braces `@{ $\dots$ @}'.  The notation
    `@{ $\dots$ @}^*' indicates that the enclosed items may be repeated zero
    or more times; `@{ $\dots$ @}^+' indicates that the enclosed items may be
    repeated one or more times.  This notation may be applied to a single
    item without the braces.
  \item Optional items are shown enclosed in brackets `@[ $\dots$ @]'.
  \item Alternatives are separated by vertical bars `@!'; the vertical bar
    has low precedence, so alternatives extend as far as possible between
    bars and up to the enclosing brackets if any.
  \item A sequence of alternatives enclosed in double-brackets `@[[ $\ldots$
    @]]' indicates that the alternatives may occur in any order, but each may
    appear at most once unless marked by a star.
  \item The notation for results is the same as for functions.
  \end{itemize}
  For example, the notation at the head of this example describes syntax
  for @|let|.
\end{describe}

\begin{describe}{cls}{example-class (direct-super other-direct-super) \&key
    :initarg}
  The synopsis for a class lists the class's direct superclasses, and the
  acceptable initargs in the form of a lambda-list.  The initargs may be
  passed to @|make-instance| when constructing an instance of the class or a
  subclass of it.  If instances of the class may be reinitialized, or if
  objects can be changed to be instances of the class, then these initargs
  may also be passed to @|reinitialize-instance| and/or @|change-class| as
  applicable; the class description will state explicitly when these
  operations are allowed.
\end{describe}

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

%%% Local variables:
%%% mode: LaTeX
%%% TeX-master: "sod.tex"
%%% TeX-PDF-mode: t
%%% End: