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 | ||
72 | The following conventions apply throughout this specification. | |
73 | ||
74 | \begin{itemize} | |
75 | ||
76 | \item If a specification describes an argument as having a particular type or | |
77 | syntax, then it is an error to provide an argument not having that | |
78 | particular type or syntax. | |
79 | ||
80 | \item If a specification describes a function then that function might be | |
81 | implemented as a generic function; it is an error to attempt to (re)define | |
82 | it as a generic function, or to attempt to add methods to it. A function | |
83 | specified as being a generic function will certainly be so; if user methods | |
84 | are permitted on the generic function then this will be specified. | |
85 | ||
86 | \item Where a class precedence list is specified, either explicitly or | |
87 | implicitly by a class hierarchy, the implementation may include additional | |
88 | superclasses not specified here. Such additional superclasses will not | |
89 | affect the order of specified classes in the class precedence lists either | |
90 | of specified classes themselves or of user-defined subclasses of specified | |
91 | classes. | |
92 | ||
93 | \item Unless otherwise specified, generic functions use the standard method | |
94 | combination. | |
95 | ||
96 | \item The specifications for methods are frequently brief; they should be | |
97 | read in conjunction with and in the context of the specification for the | |
98 | generic function and specializing classes, if any. | |
99 | ||
100 | \item An object $o$ is a \emph{direct instance} of a class $c$ if @|(eq | |
101 | (class-of $o$) $c$)|; $o$ is an \emph{instance} of $c$ if it is a direct | |
102 | instance of any subclass of $c$. | |
103 | ||
104 | \item If a class is specified as being \emph{abstract} then it is an error to | |
105 | construct direct instances of it, e.g., using @|make-instance|. | |
106 | ||
107 | \item If an object is specified as being \emph{immutable} then it is an error | |
108 | to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|. Programs | |
109 | may rely on immutable objects retaining their state. | |
110 | ||
111 | \item A value is \emph{fresh} if it is guaranteed to be not @|eql| to any | |
112 | previously existing value. A list is \emph{fresh} if it is guaranteed that | |
113 | none of the cons cells in its main cdr chain (i.e., the list head, its cdr, | |
114 | and so on) are @|eql| to any previously existing value. | |
115 | ||
116 | \item Unless otherwise specified, it is an error to mutate any part of value | |
117 | passed as an argument to, or a non-fresh part of a value returned by, a | |
118 | function specified in this document. | |
119 | ||
120 | \item Unless otherwise specified, it is an error to change the class of an | |
121 | instance of any class described here; and it is an error to change the | |
122 | class of an object to a class described here. | |
123 | ||
124 | \end{itemize} | |
125 | ||
126 | \subsection{Format of the entries} \label{sec:proto.conventions.format} | |
127 | ||
128 | Most symbols defined by the protocol have their own entries. An entry begins | |
129 | with a header line, showing a synopsis of the symbol on the left, and the | |
130 | category (function, class, macro, etc.) on the right. | |
131 | ||
132 | \begin{describe}{fun}{example-function @<required> | |
133 | \&optional @<optional> | |
134 | \&rest @<rest> | |
135 | \&key :keyword | |
136 | @> @<result>} | |
137 | The synopsis for a function, generic function or method describes the | |
138 | function's lambda-list using the usual syntax. Note that keyword arguments | |
139 | are shown by naming their keywords; in the description, the value passed | |
140 | for the keyword argument @|:keyword| is shown as @<keyword>. | |
141 | ||
142 | If no results are shown, then the return values (if any) are not | |
143 | specified. Functions may return more than one result, e.g., | |
144 | \begin{quote} \sffamily | |
145 | floor @<dividend> \&optional (@<divisor> 1) @> @<quotient> @<remainder> | |
146 | \end{quote} | |
147 | or possibly multiple results, e.g., | |
148 | \begin{quote} \sffamily | |
149 | values \&rest @<values> @> @<value>^* | |
150 | \end{quote} | |
151 | ||
152 | For a method, specializers are shown using the usual @|defmethod| syntax, | |
153 | e.g., | |
154 | \begin{quote} \sffamily | |
155 | some-generic-function ((@<specialized> list) @<unspecialized>) | |
156 | @> @<result> | |
157 | \end{quote} | |
158 | \end{describe} | |
159 | ||
cac85e0b MW |
160 | \begin{describe}{mac} |
161 | {example-macro | |
162 | (@{ @<symbol> @! (@<symbol> @<form>) @}^*) \\ \ind | |
163 | @[[ @<declaration>^* @! @<doc-string> @]] \\ | |
164 | @<form>^* | |
165 | \nlret @<value>^*} | |
1f7d590d MW |
166 | The synopsis for a macro describes the acceptable syntax using the |
167 | following notation. | |
168 | \begin{itemize} | |
169 | \item Literal symbols, e.g., keywords and parenthesis, are shown in | |
170 | @|sans|. | |
171 | \item Metasyntactic variables are shown in (roman) @<italics>. | |
172 | \item Items are grouped together by braces `@{ $\dots$ @}'. The notation | |
173 | `@{ $\dots$ @}^*' indicates that the enclosed items may be repeated zero | |
174 | or more times; `@{ $\dots$ @}^+' indicates that the enclosed items may be | |
175 | repeated one or more times. This notation may be applied to a single | |
176 | item without the braces. | |
177 | \item Optional items are shown enclosed in brackets `@[ $\dots$ @]'. | |
178 | \item Alternatives are separated by vertical bars `@!'; the vertical bar | |
179 | has low precedence, so alternatives extend as far as possible between | |
180 | bars and up to the enclosing brackets if any. | |
181 | \item A sequence of alternatives enclosed in double-brackets `@[[ $\ldots$ | |
182 | @]]' indicates that the alternatives may occur in any order, but each may | |
183 | appear at most once unless marked by a star. | |
184 | \item The notation for results is the same as for functions. | |
185 | \end{itemize} | |
186 | For example, the notation at the head of this example describes syntax | |
187 | for @|let|. | |
188 | \end{describe} | |
189 | ||
190 | \begin{describe}{cls}{example-class (direct-super other-direct-super) \&key | |
191 | :initarg} | |
192 | The synopsis for a class lists the class's direct superclasses, and the | |
193 | acceptable initargs in the form of a lambda-list. The initargs may be | |
194 | passed to @|make-instance| when constructing an instance of the class or a | |
195 | subclass of it. If instances of the class may be reinitialized, or if | |
196 | objects can be changed to be instances of the class, then these initargs | |
197 | may also be passed to @|reinitialize-instance| and/or @|change-class| as | |
198 | applicable; the class description will state explicitly when these | |
199 | operations are allowed. | |
200 | \end{describe} | |
201 | ||
202 | %%%----- That's all, folks -------------------------------------------------- | |
203 | ||
204 | %%% Local variables: | |
205 | %%% mode: LaTeX | |
206 | %%% TeX-master: "sod.tex" | |
207 | %%% TeX-PDF-mode: t | |
208 | %%% End: |