| 1 | %%% -*-latex-*- |
| 2 | %%% |
| 3 | %%% Description of the internal class structure and protocol |
| 4 | %%% |
| 5 | %%% (c) 2009 Straylight/Edgeware |
| 6 | %%% |
| 7 | |
| 8 | %%%----- Licensing notice --------------------------------------------------- |
| 9 | %%% |
| 10 | %%% This file is part of the Simple Object Definition system. |
| 11 | %%% |
| 12 | %%% SOD is free software; you can redistribute it and/or modify |
| 13 | %%% it under the terms of the GNU General Public License as published by |
| 14 | %%% the Free Software Foundation; either version 2 of the License, or |
| 15 | %%% (at your option) any later version. |
| 16 | %%% |
| 17 | %%% SOD is distributed in the hope that it will be useful, |
| 18 | %%% but WITHOUT ANY WARRANTY; without even the implied warranty of |
| 19 | %%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
| 20 | %%% GNU General Public License for more details. |
| 21 | %%% |
| 22 | %%% You should have received a copy of the GNU General Public License |
| 23 | %%% along with SOD; if not, write to the Free Software Foundation, |
| 24 | %%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. |
| 25 | |
| 26 | \chapter{Protocol overview} \label{ch:proto} |
| 27 | |
| 28 | This chapter provides an overview of the Sod translator's internal object |
| 29 | model. It describes most of the important classes and generic functions, how |
| 30 | they are used to build a model of a Sod module and produce output code, and |
| 31 | how an extension might modify the translator's behaviour. |
| 32 | |
| 33 | I assume familiarity with the Common Lisp Object System (CLOS). Familiarity |
| 34 | with the CLOS Metaobject Protocol isn't necessary but may be instructive. |
| 35 | |
| 36 | %%%-------------------------------------------------------------------------- |
| 37 | \section{A tour through the translator} |
| 38 | |
| 39 | At the very highest level, the Sod translator works in two phases: it |
| 40 | \emph{parses} source files into an internal representation, and then it |
| 41 | \emph{generates} output files from the internal representation. |
| 42 | |
| 43 | The function @|read-module| is given a pathname for a file: it opens the |
| 44 | file, parses the program text, and returns a @|module| instance describing |
| 45 | the classes and other items found. Parsing has a number of extension points |
| 46 | which allow extensions to add their own module syntax. Properties can be |
| 47 | attached to modules and the items defined within them, which select which |
| 48 | internal classes are used to represent them, and possibly provide additional |
| 49 | parameters to them. |
| 50 | |
| 51 | Modules contain a variety of objects, but the most important objects are |
| 52 | classes, which are associated with a menagerie of other objects representing |
| 53 | the slots, messages, methods and so on defined in the module. These various |
| 54 | objects engage in a (fairly complicated) protocol to construct another |
| 55 | collection of \emph{layout objects} describing the low-level data structures |
| 56 | and tables which need to be creates. |
| 57 | |
| 58 | At the far end, the main output function is @|output-module|, which is given |
| 59 | a module, an output stream and a \emph{reason}, which describes what kind of |
| 60 | output is wanted. The module items and the layout objects then engage in |
| 61 | another protocol to work out what output needs to be produced, and which |
| 62 | order it needs to be written in. |
| 63 | |
| 64 | %%%-------------------------------------------------------------------------- |
| 65 | \section{Specification conventions} \label{sec:proto.conventions} |
| 66 | |
| 67 | Throughout this specification, the phrase `it is an error' indicates that a |
| 68 | particular circumstance is erroneous and results in unspecified and possibly |
| 69 | incorrect behaviour. In particular, the situation need not be immediately |
| 70 | diagnosed, and the consequences may be far-reaching. |
| 71 | |
| 72 | A \emph{specified} function, variable, symbol, class, type, macro, or other |
| 73 | item is one documented in this specification. |
| 74 | |
| 75 | The following conventions apply throughout this specification. |
| 76 | |
| 77 | \begin{itemize} |
| 78 | |
| 79 | \item If a specification describes an argument as having a particular type or |
| 80 | syntax, then it is an error to provide an argument not having that |
| 81 | particular type or syntax. |
| 82 | |
| 83 | \item A specified function may, e.g., in a later version, accept additional |
| 84 | optional and/or keyword arguments. A specified macro may be extended to |
| 85 | accept syntax other than that documented in this specification, e.g., to |
| 86 | add additional optional arguments. |
| 87 | |
| 88 | \item If a specified function or macro is described as returning the values |
| 89 | returned by some user-supplied function or form, then it will do precisely |
| 90 | that, and there are no restrictions on which or how many values such a |
| 91 | user-supplied function or form may return. Other specified functions or |
| 92 | macros may return additional values beyond those described (so it is likely |
| 93 | an error to invoke them in forms such as @|multiple-value-list| or |
| 94 | @|multiple-value-call|). It is an error for a user-supplied function or |
| 95 | form not to return the documented number and types of values. |
| 96 | |
| 97 | \item The \emph{specified packages} are the @|SOD| package, and all packages |
| 98 | whose names begin @|SOD-|. The specified packages are reserved for the Sod |
| 99 | translator. It is an error to define or alter specified packages (e.g., to |
| 100 | export additional symbols from them, import symbols into them, shadow |
| 101 | symbols in them, or modify their `use' lists), to refer to internal symbols |
| 102 | in specified packages, or to define functions or macros, or proclaim |
| 103 | @|special| variables, whose names are exported by specified packages. If a |
| 104 | symbol exported from a specified package has a name beginning and ending |
| 105 | with @|*| or @|+|, then it is an error to use it as a lexical variable. |
| 106 | |
| 107 | \item A specified function might be implemented as a generic function even if |
| 108 | it is not documented as being one; it is an error to attempt to (re)define |
| 109 | it as a generic function, or to attempt to add methods to it. A function |
| 110 | specified as being a generic function will certainly be so; if user methods |
| 111 | are permitted on the generic function then this will be documented. |
| 112 | |
| 113 | \item Where a class precedence list is specified, either explicitly or |
| 114 | implicitly by a class hierarchy, the implementation may include additional |
| 115 | superclasses not specified here. Such additional superclasses will not |
| 116 | affect the order of specified classes in the class precedence lists either |
| 117 | of specified classes themselves or of user-defined subclasses of specified |
| 118 | classes. |
| 119 | |
| 120 | \item Unless otherwise specified, generic functions use the standard method |
| 121 | combination. |
| 122 | |
| 123 | \item The specifications for methods are frequently brief; they should be |
| 124 | read in conjunction with and in the context of the specification for the |
| 125 | generic function and specializing classes, if any. |
| 126 | |
| 127 | \item An object $o$ is a \emph{direct instance} of a class $c$ if @|(eq |
| 128 | (class-of $o$) $c$)|; $o$ is an \emph{instance} of $c$ if it is a direct |
| 129 | instance of any subclass of $c$. If a class is specified as being |
| 130 | \emph{abstract} then it is an error to construct direct instances of it, |
| 131 | e.g., using @|make-instance|. |
| 132 | |
| 133 | \item If an object is specified as being \emph{immutable} then it is an error |
| 134 | to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|. User |
| 135 | programs may rely on immutable objects retaining their state. |
| 136 | |
| 137 | \item A value is \emph{fresh} if it is guaranteed to be not @|eql| to any |
| 138 | previously existing value. A list is \emph{fresh} if it is guaranteed that |
| 139 | none of the cons cells in its main cdr chain (i.e., the list head, its cdr, |
| 140 | and so on) are @|eql| to any previously existing value. Unless otherwise |
| 141 | specified, it is an error to mutate any part of value passed as an argument |
| 142 | to, or a non-fresh part of a value returned by, a specified function. |
| 143 | |
| 144 | \item Unless otherwise specified, it is an error to change the class of an |
| 145 | instance of any specified class; and it is an error to change the class of |
| 146 | an object to a specified class. |
| 147 | |
| 148 | \end{itemize} |
| 149 | |
| 150 | \subsection{Format of the entries} \label{sec:proto.conventions.format} |
| 151 | |
| 152 | Most symbols defined by the protocol have their own entries. An entry begins |
| 153 | with a header line, showing a synopsis of the symbol on the left, and the |
| 154 | category (function, class, macro, etc.) on the right. |
| 155 | |
| 156 | \begin{describe}{fun}{example-function @<required> |
| 157 | \&optional @<optional> |
| 158 | \&rest @<rest> |
| 159 | \&key :keyword |
| 160 | @> @<result>} |
| 161 | The synopsis for a function, generic function or method describes the |
| 162 | function's lambda-list using the usual syntax. Note that keyword arguments |
| 163 | are shown by naming their keywords; in the description, the value passed |
| 164 | for the keyword argument @|:keyword| is shown as @<keyword>. |
| 165 | |
| 166 | If no results are shown, then the return values (if any) are not |
| 167 | specified. Functions may return more than one result, e.g., |
| 168 | \begin{quote} \sffamily |
| 169 | floor @<dividend> \&optional (@<divisor> 1) @> @<quotient> @<remainder> |
| 170 | \end{quote} |
| 171 | or possibly multiple results, e.g., |
| 172 | \begin{quote} \sffamily |
| 173 | values \&rest @<values> @> @<value>^* |
| 174 | \end{quote} |
| 175 | |
| 176 | For a method, specializers are shown using the usual @|defmethod| syntax, |
| 177 | e.g., |
| 178 | \begin{quote} \sffamily |
| 179 | some-generic-function ((@<specialized> list) @<unspecialized>) |
| 180 | @> @<result> |
| 181 | \end{quote} |
| 182 | \end{describe} |
| 183 | |
| 184 | \begin{describe}{mac} |
| 185 | {example-macro |
| 186 | (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind |
| 187 | @[[ @<declaration>^* @! @<doc-string> @]] \\ |
| 188 | @<form>^* |
| 189 | \nlret @<value>^*} |
| 190 | The synopsis for a macro describes the acceptable syntax using the |
| 191 | following notation. |
| 192 | \begin{itemize} |
| 193 | \item Literal symbols, e.g., keywords and parenthesis, are shown in |
| 194 | @|sans|. |
| 195 | \item Metasyntactic variables are shown in (roman) @<italics>. |
| 196 | \item Items are grouped together by braces `@{ $\dots$ @}'. The notation |
| 197 | `@{ $\dots$ @}^*' indicates that the enclosed items may be repeated zero |
| 198 | or more times; `@{ $\dots$ @}^+' indicates that the enclosed items may be |
| 199 | repeated one or more times. This notation may be applied to a single |
| 200 | item without the braces. |
| 201 | \item Optional items are shown enclosed in brackets `@[ $\dots$ @]'. |
| 202 | \item Alternatives are separated by vertical bars `@!'; the vertical bar |
| 203 | has low precedence, so alternatives extend as far as possible between |
| 204 | bars and up to the enclosing brackets if any. |
| 205 | \item A sequence of alternatives enclosed in double-brackets `@[[ $\ldots$ |
| 206 | @]]' indicates that the alternatives may occur in any order, but each may |
| 207 | appear at most once unless marked by a star. |
| 208 | \item The notation for results is the same as for functions. |
| 209 | \end{itemize} |
| 210 | For example, the notation at the head of this example describes syntax |
| 211 | for @|let|. |
| 212 | \end{describe} |
| 213 | |
| 214 | \begin{describe}{cls}{example-class (direct-super other-direct-super) \&key |
| 215 | :initarg} |
| 216 | The synopsis for a class lists the class's direct superclasses, and the |
| 217 | acceptable initargs in the form of a lambda-list. The initargs may be |
| 218 | passed to @|make-instance| when constructing an instance of the class or a |
| 219 | subclass of it. If instances of the class may be reinitialized, or if |
| 220 | objects can be changed to be instances of the class, then these initargs |
| 221 | may also be passed to @|reinitialize-instance| and/or @|change-class| as |
| 222 | applicable; the class description will state explicitly when these |
| 223 | operations are allowed. |
| 224 | \end{describe} |
| 225 | |
| 226 | %%%----- That's all, folks -------------------------------------------------- |
| 227 | |
| 228 | %%% Local variables: |
| 229 | %%% mode: LaTeX |
| 230 | %%% TeX-master: "sod.tex" |
| 231 | %%% TeX-PDF-mode: t |
| 232 | %%% End: |