Commit | Line | Data |
---|---|---|
1f7d590d MW |
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 | ||
5961a1b1 MW |
72 | A \emph{specified} function, variable, symbol, class, type, macro, or other |
73 | item is one documented in this specification. | |
74 | ||
1f7d590d MW |
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 | ||
5961a1b1 MW |
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 | |
1f7d590d MW |
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 | |
5961a1b1 | 111 | are permitted on the generic function then this will be documented. |
1f7d590d MW |
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 | |
5961a1b1 MW |
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|. | |
1f7d590d MW |
132 | |
133 | \item If an object is specified as being \emph{immutable} then it is an error | |
5961a1b1 MW |
134 | to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|. User |
135 | programs may rely on immutable objects retaining their state. | |
1f7d590d MW |
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, | |
5961a1b1 MW |
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. | |
1f7d590d MW |
143 | |
144 | \item Unless otherwise specified, it is an error to change the class of an | |
5961a1b1 MW |
145 | instance of any specified class; and it is an error to change the class of |
146 | an object to a specified class. | |
1f7d590d MW |
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 | ||
cac85e0b MW |
184 | \begin{describe}{mac} |
185 | {example-macro | |
020b9e2b MW |
186 | (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind |
187 | @[[ @<declaration>^* @! @<doc-string> @]] \\ | |
cac85e0b MW |
188 | @<form>^* |
189 | \nlret @<value>^*} | |
1f7d590d MW |
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: |