5 %%% (c) 2015 Straylight/Edgeware
8 %%%----- Licensing notice ---------------------------------------------------
10 %%% This file is part of the Sensible Object Design, an object system for C.
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.
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.
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.
26 \chapter{The output system} \label{ch:output}
28 This chapter deals with actually generating output files. It will be of
29 interest to programmers introducing new layout object classes, or new kinds
30 of output files. An understanding of the material in
31 \xref{sec:structures.layout} will prove valuable.
33 %%%--------------------------------------------------------------------------
34 \section{Output sequencing} \label{sec:output.sequencer}
36 C compilers are picky about the order in which things are presented to them
37 in their input; but information about the structure of our classes is
38 scattered among a variety of different layout objects. It's not the case
39 that a layout object only contributes to a single localized portion of the
40 output: for example, a @|vtmsgs| layout object is responsible for declaring
41 both the appropriate @|struct $C$__vtmsgs_$a$| structure in the header file,
42 populated with method entry pointers, but also declaring its member in the
43 enclosing @|struct $C$__vt_$i$| structure.
45 One approach would be to have the various layout objects just know how to
46 call each other in the right order so as to have everything come out
47 properly. That would make extending the translator, e.g., to add new kinds
48 of layout objects, rather difficult. And it doesn't let users insert custom
49 C fragments in flexible ways.
51 Instead, there's a clear separation between which things need to be output,
52 and the order in which they're produced.
54 Ordering is handled by a \emph{sequencer} object. A sequencer doesn't know
55 anything particular about output: its job is simply to do things in a
56 particular order. It's described here because Sod only uses it for output
59 A sequencer maintains a collection of named \emph{items}, each of which has a
60 name and a list of functions associated with it. A name can be any Lisp
61 object. Names are compared using @|equal|, so lists can be used to construct
62 a hierarchical namespace.
64 The sequencer also maintains a collection of \emph{constraints}, which take
65 the form of lists of item names. A constraint of the form @|($N_1$, $N_2$,
66 $\ldots$, $N_k$)| requires that the item named $N_1$ must be scheduled before
67 the item named $N_2$, and so on, all of which must be scheduled before the
68 item named $N_k$. Items with these names do not need to exist or be known to
69 the sequencer. An item name may appear in any number of constraints, all of
72 It might be that a collection of constraints is impossible to satisfy: for
74 \begin{center} \codeface
75 (alice bob) \qquad (bob carol) \qquad (carol alice)
77 can't be satisfied, since the first constraint requires that @|alice|
78 precedes @|bob|, but the third says that @|alice| must come after @|carol|,
79 and the second that @|carol| comes after @|bob|: it's not possible that
80 @|alice| comes before @|bob| and after @|bob|. In this case, the sequencer
81 fails and signals an error of type @|inconsistent-merge-error|.
83 It is possible, but tedious, to explicitly order an entire collection of
84 items by adding constraints. In the absence of explicit constraints to order
85 them, items are ordered according to the order in which constraints naming
86 them were first added to the sequencer. Items not named in any constraint
87 are not processed at all.
89 For example, suppose we have the following constraints.
90 \begin{center} \codeface
96 The constraints give us that $@|python| < @|icon| < @|perl| < @|java|$, and
97 also $@|lisp| < @|java|$. In this case, @|lisp| precedes @|python| because
98 @|lisp| is mentioned in the second constraint while @|python| isn't mentioned
99 until the third. So the final processing order is
109 \begin{describe}{cls}{sequencer-item}
110 An object of class @|sequencer-item| represents a sequencer item.
111 Sequencer items maintain a \emph{name} and a list of \emph{functions}.
112 Names are compared using @|equal|.
114 The functions are maintained in \emph{reverse order}, because it's
115 convenient to be able to add new functions using @|push|.
118 \begin{describe}{fun}{sequencer-item-p @<object> @> @<generalized-boolean>}
119 Return non-nil if and only if @<object> is a @|sequencer-item|.
122 \begin{describe}{fun}
123 {make-sequencer-item @<name> \&optional @<functions> @> @<item>}
124 Create and return a new sequencer item with the given @<name> and list of
125 @<functions>; the list of functions defaults to nil if omitted.
129 {\dhead{fun}{sequencer-item-name @<item> @> @<name>}
130 \dhead{fun}{sequencer-item-functions @<item> @> @<list>}
131 \dhead{fun}{setf (sequencer-item-functions @<item>) @<list>}}
132 These functions read or modify the state of a sequencer @<item>, as
133 originally established by @|make-sequencer-item|.
135 It is an error to modify an item's list of functions during a call to
136 @|invoke-sequencer-items| on the item's owning sequencer.
139 \begin{describe}{cls}{sequencer () \&key :constraints}
142 \begin{describe}{fun}{ensure-sequencer-item @<sequencer> @<name> @> @<item>}
145 \begin{describe}{fun}{add-sequencer-constraint @<sequencer> @<constraint>}
148 \begin{describe}{fun}
149 {invoke-sequencer-items @<sequencer> \&rest @<arguments>}
152 \begin{describe}{gf}{hook-output progn @<object> @<reason> @<sequencer>}
153 \begin{describe}{meth}
154 {hook-output progn (@<object> t) (@<reason> t) @<sequencer>}
158 \begin{describe}{mac}
159 {sequence-output (@<stream-var> @<sequencer>) \\ \ind
160 @{ :constraint (@<item-name>^*) @} \\
161 @{ (@<item-name> @<form>^*) @}^*}
164 %%%--------------------------------------------------------------------------
165 \section{Module output} \label{output.module}
167 \subsection{Producing output}
169 \begin{describe}{fun}{output-module @<module> @<reason> @<stream>}
173 \subsection{Managing output types} \label{output.module.manage}
175 \begin{describe}{fun}{declare-output-type @<reason> @<pathname>}
178 \begin{describe}{fun}{output-type-pathname @<reason> @> @<pathname>}
182 \subsection{Utilities} \label{output.module.utilities}
184 \begin{describe}{fun}{banner @<title> @<output> \&key :blank-line-p}
187 \begin{describe}{fun}{guard-name @<filename> @> @<string>}
190 \begin{describe}{fun}
191 {one-off-output @<token> @<sequencer> @<item-name> @<function>}
194 %%%--------------------------------------------------------------------------
195 \section{Class output} \label{output.class}
197 \begin{describe}{var}{*instance-class*}
200 %% output for `h' files
215 %% CLASS islots start
216 %% CLASS islots slots
218 %% CLASS vtmsgs start
219 %% CLASS vtmsgs CLASS start
220 %% CLASS vtmsgs CLASS slots
221 %% CLASS vtmsgs CLASS end
223 %% CLASS vtables start
224 %% CLASS vtables CHAIN-HEAD start
225 %% CLASS vtables CHAIN-HEAD slots
226 %% CLASS vtables CHAIN-HEAD end
228 %% CLASS vtable-externs
229 %% CLASS vtable-externs-after
230 %% CLASS methods start
233 %% CLASS ichains start
234 %% CLASS ichains CHAIN-HEAD start
235 %% CLASS ichains CHAIN-HEAD slots
236 %% CLASS ichains CHAIN-HEAD end
238 %% CLASS ilayout start
239 %% CLASS ilayout slots
250 %% output for `c' files
261 %% CLASS direct-methods start
262 %% CLASS direct-methods METHOD start
263 %% CLASS direct-methods METHOD body
264 %% CLASS direct-methods METHOD end
265 %% CLASS direct-methods end
266 %% CLASS effective-methods
267 %% CLASS vtables start
268 %% CLASS vtables CHAIN-HEAD start
269 %% CLASS vtables CHAIN-HEAD class-pointer METACLASS
270 %% CLASS vtables CHAIN-HEAD base-offset
271 %% CLASS vtables CHAIN-HEAD chain-offset TARGET-HEAD
272 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS start
273 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS slots
274 %% CLASS vtables CHAIN-HEAD vtmsgs CLASS end
275 %% CLASS vtables CHAIN-HEAD end
277 %% CLASS object prepare
278 %% CLASS object start
279 %% CLASS object CHAIN-HEAD ichain start
280 %% CLASS object SUPER slots start
281 %% CLASS object SUPER slots
282 %% CLASS object SUPER vtable
283 %% CLASS object SUPER slots end
284 %% CLASS object CHAIN-HEAD ichain end
292 %%%----- That's all, folks --------------------------------------------------
296 %%% TeX-master: "sod.tex"