doc/concepts.tex: Typeset method rôle names as identifiers.

[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.

A \emph{specified} function, variable, symbol, class, type, macro, or other
item is one documented in this specification.

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 A specified function may, e.g., in a later version, accept additional
  optional and/or keyword arguments.  A specified macro may be extended to
  accept syntax other than that documented in this specification, e.g., to
  add additional optional arguments.

\item If a specified function or macro is described as returning the values
  returned by some user-supplied function or form, then it will do precisely
  that, and there are no restrictions on which or how many values such a
  user-supplied function or form may return.  Other specified functions or
  macros may return additional values beyond those described (so it is likely
  an error to invoke them in forms such as @|multiple-value-list| or
  @|multiple-value-call|).  It is an error for a user-supplied function or
  form not to return the documented number and types of values.

\item The \emph{specified packages} are the @|SOD| package, and all packages
  whose names begin @|SOD-|.  The specified packages are reserved for the Sod
  translator.  It is an error to define or alter specified packages (e.g., to
  export additional symbols from them, import symbols into them, shadow
  symbols in them, or modify their `use' lists), to refer to internal symbols
  in specified packages, or to define functions or macros, or proclaim
  @|special| variables, whose names are exported by specified packages.  If a
  symbol exported from a specified package has a name beginning and ending
  with @|*| or @|+|, then it is an error to use it as a lexical variable.

\item A specified function might be implemented as a generic function even if
  it is not documented as being one; 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 documented.

\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$.  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)|.  User
  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.  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 specified function.

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

\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: