Commit | Line | Data |
---|---|---|
dea4d055 MW |
1 | %%% -*-latex-*- |
2 | %%% | |
1f7d590d | 3 | %%% C language utilities |
dea4d055 | 4 | %%% |
1f7d590d | 5 | %%% (c) 2015 Straylight/Edgeware |
dea4d055 MW |
6 | %%% |
7 | ||
8 | %%%----- Licensing notice --------------------------------------------------- | |
9 | %%% | |
e0808c47 | 10 | %%% This file is part of the Sensible Object Design, an object system for C. |
dea4d055 MW |
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 | ||
1f7d590d | 26 | \chapter{C language utilities} \label{ch:clang} |
dea4d055 MW |
27 | |
28 | %%%-------------------------------------------------------------------------- | |
1f7d590d | 29 | \section{C type representation} \label{sec:clang.c-types} |
dea4d055 | 30 | |
1f7d590d | 31 | \subsection{Overview} \label{sec:clang.c-types.over} |
dea4d055 MW |
32 | |
33 | The Sod translator represents C types in a fairly simple and direct way. | |
34 | However, because it spends a fair amount of its time dealing with C types, it | |
35 | provides a number of useful operations and macros. | |
36 | ||
64d1ecf7 | 37 | The class hierarchy is shown in~\xref{fig:codegen.c-types.classes}. |
dea4d055 MW |
38 | |
39 | \begin{figure} \centering | |
40 | \parbox{10pt}{\begin{tabbing} | |
020b9e2b MW |
41 | @|c-type| \\ \ind |
42 | @|qualifiable-c-type| \\ \ind | |
43 | @|simple-c-type| \\ \ind | |
44 | @|c-class-type| \-\\ | |
45 | @|tagged-c-type| \\ \ind | |
46 | @|c-struct-type| \\ | |
47 | @|c-union-type| \\ | |
48 | @|c-enum-type| \-\\ | |
49 | @|c-atomic-type| \\ | |
50 | @|c-pointer-type| \-\\ | |
51 | @|c-array-type| \\ | |
52 | @|c-function-type| \\ \ind | |
53 | @|c-keyword-function-type| \- | |
dea4d055 MW |
54 | \end{tabbing}} |
55 | \caption{Classes representing C types} | |
684d95c7 | 56 | \label{fig:codegen.c-types.classes} |
dea4d055 MW |
57 | \end{figure} |
58 | ||
59 | C type objects are immutable unless otherwise specified. | |
60 | ||
61 | \subsubsection{Constructing C type objects} | |
62 | There is a constructor function for each non-abstract class of C type object. | |
63 | Note, however, that constructor functions need not generate a fresh type | |
64 | object if a previously existing type object is suitable. In this case, we | |
65 | say that the objects are \emph{interned}. Some constructor functions are | |
66 | specified to return interned objects: programs may rely on receiving the same | |
67 | (@|eq|) type object for similar (possibly merely @|equal|) arguments. Where | |
68 | not specified, clients may still not rely on receiving fresh objects. | |
69 | ||
58f9b400 | 70 | A convenient S-expression notation is provided by the |
e8d70b1b | 71 | \descref{mac}{c-type}[macro]. Use of this macro is merely an abbreviation |
58f9b400 MW |
72 | for corresponding use of the various constructor functions, and therefore |
73 | interns type objects in the same manner. The syntax accepted by the macro | |
e8d70b1b MW |
74 | can be extended in order to support new classes: see \descref{mac}{defctype}, |
75 | \descref{mac}{c-type-alias} and \descref{mac}{define-c-type-syntax}. | |
dea4d055 MW |
76 | |
77 | The descriptions of each of the various classes include descriptions of the | |
78 | initargs which may be passed to @|make-instance| when constructing a new | |
79 | instance of the class. However, the constructor functions and S-expression | |
80 | syntax are strongly recommended over direct use of @|make-instance|. | |
81 | ||
82 | \subsubsection{Printing} | |
83 | There are two protocols for printing C types. Unfortunately they have | |
84 | similar names. | |
85 | \begin{itemize} | |
e8d70b1b | 86 | \item The \descref{gf}{print-c-type}[function] prints a C type value using |
58f9b400 | 87 | the S-expression notation. It is mainly useful for diagnostic purposes. |
e8d70b1b | 88 | \item The \descref{gf}{pprint-c-type}[function] prints a C type as a |
58f9b400 | 89 | C-syntax declaration. |
dea4d055 MW |
90 | \end{itemize} |
91 | Neither generic function defines a default primary method; subclasses of | |
92 | @|c-type| must define their own methods in order to print correctly. | |
93 | ||
a75cd932 MW |
94 | \begin{describe}{fun}{c-name-case @<name> @> @<string>} |
95 | \end{describe} | |
96 | ||
31d4431b | 97 | |
1f7d590d | 98 | \subsection{The C type root class} \label{sec:clang.c-types.root} |
dea4d055 MW |
99 | |
100 | \begin{describe}{cls}{c-type ()} | |
101 | The class @|c-type| marks the root of the built-in C type hierarchy. | |
102 | ||
103 | Users may define subclasses of @|c-type|. All non-abstract subclasses must | |
104 | have a primary method defined on @|pprint-c-type|; unless instances of the | |
105 | subclass are interned, a method on @|c-type-equal-p| is also required. | |
106 | ||
107 | The class @|c-type| is abstract. | |
108 | \end{describe} | |
109 | ||
31d4431b | 110 | |
1f7d590d | 111 | \subsection{C type S-expression notation} \label{sec:clang.c-types.sexp} |
dea4d055 MW |
112 | |
113 | The S-expression representation of a type is described syntactically as a | |
114 | type specifier. Type specifiers fit into two syntactic categories. | |
115 | \begin{itemize} | |
116 | \item A \emph{symbolic type specifier} consists of a symbol. It has a | |
117 | single, fixed meaning: if @<name> is a symbolic type specifier, then each | |
118 | use of @<name> in a type specifier evaluates to the same (@|eq|) type | |
119 | object, until the @<name> is redefined. | |
120 | \item A \emph{type operator} is a symbol; the corresponding specifier is a | |
121 | list whose @|car| is the operator. The remaining items in the list are | |
122 | arguments to the type operator. | |
123 | \end{itemize} | |
124 | ||
1f7d590d | 125 | \begin{describe}{mac}{c-type @<type-spec> @> @<c-type>} |
dea4d055 MW |
126 | Evaluates to a C type object, as described by the type specifier |
127 | @<type-spec>. | |
128 | \end{describe} | |
129 | ||
1f7d590d | 130 | \begin{describe}{mac} |
020b9e2b MW |
131 | {defctype \=@{ @<name> @! (@<name>^+) @} @<type-spec> \+\\ |
132 | @[[ @|:export| @<export-flag> @]]^* | |
133 | \-\nlret @<names>} | |
dea4d055 MW |
134 | Defines a new symbolic type specifier @<name>; if a list of @<name>s is |
135 | given, then all are defined in the same way. The type constructed by using | |
136 | any of the @<name>s is as described by the type specifier @<type-spec>. | |
137 | ||
138 | The resulting type object is constructed once, at the time that the macro | |
139 | expansion is evaluated; the same (@|eq|) value is used each time any | |
140 | @<name> is used in a type specifier. | |
e43d3532 MW |
141 | |
142 | A variable named @|c-type-@<name>|, for the first @<name> only, is defined | |
143 | and initialized to contain the C type object so constructed. Altering or | |
144 | binding this name is discouraged. | |
145 | ||
146 | If @<export-flag> is true, then the variable name, and all of the @<name>s, | |
147 | are exported from the current package. | |
dea4d055 MW |
148 | \end{describe} |
149 | ||
1f7d590d | 150 | \begin{describe}{mac}{c-type-alias @<original> @<alias>^* @> @<aliases>} |
dea4d055 MW |
151 | Defines each @<alias> as being a type operator identical in behaviour to |
152 | @<original>. If @<original> is later redefined then the behaviour of the | |
153 | @<alias>es changes too. | |
154 | \end{describe} | |
155 | ||
1f7d590d | 156 | \begin{describe}{mac} |
020b9e2b MW |
157 | {define-c-type-syntax @<name> @<lambda-list> \\ \ind |
158 | @[[ @<declaration>^* @! @<doc-string> @]] \\ | |
159 | @<form>^* | |
160 | \-\nlret @<name>} | |
dea4d055 MW |
161 | Defines the symbol @<name> as a new type operator. When a list of the form |
162 | @|(@<name> @<argument>^*)| is used as a type specifier, the @<argument>s | |
163 | are bound to fresh variables according to @<lambda-list> (a destructuring | |
164 | lambda-list) and the @<form>s evaluated in order in the resulting lexical | |
165 | environment as an implicit @|progn|. The value should be a Lisp form which | |
166 | will evaluate to the type specified by the arguments. | |
167 | ||
168 | The @<form>s may call @|expand-c-type-spec| in order to recursively expand | |
169 | type specifiers among its arguments. | |
170 | \end{describe} | |
171 | ||
e07fb83c | 172 | \begin{describe}{gf}{expand-c-type-spec @<type-spec> @> @<form>} |
dea4d055 | 173 | Returns the Lisp form that @|(c-type @<type-spec>)| would expand into. |
e07fb83c | 174 | |
e8d70b1b | 175 | If @<type-spec> is a list, then \descref{gf}{expand-c-type-form} is |
e07fb83c MW |
176 | invoked. |
177 | \end{describe} | |
178 | ||
179 | \begin{describe}{gf}{expand-c-type-form @<head> @<tail> @> @<form>} | |
054e8f8f | 180 | Returns the Lisp form that @|(c-type (@<head> . @<tail>))| would expand |
e07fb83c | 181 | into. |
dea4d055 MW |
182 | \end{describe} |
183 | ||
684d95c7 MW |
184 | \begin{describe}{cty}{lisp @<form>^*} |
185 | Evaluates the @<form>s as an implicit @|progn|, and returns the value(s) of | |
186 | the final @<form> as a C type. | |
187 | \end{describe} | |
188 | ||
1f7d590d MW |
189 | \begin{describe}{gf} |
190 | {print-c-type @<stream> @<type> \&optional @<colon> @<atsign>} | |
dea4d055 MW |
191 | Print the C type object @<type> to @<stream> in S-expression form. The |
192 | @<colon> and @<atsign> arguments may be interpreted in any way which seems | |
193 | appropriate: they are provided so that @|print-c-type| may be called via | |
194 | @|format|'s @|\char`\~/\dots/| command; they are not set when | |
195 | @|print-c-type| is called by Sod functions. | |
196 | ||
197 | There should be a method defined for every C type class; there is no | |
198 | default method. | |
199 | \end{describe} | |
200 | ||
684d95c7 MW |
201 | \begin{describe*} |
202 | {\dhead{sym}{c-type} | |
203 | \dhead{meth}{symbol,(eql 'c-type)} | |
204 | {documentation (@<symbol> symbol) | |
205 | (@<doc-type> (eql 'c-type))} | |
206 | \dhead{meth}{symbol,(eql 'c-type)} | |
207 | {setf \=(documentation (@<symbol> symbol) | |
208 | (@<doc-type> (eql 'c-type))) \\ | |
209 | \>@<string>}} | |
210 | \end{describe*} | |
211 | ||
212 | \begin{describe*} | |
213 | {\dhead{sym}{c-type-form} | |
214 | \dhead{meth}{symbol,(eql 'c-type-form)} | |
215 | {documentation (@<symbol> symbol) | |
216 | (@<doc-type> (eql 'c-type-form))} | |
217 | \dhead{meth}{symbol,(eql 'c-type-form)} | |
218 | {setf \=(documentation (@<symbol> symbol) | |
219 | (@<doc-type> (eql 'c-type-form))) \\ | |
220 | \>@<string>}} | |
221 | \end{describe*} | |
222 | ||
31d4431b | 223 | |
1f7d590d | 224 | \subsection{Comparing C types} \label{sec:clang.c-types.cmp} |
dea4d055 MW |
225 | |
226 | It is necessary to compare C types for equality, for example when checking | |
227 | argument lists for methods. This is done by @|c-type-equal-p|. | |
228 | ||
1f7d590d MW |
229 | \begin{describe}{gf} |
230 | {c-type-equal-p @<c-type>_1 @<c-type>_2 @> @<generalized-boolean>} | |
231 | The generic function @|c-type-equal-p| compares two C types @<c-type>_1 and | |
232 | @<c-type>_2 for equality; it returns true if the two types are equal and | |
dea4d055 MW |
233 | false if they are not. |
234 | ||
235 | Two types are equal if they are structurally similar, where this property | |
236 | is defined by methods for each individual class; see the descriptions of | |
237 | the classes for the details. | |
238 | ||
239 | The generic function @|c-type-equal-p| uses the @|and| method combination. | |
240 | ||
87883222 | 241 | \begin{describe}{meth}{t,t}{c-type-equal-p @<c-type>_1 @<c-type>_2} |
dea4d055 MW |
242 | A default primary method for @|c-type-equal-p| is defined. It simply |
243 | returns @|nil|. This way, methods can specialize on both arguments | |
244 | without fear that a call will fail because no methods are applicable. | |
245 | \end{describe} | |
87883222 | 246 | \begin{describe}{ar-meth}{}{c-type-equal-p @<c-type>_1 @<c-type>_2} |
dea4d055 | 247 | A default around-method for @|c-type-equal-p| is defined. It returns |
1f7d590d MW |
248 | true if @<c-type>_1 and @<c-type>_2 are @|eql|; otherwise it delegates to |
249 | the primary methods. Since several common kinds of C types are interned, | |
dea4d055 MW |
250 | this is a common case worth optimizing. |
251 | \end{describe} | |
252 | \end{describe} | |
253 | ||
31d4431b | 254 | |
1f7d590d | 255 | \subsection{Outputting C types} \label{sec:clang.c-types.output} |
dea4d055 | 256 | |
1f7d590d | 257 | \begin{describe}{gf}{pprint-c-type @<c-type> @<stream> @<kernel>} |
dea4d055 | 258 | The generic function @|pprint-c-type| pretty-prints to @<stream> a C-syntax |
1f7d590d | 259 | declaration of an object or function of type @<c-type>. The result is |
dea4d055 MW |
260 | written to @<stream>. |
261 | ||
262 | A C declaration has two parts: a sequence of \emph{declaration specifiers} | |
263 | and a \emph{declarator}. The declarator syntax involves parentheses and | |
264 | operators, in order to reflect the operators applicable to the declared | |
265 | variable. For example, the name of a pointer variable is preceded by @`*'; | |
266 | the name of an array is followed by dimensions enclosed in @`['\dots @`]'. | |
267 | ||
268 | The @<kernel> argument must be a function designator (though see the | |
269 | standard around-method); it is invoked as | |
270 | \begin{quote} \codeface | |
271 | (funcall @<kernel> @<stream> @<priority> @<spacep>) | |
272 | \end{quote} | |
273 | It should write to @<stream> -- which may not be the same stream originally | |
274 | passed into the generic function -- the `kernel' of the declarator, i.e., | |
275 | the part to which prefix and/or postfix operators are attached to form the | |
276 | full declarator. | |
277 | ||
278 | The methods on @|pprint-c-type| specialized for compound types work by | |
279 | recursively calling @|pprint-c-type| on the subtype, passing down a closure | |
280 | which prints the necessary additional declarator operators before calling | |
281 | the original @<kernel> function. The additional arguments @<priority> and | |
282 | @<spacep> support this implementation technique. | |
283 | ||
284 | The @<priority> argument describes the surrounding operator context. It is | |
285 | zero if no type operators are directly attached to the kernel (i.e., there | |
286 | are no operators at all, or the kernel is enclosed in parentheses), one if | |
287 | a prefix operator is directly attached, or two if a postfix operator is | |
288 | directly attached. If the @<kernel> function intends to provide its own | |
289 | additional declarator operators, it should check the @<priority> in order | |
290 | to determine whether parentheses are necessary. See also the | |
e8d70b1b | 291 | \descref{mac}{maybe-in-parens}[macro]. |
dea4d055 MW |
292 | |
293 | The @<spacep> argument indicates whether a space needs to be printed in | |
294 | order to separate the declarator from the declaration specifiers. A kernel | |
295 | which contains an identifier should insert a space before the identifier | |
296 | when @<spacep> is non-nil. An `empty' kernel, as found in an abstract | |
297 | declarator (one that specifies no name), looks more pleasing without a | |
e8d70b1b | 298 | trailing space. See also the \descref{fun}{c-type-space}[function]. |
dea4d055 MW |
299 | |
300 | Every concrete subclass of @|c-type| is expected to provide a primary | |
301 | method on this function. There is no default primary method. | |
302 | ||
87883222 | 303 | \begin{describe}{ar-meth}{}{pprint-c-type @<c-type> @<stream> @<kernel>} |
dea4d055 MW |
304 | A default around method is defined on @|pprint-c-type| which `canonifies' |
305 | non-function @<kernel> arguments. In particular: | |
306 | \begin{itemize} | |
307 | \item if @<kernel> is nil, then @|pprint-c-type| is called recursively | |
308 | with a @<kernel> function that does nothing; and | |
309 | \item if @<kernel> is any other kind of object, then @|pprint-c-type| is | |
310 | called recursively with a @<kernel> function that prints the object as | |
311 | if by @|princ|, preceded if necessary by space using @|c-type-space|. | |
312 | \end{itemize} | |
313 | \end{describe} | |
314 | \end{describe} | |
315 | ||
316 | \begin{describe}{fun}{c-type-space @<stream>} | |
317 | Writes a space and other pretty-printing instructions to @<stream> in order | |
318 | visually to separate a declarator from the preceding declaration | |
319 | specifiers. The precise details are subject to change. | |
320 | \end{describe} | |
321 | ||
1f7d590d | 322 | \begin{describe}{mac} |
cac85e0b MW |
323 | {maybe-in-parens (@<stream-var> @<guard-form>) |
324 | @<declaration>^* | |
325 | @<form>^*} | |
dea4d055 MW |
326 | The @<guard-form> is evaluated, and then the @<form>s are evaluated in |
327 | sequence within a pretty-printer logical block writing to the stream named | |
328 | by the symbol @<stream-var>. If the @<guard-form> evaluates to nil, then | |
329 | the logical block has empty prefix and suffix strings; if it evaluates to a | |
330 | non-nil value, then the logical block has prefix and suffix @`(' and @`)' | |
331 | respectively. | |
332 | ||
333 | Note that this may cause @<stream> to be bound to a different stream object | |
334 | within the @<form>s. | |
335 | \end{describe} | |
336 | ||
31d4431b | 337 | |
dea4d055 | 338 | \subsection{Type qualifiers and qualifiable types} |
1f7d590d | 339 | \label{sec:clang.ctypes.qual} |
dea4d055 | 340 | |
ae0f15ee MW |
341 | Qualifiers -- @|const|, @|volatile|, and so on -- are represented as lists of |
342 | keywords attached to types. Not all C types can carry qualifiers: notably, | |
343 | function and array types cannot be qualified. | |
344 | ||
345 | For the most part, the C qualifier keywords correspond to like-named Lisp | |
346 | keywords, only the Lisp keyword names are in uppercase. The correspondence | |
347 | is shown in \xref{tab:clang.ctypes.qual}. | |
348 | ||
349 | \begin{table} | |
350 | \begin{tabular}[C]{*2{>{\codeface}l}l} \hlx*{hv} | |
6e26f47b MW |
351 | \thd{C name} & \thd{Lisp name} \\ \hlx{vhv} |
352 | _Atomic & :atomic \\ | |
353 | const & :const \\ | |
354 | restrict & :restrict \\ | |
355 | volatile & :volatile \\ \hlx*{vh} | |
ae0f15ee MW |
356 | \end{tabular} |
357 | \caption{C and Lisp qualifier names} \label{tab:clang.ctypes.qual} | |
358 | \end{table} | |
359 | ||
360 | The default behaviour, on output, is to convert keywords to lowercase and | |
361 | hope for the best: special cases can be dealt with by adding appropriate | |
e8d70b1b | 362 | methods to \descref{gf}{c-qualifier-keyword}. |
ae0f15ee | 363 | |
dea4d055 MW |
364 | \begin{describe}{cls}{qualifiable-c-type (c-type) \&key :qualifiers} |
365 | The class @|qualifiable-c-type| describes C types which can bear | |
366 | `qualifiers' (\Cplusplus\ calls them `cv-qualifiers'): @|const|, | |
367 | @|restrict| and @|volatile|. | |
368 | ||
369 | The @<qualifiers> are a list of keyword symbols @|:const|, @|:restrict| and | |
370 | @|:volatile|. There is no built-in limitation to these particular | |
371 | qualifiers; others keywords may be used, though this isn't recommended. | |
372 | ||
373 | Two qualifiable types are equal only if they have \emph{matching | |
31d4431b MW |
374 | qualifiers}: i.e., every qualifier attached to one is also attached to the |
375 | other: order is not significant, and neither is multiplicity. | |
dea4d055 MW |
376 | |
377 | The class @|qualifiable-c-type| is abstract. | |
378 | \end{describe} | |
379 | ||
a75cd932 MW |
380 | \begin{describe}{fun} |
381 | {canonify-qualifiers @<qualifiers> @> @<canonfied-qualifiers>} | |
382 | \end{describe} | |
383 | ||
1f7d590d MW |
384 | \begin{describe}{gf}{c-type-qualifiers @<c-type> @> @<list>} |
385 | Returns the qualifiers of the @|qualifiable-c-type| instance @<c-type> as | |
386 | an immutable list. | |
dea4d055 MW |
387 | \end{describe} |
388 | ||
a75cd932 | 389 | \begin{describe}{fun}{qualify-c-type @<c-type> @<qualifiers> @> @<c-type>} |
1f7d590d | 390 | The argument @<c-type> must be an instance of @|qualifiable-c-type|, |
dea4d055 MW |
391 | currently bearing no qualifiers, and @<qualifiers> a list of qualifier |
392 | keywords. The result is a C type object like @<c-type> except that it | |
393 | bears the given @<qualifiers>. | |
394 | ||
1f7d590d | 395 | The @<c-type> is not modified. If @<c-type> is interned, then the returned |
dea4d055 MW |
396 | type will be interned. |
397 | \end{describe} | |
398 | ||
0b80399d | 399 | \begin{describe}{fun}{format-qualifiers @<qualifiers> @> @<string>} |
dea4d055 MW |
400 | Returns a string containing the qualifiers listed in @<qualifiers> in C |
401 | syntax, with a space after each. In particular, if @<qualifiers> is | |
402 | non-null then the final character of the returned string will be a space. | |
403 | \end{describe} | |
404 | ||
ff4e398b MW |
405 | \begin{describe}{gf}{c-qualifier-keyword @<qualifier> @> @<string>} |
406 | Return, as a string, the C keyword corresponding to the Lisp @<qualifier>. | |
407 | ||
408 | There is a standard method, which deals with many qualifiers. Additional | |
409 | methods exist for qualifier keywords which need special handling, such as | |
410 | @|:atomic|; they are not listed here explicitly. | |
411 | ||
87883222 MW |
412 | \begin{describe}{meth}{keyword} |
413 | {c-qualifier-keyword @<keyword> @> @<string>} | |
ff4e398b MW |
414 | Returns the @<keyword>'s print-name, in lower case. This is sufficient |
415 | for the standard qualifiers @|:const|, @|:restrict|, and @|:volatile|. | |
416 | \end{describe} | |
417 | \end{describe} | |
418 | ||
419 | \begin{describe}{fun}{c-type-qualifier-keywords @<c-type> @> @<list>} | |
420 | Return the @<c-type>'s qualifiers, as a list of C keyword names. | |
421 | \end{describe} | |
422 | ||
31d4431b | 423 | |
b7fcf941 MW |
424 | \subsection{Storage specifiers} \label{sec:clang.ctypes.specs} |
425 | ||
426 | Some declaration specifiers, mostly to do with how to store the specific | |
427 | object in question, are determinedly `top level', and, unlike qualifiers, | |
428 | don't stay attached to the base type when acted on by declarator operators. | |
429 | Sod calls these `storage specifiers', though no such category exists in the C | |
430 | standard. They have their own protocol, which is similar in many ways to | |
431 | that of C types. | |
432 | ||
433 | Every Lisp keyword is potentially a storage specifier, which simply maps to | |
434 | its lower-case print name in C; but other storage specifiers may be more | |
435 | complicated objects. | |
436 | ||
684d95c7 MW |
437 | \begin{describe*} |
438 | {\dhead{cls}{c-storage-specifiers-type (c-type) | |
439 | \&key :subtype :specifiers} | |
440 | \dhead{cty}{specs @<subtype> @<specifier>^*}} | |
b7fcf941 MW |
441 | A type which carries storage specifiers. The @<subtype> is the actual |
442 | type, and may be any C type; the @<specifiers> are a list of | |
443 | storage-specifier objects. | |
444 | ||
684d95c7 MW |
445 | The type specifier @|specs| wraps the @<subtype> in a |
446 | @|c-storage-specifiers-type|, carrying the @<specifier>s, which are a list | |
447 | of storage specifiers in S-expression notation. | |
448 | \end{describe*} | |
b7fcf941 MW |
449 | |
450 | \begin{describe}{fun}{c-type-specifiers @<type> @> @<list>} | |
451 | Returns the list of type specifiers attached to the @<type> object, which | |
452 | must be a @|c-storage-specifiers-type|. | |
453 | \end{describe} | |
454 | ||
455 | \begin{describe}{mac} | |
456 | {define-c-storage-specifier-syntax @<name> @<lambda-list> \\ \ind | |
457 | @[[ @<declaration>^* @! @<doc-string> @]] \\ | |
458 | @<form>^* \- | |
459 | \nlret @<name>} | |
460 | ||
461 | Defines the symbol @<name> as a new storage-specifier operator. When a | |
462 | list of the form @|(@<name> @<argument>^*)| is used as a storage specifier, | |
463 | the @<argument>s are bound to fresh variables according to the | |
464 | @<lambda-list> (a destructuring lambda-list) and the @<form>s evaluated in | |
465 | order in the resulting lexical environment as an implicit @<progn>. The | |
466 | value should be a Lisp form which will evaluate to the storage-specifier | |
467 | object described by the arguments. | |
468 | ||
469 | The @<form>s may call @|expand-c-storage-specifier| in order to recursively | |
470 | expand storage specifiers among its arguments. | |
471 | \end{describe} | |
472 | ||
473 | \begin{describe}{gf}{expand-c-storage-specifier @<spec> @> @<form>} | |
474 | Returns the Lisp form that @<spec> expands to within @|(c-type (specs | |
475 | @<subtype> @<spec>))|. | |
476 | ||
588e0b33 | 477 | If @<spec> is a list, then \descref{gf}{expand-c-storage-specifier-form} is |
b7fcf941 MW |
478 | invoked. |
479 | \end{describe} | |
480 | ||
481 | \begin{describe}{gf}{expand-c-storage-specifier-form @<spec> @> @<form>} | |
482 | Returns the Lisp form that @|(@<head> . @<tail>)| expands to within | |
483 | @|(c-type (specs @<subtype> (@<head> . @<tail>)))|. | |
484 | \end{describe} | |
485 | ||
684d95c7 MW |
486 | \begin{describe}{cstg}{lisp @<form>^*} |
487 | Evaluates the @<form>s as an implicit @|progn|, and returns the value(s) of | |
488 | the final @<form> as a storage-specifier. | |
489 | \end{describe} | |
490 | ||
b7fcf941 | 491 | \begin{describe}{gf}{pprint-c-storage-specifier @<spec> @<stream>} |
684d95c7 | 492 | Prints the storage-specifier @<spec> to @<stream>, in C syntax. |
b7fcf941 MW |
493 | \end{describe} |
494 | ||
495 | \begin{describe}{gf} | |
496 | {print-c-storage-specifier @<stream> @<spec> | |
497 | \&optional @<colon> @<atsign>} | |
498 | \end{describe} | |
499 | ||
500 | \begin{describe}{fun}{wrap-c-type @<func> @<base-type> @> @<c-type>} | |
501 | Apply @<func> to the underlying C type of @<base-type> to create a new | |
502 | `wrapped' type, and attach the storage specifiers of @<base-type> to the | |
503 | wrapped type. | |
504 | ||
505 | If @<base-type> is \emph{not} a @|c-storage-specifiers-type|, then return | |
506 | @|(funcall @<func> @<base-type>)|. Otherwise, return a new | |
507 | @|c-storage-specifiers-type|, with the same specifiers, but whose subtype | |
508 | is the result of applying @<func> to the subtype of the original | |
509 | @<base-type>. | |
510 | \end{describe} | |
511 | ||
684d95c7 MW |
512 | \begin{describe*} |
513 | {\dhead{cls}{alignas-storage-specifier () \&key :alignment} | |
514 | \dhead{cstg}{alignas @<alignment>}} | |
515 | The class of \mbox{@|_Alignas|} storage specifiers; an instance denotes the | |
516 | specifier \mbox{@|_Alignas(@<alignment>)|}. The @<alignment> parameter may | |
517 | be any printable object, but is usually a string or C fragment. | |
518 | ||
519 | The storage specifier form @|alignas| returns a storage specifier | |
520 | \mbox{@|_Alignas(@<alignment>)|}, where @<alignment> is evaluated. | |
521 | \end{describe*} | |
db56b1d3 | 522 | |
31d4431b | 523 | |
1f7d590d | 524 | \subsection{Leaf types} \label{sec:clang.c-types.leaf} |
dea4d055 MW |
525 | |
526 | A \emph{leaf type} is a type which is not defined in terms of another type. | |
527 | In Sod, the leaf types are | |
528 | \begin{itemize} | |
529 | \item \emph{simple types}, including builtin types like @|int| and @|char|, | |
530 | as well as type names introduced by @|typename|, because Sod isn't | |
531 | interested in what the type name means, merely that it names a type; and | |
532 | \item \emph{tagged types}, i.e., enum, struct and union types which are named | |
533 | by a keyword identifying the kind of type, and a \emph{tag}. | |
534 | \end{itemize} | |
535 | ||
536 | \begin{describe}{cls}{simple-c-type (qualifiable-c-type) | |
537 | \&key :qualifiers :name} | |
538 | The class of `simple types'; an instance denotes the type @<qualifiers> | |
539 | @<name>. | |
540 | ||
541 | A simple type object maintains a \emph{name}, which is a string whose | |
542 | contents are the C name for the type. The initarg @|:name| may be used to | |
543 | provide this name when calling @|make-instance|. | |
544 | ||
545 | Two simple type objects are equal if and only if they have @|string=| names | |
546 | and matching qualifiers. | |
547 | ||
684d95c7 MW |
548 | \def\x#1{\desclabel{cty}{#1}} |
549 | \def\y#1{\desclabel{const}{c-type-#1}\x{#1}} | |
550 | \y{bool} \y{wchar-t} | |
551 | \y{int} \x{signed} \y{unsigned} \y{signed-char} | |
552 | \crossproduct\y{{{}{unsigned-}}{{char}{short}{long}{long-long}}} | |
553 | \crossproduct\x{{{}{signed-}{unsigned-}}{{short}{long}{long-long}}{{-int}}} | |
554 | \crossproduct\x{{{signed-}{unsigned-}}{{int}}} | |
555 | \crossproduct\x{{{signed-}}{{short}{int}{long}{long-long}}} | |
556 | \crossproduct\x{{{s}{u}}{{char}{short}{int}{long}{llong}}} \x{llong} | |
557 | \y{size-t} \y{ptrdiff-t} \y{float} | |
558 | \y{double} \y{long-double} \y{float-imaginary} \y{double-imaginary} | |
559 | \y{long-double-imaginary} \y{float-complex} \y{double-complex} | |
560 | \y{long-double-complex} \y{va-list} \y{void} | |
561 | \crossproduct\y{{{int}{uint}}{{}{-least}{-fast}}{{8}{16}{32}{64}}{{-t}}} | |
562 | \crossproduct\y{{{int}{uint}}{{ptr}{max}}{{-t}}} | |
0a8f78ec | 563 | |
dea4d055 | 564 | A number of symbolic type specifiers for builtin types are predefined as |
64d1ecf7 | 565 | shown in \xref{tab:codegen.c-types.simple}. These are all defined as if by |
dea4d055 MW |
566 | @|define-simple-c-type|, so can be used to construct qualified types. |
567 | \end{describe} | |
568 | ||
569 | \begin{table} | |
fcb6c0fb MW |
570 | \begin{tabular}[C]{ll} \hlx*{hv} |
571 | \thd{C type} & \thd{Specifiers} \\ \hlx{vhv} | |
572 | @|void| & @|void| \\ \hlx{v} | |
a4434457 MW |
573 | @|_Bool| & @|bool| \\ \hlx{v} |
574 | @|char| & @|char| \\ \hlx{} | |
a4434457 | 575 | @|wchar_t| & @|wchar-t| \\ \hlx{v} |
d21ac4d9 MW |
576 | @|signed char| & @|signed-char|, @|schar| \\ \hlx{} |
577 | @|unsigned char| & @|unsigned-char|, @|uchar| \\ \hlx{v} | |
dea4d055 | 578 | @|short| & @|short|, @|signed-short|, @|short-int|, |
fcb6c0fb | 579 | @|signed-short-int| @|sshort| \\ \hlx{} |
dea4d055 | 580 | @|unsigned short| & @|unsigned-short|, @|unsigned-short-int|, |
fcb6c0fb | 581 | @|ushort| \\ \hlx{v} |
dea4d055 | 582 | @|int| & @|int|, @|signed|, @|signed-int|, |
fcb6c0fb MW |
583 | @|sint| \\ \hlx{} |
584 | @|unsigned int| & @|unsigned|, @|unsigned-int|, @|uint| \\ \hlx{v} | |
dea4d055 | 585 | @|long| & @|long|, @|signed-long|, @|long-int|, |
fcb6c0fb | 586 | @|signed-long-int|, @|slong| \\ \hlx{} |
dea4d055 | 587 | @|unsigned long| & @|unsigned-long|, @|unsigned-long-int|, |
fcb6c0fb | 588 | @|ulong| \\ \hlx{v} |
dea4d055 | 589 | @|long long| & @|long-long|, @|signed-long-long|, |
d21ac4d9 | 590 | @|long-long-int|, \\ \hlx{} |
dea4d055 MW |
591 | & \qquad @|signed-long-long-int|, |
592 | @|llong|, @|sllong| \\ \hlx{v} | |
593 | @|unsigned long long| | |
594 | & @|unsigned-long-long|, @|unsigned-long-long-int|, | |
fcb6c0fb | 595 | @|ullong| \\ \hlx{v} |
d21ac4d9 MW |
596 | @|size_t| & @|size-t| \\ \hlx{} |
597 | @|ptrdiff_t| & @|ptrdiff-t| \\ \hlx{v} | |
0a8f78ec MW |
598 | @|int$n$_t| & @|int$n$-t| |
599 | (for $n \in \{ @|8|, @|16|, @|32|, @|64| \}$) | |
600 | \\ \hlx{} | |
601 | @|uint$n$_t| & @|uint$n$-t| \\ \hlx{} | |
602 | @|int_least$n$_t| & @|int_least$n$-t| \\ \hlx{} | |
603 | @|uint_least$n$_t| & @|uint_least$n$-t| \\ \hlx{} | |
604 | @|int_fast$n$_t| & @|int_fast$n$-t| \\ \hlx{} | |
605 | @|uint_fast$n$_t| & @|uint_fast$n$-t| \\ \hlx{v} | |
606 | @|intptr_t| & @|intptr-t| \\ \hlx{} | |
607 | @|uintptr_t| & @|uintptr-t| \\ \hlx{} | |
608 | @|intmax_t| & @|intmax-t| \\ \hlx{} | |
609 | @|uintmax_t| & @|uintmax-t| \\ \hlx{v} | |
fcb6c0fb | 610 | @|float| & @|float| \\ \hlx{} |
a4434457 MW |
611 | @|double| & @|double| \\ \hlx{} |
612 | @|long double| & @|long-double| \\ \hlx{v} | |
613 | @|float _Imaginary| & @|float-imaginary| \\ \hlx{} | |
a4434457 | 614 | @|double _Imaginary|& @|double-imaginary| \\ \hlx{} |
a4434457 | 615 | @|long double _Imaginary| |
d21ac4d9 MW |
616 | & @|long-double-imaginary| \\ \hlx{v} |
617 | @|float _Complex| & @|float-complex| \\ \hlx{} | |
618 | @|double _Complex| & @|double-complex| \\ \hlx{} | |
a4434457 | 619 | @|long double _Complex| |
d21ac4d9 MW |
620 | & @|long-double-complex| \\ \hlx{v} |
621 | @|va_list| & @|va-list| \\ \hlx*{vh} | |
dea4d055 MW |
622 | \end{tabular} |
623 | \caption{Builtin symbolic type specifiers for simple C types} | |
64d1ecf7 | 624 | \label{tab:codegen.c-types.simple} |
dea4d055 MW |
625 | \end{table} |
626 | ||
1f7d590d MW |
627 | \begin{describe}{fun} |
628 | {make-simple-type @<name> \&optional @<qualifiers> @> @<c-type>} | |
dea4d055 MW |
629 | Return the (unique interned) simple C type object for the C type whose name |
630 | is @<name> (a string) and which has the given @<qualifiers> (a list of | |
631 | keywords). | |
632 | \end{describe} | |
633 | ||
1f7d590d MW |
634 | \begin{describe}{gf}{c-type-name @<c-type> @> @<string>} |
635 | Returns the name of a @|simple-c-type| instance @<c-type> as an immutable | |
dea4d055 MW |
636 | string. |
637 | \end{describe} | |
638 | ||
1f7d590d | 639 | \begin{describe}{mac} |
020b9e2b | 640 | {define-simple-c-type |
14adef2f MW |
641 | \=@{ @<name> @! (@<name>^+) @} |
642 | @{ @<string> @! (@<string>^*) @} \+\\ | |
020b9e2b MW |
643 | @[[ @|:export| @<export-flag> @]] |
644 | \-\nlret @<name>} | |
dea4d055 MW |
645 | Define type specifiers for a new simple C type. Each symbol @<name> is |
646 | defined as a symbolic type specifier for the (unique interned) simple C | |
14adef2f MW |
647 | type whose name is the value of (the first) @<string>. Further, each |
648 | @<name> is defined to be a type operator: the type specifier @|(@<name> | |
dea4d055 | 649 | @<qualifier>^*)| evaluates to the (unique interned) simple C type whose |
14adef2f MW |
650 | name is (the first) @<string> and which has the @<qualifiers> (which are |
651 | evaluated). | |
e43d3532 | 652 | |
14adef2f | 653 | Each of the @<string>s is associated with the resulting type for retrieval |
e8d70b1b | 654 | by \descref{fun}{find-simple-c-type}. Furthermore, a variable |
14adef2f MW |
655 | @|c-type-@<name>| is defined, for the first @<name> only, and initialized |
656 | with the newly constructed C type object. | |
e43d3532 MW |
657 | |
658 | If @<export-flag> is true, then the @|c-type-@<name>| variable name, and | |
659 | all of the @<name>s, are exported from the current package. | |
dea4d055 MW |
660 | \end{describe} |
661 | ||
14adef2f MW |
662 | \begin{describe}{fun} |
663 | {find-simple-c-type @<string> @> @{ @<simple-c-type> @! @|nil| @}} | |
664 | If @<string> is the name of a simple C type, as established by the | |
e8d70b1b | 665 | \descref{mac}{define-simple-c-type}[macro], then return the corresponding |
14adef2f MW |
666 | @|simple-c-type| object; otherwise, return @|nil|. |
667 | \end{describe} | |
668 | ||
dea4d055 MW |
669 | \begin{describe}{cls}{tagged-c-type (qualifiable-c-type) |
670 | \&key :qualifiers :tag} | |
671 | Provides common behaviour for C tagged types. A @<tag> is a string | |
672 | containing a C identifier. | |
673 | ||
674 | Two tagged types are equal if and only if they have the same class, their | |
675 | @<tag>s are @|string=|, and they have matching qualifiers. (User-defined | |
676 | subclasses may have additional methods on @|c-type-equal-p| which impose | |
677 | further restrictions.) | |
678 | \end{describe} | |
679 | \begin{boxy}[Bug] | |
680 | Sod maintains distinct namespaces for the three kinds of tagged types. In | |
681 | C, there is only one namespace for tags which is shared between enums, | |
682 | structs and unions. | |
683 | \end{boxy} | |
684 | ||
a75cd932 MW |
685 | \begin{describe}{gf}{c-type-tag @<c-type> @> @<keyword>} |
686 | \end{describe} | |
687 | ||
688 | \begin{describe}{fun} | |
689 | {make-c-tagged-type @<kind> @<tag> \&optional @<qualifiers> | |
690 | @> @<tagged-type>} | |
691 | \end{describe} | |
692 | ||
1f7d590d MW |
693 | \begin{describe}{gf}{c-tagged-type-kind @<c-type> @> @<keyword>} |
694 | Returns a keyword classifying the tagged @<c-type>: one of @|:enum|, | |
695 | @|:struct| or @|:union|. User-defined subclasses of @|tagged-c-type| | |
696 | should return their own classification symbols. It is intended that | |
697 | @|(string-downcase (c-tagged-type-kind @<c-type>))| be valid C | |
698 | syntax.\footnote{% | |
dea4d055 MW |
699 | Alas, C doesn't provide a syntactic category for these keywords; |
700 | \Cplusplus\ calls them a @<class-key>.} % | |
1f7d590d MW |
701 | There is a method defined for each of the built-in tagged type classes |
702 | @|c-struct-type|, @|c-union-type| and @|c-enum-type|. | |
703 | \end{describe} | |
704 | ||
705 | \begin{describe}{gf}{kind-c-tagged-type @<keyword> @> @<symbol>} | |
706 | This is not quite the inverse of @|c-tagged-type-kind|. Given a keyword | |
707 | naming a kind of tagged type, return the name of the corresponding C | |
708 | type class as a symbol. | |
dea4d055 MW |
709 | \end{describe} |
710 | ||
684d95c7 MW |
711 | \begin{describe*} |
712 | {\dhead{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag} | |
713 | \dhead{cty}{enum @<tag> @<qualifier>^*}} | |
dea4d055 MW |
714 | Represents a C enumerated type. An instance denotes the C type @|enum| |
715 | @<tag>. See the direct superclass @|tagged-c-type| for details. | |
716 | ||
684d95c7 MW |
717 | The type specifier @|enum| returns the (unique interned) enumerated type |
718 | with the given @<tag> and @<qualifier>s (all evaluated). | |
719 | \end{describe*} | |
e38e8367 | 720 | |
1f7d590d MW |
721 | \begin{describe}{fun} |
722 | {make-enum-type @<tag> \&optional @<qualifiers> @> @<c-enum-type>} | |
dea4d055 MW |
723 | Return the (unique interned) C type object for the enumerated C type whose |
724 | tag is @<tag> (a string) and which has the given @<qualifiers> (a list of | |
725 | keywords). | |
726 | \end{describe} | |
727 | ||
684d95c7 MW |
728 | \begin{describe*} |
729 | {\dhead{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag} | |
730 | \dhead{cty}{struct @<tag> @<qualifier>^*}} | |
dea4d055 MW |
731 | Represents a C structured type. An instance denotes the C type @|struct| |
732 | @<tag>. See the direct superclass @|tagged-c-type| for details. | |
733 | ||
684d95c7 MW |
734 | The type specifier @|struct| returns the (unique interned) structured type |
735 | with the given @<tag> and @<qualifier>s (all evaluated). | |
736 | \end{describe*} | |
e38e8367 | 737 | |
1f7d590d MW |
738 | \begin{describe}{fun} |
739 | {make-struct-type @<tag> \&optional @<qualifiers> @> @<c-struct-type>} | |
dea4d055 MW |
740 | Return the (unique interned) C type object for the structured C type whose |
741 | tag is @<tag> (a string) and which has the given @<qualifiers> (a list of | |
742 | keywords). | |
743 | \end{describe} | |
744 | ||
684d95c7 MW |
745 | \begin{describe*} |
746 | {\dhead{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag} | |
747 | \dhead{cty}{union @<tag> @<qualifier>^*}} | |
dea4d055 MW |
748 | Represents a C union type. An instance denotes the C type @|union| |
749 | @<tag>. See the direct superclass @|tagged-c-type| | |
750 | for details. | |
751 | ||
684d95c7 MW |
752 | The type specifier @|union| returns the (unique interned) union type with |
753 | the given @<tag> and @<qualifier>s (all evaluated). | |
754 | \end{describe*} | |
755 | ||
1f7d590d MW |
756 | \begin{describe}{fun} |
757 | {make-union-type @<tag> \&optional @<qualifiers> @> @<c-union-type>} | |
dea4d055 MW |
758 | Return the (unique interned) C type object for the union C type whose tag |
759 | is @<tag> (a string) and which has the given @<qualifiers> (a list of | |
760 | keywords). | |
761 | \end{describe} | |
762 | ||
31d4431b | 763 | |
1f7d590d MW |
764 | \subsection{Compound C types} \label{sec:code.c-types.compound} |
765 | ||
766 | Some C types are \emph{compound types}: they're defined in terms of existing | |
767 | types. The classes which represent compound types implement a common | |
768 | protocol. | |
dea4d055 | 769 | |
1f7d590d MW |
770 | \begin{describe}{gf}{c-type-subtype @<c-type> @> @<subtype>} |
771 | Returns the underlying type of a compound type @<c-type>. Precisely what | |
772 | this means depends on the class of @<c-type>. | |
dea4d055 MW |
773 | \end{describe} |
774 | ||
31d4431b | 775 | |
ae0f15ee MW |
776 | \subsection{Atomic types} \label{sec:clang.c-types.atomic} |
777 | ||
778 | Atomic types are compound types. The subtype of an atomic type is simply the | |
779 | underlying type of the object. Note that, as far as Sod is concerned, atomic | |
780 | types are not the same as atomic-qualified types: you must be consistent | |
781 | about which you use. | |
782 | ||
684d95c7 MW |
783 | \begin{describe*} |
784 | {\dhead{cls}{c-atomic-type (qualifiable-c-type) | |
785 | \&key :qualifiers :subtype} | |
786 | \dhead{cty}{atomic @<type-spec> @<qualifier>^*}} | |
ae0f15ee MW |
787 | Represents an atomic type. An instance denotes the C type |
788 | @|_Atomic(@<subtype>)|. | |
789 | ||
790 | The @<subtype> may be any C type.\footnote{% | |
791 | C does not permit atomic function or array types.} % | |
792 | Two atomic types are equal if and only if their subtypes are equal and they | |
793 | have matching qualifiers. It is possible, though probably not useful, to | |
794 | have an atomic-qualified atomic type. | |
795 | ||
684d95c7 MW |
796 | The type specifier @|atomic| returns a type qualified atomic @<subtype>, |
797 | where @<subtype> is the type specified by @<type-spec> and the | |
798 | @<qualifier>s are qualifier keywords (which are evaluated). | |
799 | \end{describe*} | |
ae0f15ee MW |
800 | |
801 | \begin{describe}{fun} | |
802 | {make-atomic-type @<c-type> \&optional @<qualifiers> @> @<c-atomic-type>} | |
803 | Return an object describing the type qualified atomic @<subtype>. If | |
804 | @<subtype> is interned, then the returned atomic type object is interned | |
805 | also. | |
806 | \end{describe} | |
807 | ||
808 | ||
1f7d590d MW |
809 | \subsection{Pointer types} \label{sec:clang.c-types.pointer} |
810 | ||
cf7f1f46 MW |
811 | Pointers are compound types. The subtype of a pointer type is the type it |
812 | points to. | |
1f7d590d | 813 | |
684d95c7 MW |
814 | \begin{describe*} |
815 | {\dhead{cls}{c-pointer-type (qualifiable-c-type) | |
816 | \&key :qualifiers :subtype} | |
817 | \dhead{cty}{* @<type-spec> @<qualifier>^*} | |
818 | \dhead{cty}{string} | |
819 | \dhead{cty}{const-string}} | |
dea4d055 MW |
820 | Represents a C pointer type. An instance denotes the C type @<subtype> |
821 | @|*|@<qualifiers>. | |
822 | ||
823 | The @<subtype> may be any C type. Two pointer types are equal if and only | |
824 | if their subtypes are equal and they have matching qualifiers. | |
825 | ||
684d95c7 MW |
826 | \desclabel{cty}{ptr} |
827 | \desclabel{cty}{pointer} | |
828 | The type specifier @|*| returns a type qualified pointer-to-@<subtype>, | |
829 | where @<subtype> is the type specified by @<type-spec> and the | |
830 | @<qualifier>s are qualifier keywords (which are evaluated). The synonyms | |
831 | @|ptr| and @|pointer| may be used in place of the star @`*'. | |
dea4d055 | 832 | |
fcb6c0fb | 833 | The symbol @|string| is a type specifier for the type pointer to |
dea4d055 MW |
834 | characters; the symbol @|const-string| is a type specifier for the type |
835 | pointer to constant characters. | |
684d95c7 | 836 | \end{describe*} |
1f7d590d MW |
837 | |
838 | \begin{describe}{fun} | |
839 | {make-pointer-type @<c-type> \&optional @<qualifiers> | |
840 | @> @<c-pointer-type>} | |
fcb6c0fb | 841 | Return an object describing the type qualified pointer to @<subtype>. |
dea4d055 MW |
842 | If @<subtype> is interned, then the returned pointer type object is |
843 | interned also. | |
844 | \end{describe} | |
845 | ||
31d4431b | 846 | |
1f7d590d MW |
847 | \subsection{Array types} \label{sec:clang.c-types.array} |
848 | ||
fcb6c0fb MW |
849 | Arrays implement the compound-type protocol. The subtype of an array type is |
850 | the array element type. | |
1f7d590d | 851 | |
684d95c7 MW |
852 | \begin{describe*} |
853 | {\dhead{cls}{c-array-type (c-type) \&key :subtype :dimensions} | |
854 | \dhead{cty}{[] @<type-spec> @<dimension>^*}} | |
855 | \desclabel{cty}{array}[|(] | |
856 | \desclabel{cty}{vec}[|(] | |
dea4d055 MW |
857 | Represents a multidimensional C array type. The @<dimensions> are a list |
858 | of dimension specifiers $d_0$, $d_1$, \ldots, $d_{n-1}$; an instance then | |
859 | denotes the C type @<subtype> @|[$d_0$][$d_1$]$\ldots$[$d_{n-1}$]|. An | |
860 | individual dimension specifier is either a string containing a C integral | |
861 | constant expression, or nil which is equivalent to an empty string. Only | |
862 | the first (outermost) dimension $d_0$ should be empty. | |
863 | ||
864 | C doesn't actually have multidimensional arrays as a primitive notion; | |
865 | rather, it permits an array (with known extent) to be the element type of | |
866 | an array, which achieves an equivalent effect. C arrays are stored in | |
867 | row-major order: i.e., if we write down the indices of the elements of an | |
868 | array in order of ascending address, the rightmost index varies fastest; | |
869 | hence, the type constructed is more accurately an array of $d_0$ arrays of | |
870 | $d_1$ of \ldots\ arrays of $d_{n-1}$ elements of type @<subtype>. We shall | |
871 | continue to abuse terminology and refer to multidimensional arrays. | |
872 | ||
684d95c7 MW |
873 | The type specifier @|[]| constructs a multidimensional array with the given |
874 | @<dimension>s whose elements have the type specified by @<type-spec>. If | |
875 | no dimensions are given then a single-dimensional array with unspecified | |
876 | extent. The synonyms @|array| and @|vec| may be used in place of the | |
877 | brackets @`[]'. | |
878 | ||
879 | \desclabel{cty}{array}[|)] | |
880 | \desclabel{cty}{vec}[|)] | |
881 | \end{describe*} | |
1f7d590d MW |
882 | |
883 | \begin{describe}{fun} | |
884 | {make-array-type @<subtype> @<dimensions> @> @<c-array-type>} | |
dea4d055 MW |
885 | Return an object describing the type of arrays with given @<dimensions> and |
886 | with element type @<subtype> (an instance of @|c-type|). The @<dimensions> | |
887 | argument is a list whose elements are strings or nil; see the description | |
888 | of the class @|c-array-type| above for details. | |
889 | \end{describe} | |
1f7d590d MW |
890 | |
891 | \begin{describe}{gf}{c-array-dimensions @<c-type> @> @<list>} | |
892 | Returns the dimensions of @<c-type>, an array type, as an immutable list. | |
893 | \end{describe} | |
894 | ||
31d4431b | 895 | |
1f7d590d MW |
896 | \subsection{Function types} \label{sec:clang.c-types.fun} |
897 | ||
fcb6c0fb MW |
898 | Function types implement the compound-type protocol. The subtype of a |
899 | function type is the type of the function's return value. | |
900 | ||
1f7d590d | 901 | \begin{describe}{cls}{argument} |
fcb6c0fb | 902 | Represents an ordinary function argument. |
1f7d590d MW |
903 | \end{describe} |
904 | ||
905 | \begin{describe}{fun}{argumentp @<value> @> @<generalized-boolean>} | |
fcb6c0fb MW |
906 | Decide whether @<value> is an @<argument> object: if so, return non-nil; if |
907 | not return nil. | |
1f7d590d MW |
908 | \end{describe} |
909 | ||
ced609b8 MW |
910 | \begin{describe}{fun} |
911 | {make-argument @<name> @<c-type> \&optional @<default> @> @<argument>} | |
fcb6c0fb MW |
912 | Construct and a return a new @<argument> object. The argument has type |
913 | @<c-type>, which must be a @|c-type| object, and is named @<name>. | |
914 | ||
915 | The @<name> may be nil to indicate that the argument has no name: in this | |
916 | case the argument will be formatted as an abstract declarator, which is not | |
917 | suitable for function definitions. If @<name> is not nil, then the | |
918 | @<name>'s print representation, with @|*print-escape*| nil, is used as the | |
919 | argument name. | |
ced609b8 MW |
920 | |
921 | A @<default> may be supplied. If the argument is used in a | |
e8d70b1b MW |
922 | keyword-argument list (e.g., in a \descref{cls}{c-keyword-function-type} |
923 | [object]), and the @<default> value is provided and non-nil, then its | |
ced609b8 MW |
924 | (unescaped) printed representation is used to provide a default value if |
925 | the keyword argument is not supplied by the caller. | |
1f7d590d MW |
926 | \end{describe} |
927 | ||
52e2a70f | 928 | \begin{describe*} |
31d4431b | 929 | {\dhead{fun}{argument-name @<argument> @> @<name>} |
ced609b8 MW |
930 | \dhead{fun}{argument-type @<argument> @> @<c-type>} |
931 | \dhead{fun}{argument-default @<argument> @> @<default>}} | |
932 | Accessor functions for @|argument| objects. They return the appropriate | |
933 | component of the object, as set by to @|make-argument|. The @<default> is | |
934 | nil if no default was provided to @|make-argument|. | |
52e2a70f | 935 | \end{describe*} |
dea4d055 | 936 | |
fcb6c0fb | 937 | \begin{describe}{gf} |
1f7d590d | 938 | {commentify-argument-name @<name> @> @<commentified-name>} |
fcb6c0fb MW |
939 | Convert the argument name @<name> so that it's suitable to declare the |
940 | function in a header file. | |
dea4d055 | 941 | |
fcb6c0fb MW |
942 | Robust header files shouldn't include literal argument names in |
943 | declarations of functions or function types, since this restricts the | |
944 | including file from defining such names as macros. This generic function | |
945 | is used to convert names into a safe form. | |
946 | ||
87883222 MW |
947 | \begin{describe}{meth}{null} |
948 | {commentify-argument-name (@<name> null) @> nil} | |
fcb6c0fb MW |
949 | Returns nil: if the argument name is already omitted, it's safe for use |
950 | in a header file. | |
951 | \end{describe} | |
87883222 MW |
952 | \begin{describe}{meth}{t} |
953 | {commentify-argument-name (@<name> t) @> @<string>} | |
fcb6c0fb MW |
954 | Returns the print form of @<name> wrapped in a C comment, as |
955 | @`/*@<name>*/'. | |
956 | \end{describe} | |
1f7d590d MW |
957 | \end{describe} |
958 | ||
959 | \begin{describe}{fun} | |
fcb6c0fb MW |
960 | {commentify-argument-names @<arguments> @> @<commentified-arguments>} |
961 | Convert the @<arguments> list so that it's suitable for use in a header | |
962 | file. | |
963 | ||
964 | The @<arguments> list should be a list whose items are @|argument| objects | |
965 | or the keyword @|:ellipsis|. The return value is a list constructed as | |
966 | follows. For each @|argument| object in the input list, there is a | |
967 | corresponding @|argument| object in the returned list, with the same type, | |
968 | and whose name is the result of @|commentify-argument-name| applied to the | |
969 | input argument name; an @|:ellipsis| in the input list is passed through | |
970 | unchanged. | |
1f7d590d MW |
971 | \end{describe} |
972 | ||
684d95c7 MW |
973 | \begin{describe*} |
974 | {\dhead{cls}{c-function-type (c-type) \&key :subtype :arguments} | |
975 | \dhead*{cty}{fun @<return-type> | |
976 | @{ (@<arg-name> @<arg-type>) @}^* | |
977 | @[:ellipsis @! . @<form>@]}} | |
978 | \desclabel{cty}{()}[|(] | |
979 | \desclabel{cty}{fn}[|(] | |
980 | \desclabel{cty}{func}[|(] | |
981 | \desclabel{cty}{function}[|(] | |
982 | \descindex{cty}{fun}[|(] | |
fcb6c0fb MW |
983 | Represents C function types. An instance denotes the type of a C |
984 | function which accepts the @<arguments> and returns @<subtype>. | |
985 | ||
986 | The @<arguments> are a possibly empty list. All but the last element of | |
987 | the list must be @|argument| objects; the final element may instead be the | |
988 | keyword @|:ellipsis|, which denotes a variable argument list. | |
989 | ||
990 | An @<arguments> list consisting of a single argument with type @|void| is | |
991 | converted into an empty list. On output as C code, an empty argument list | |
992 | is written as @|void|. It is not possible to represent a pre-ANSI C | |
993 | function without prototypes. | |
994 | ||
995 | Two function types are considered to be the same if their return types are | |
996 | the same, and their argument lists consist of arguments with the same type, | |
997 | in the same order, and either both or neither argument list ends with | |
998 | @|:ellipsis|; argument names are not compared. | |
999 | ||
684d95c7 MW |
1000 | The type specifier @|fun| constructs a function type. The function has the |
1001 | subtype @<return-type>. The remaining items in the type-specifier list are | |
1002 | used to construct the argument list. The argument items are a possibly | |
1003 | improper list, beginning with zero or more \emph{explicit arguments}: | |
1004 | two-item @<arg-name>/@<arg-type> lists. For each such list, an @|argument| | |
1005 | object is constructed with the given name (evaluated) and type. Following | |
1006 | the explicit arguments, there may be | |
fcb6c0fb MW |
1007 | \begin{itemize} |
1008 | \item nothing, in which case the function's argument list consists only of | |
1009 | the explicit arguments; | |
1010 | \item the keyword @|:ellipsis|, as the final item in the type-specifier | |
1011 | list, indicating a variable argument list may follow the explicit | |
1012 | arguments; or | |
1013 | \item a possibly-improper list tail, beginning with an atom either as a | |
1014 | list item or as the final list cdr, indicating that the entire list tail | |
2249baa7 | 1015 | is a Lisp expression which is to be evaluated to compute the remaining |
fcb6c0fb MW |
1016 | arguments. |
1017 | \end{itemize} | |
1018 | A tail expression may return a list of @|argument| objects, optionally | |
1019 | followed by an @|:ellipsis|. | |
1020 | ||
1021 | For example, | |
1022 | \begin{prog} | |
020b9e2b | 1023 | (c-type (fun \=(lisp (c-type-subtype other-func)) \+\\ |
fcb6c0fb MW |
1024 | ("first" int) . (c-function-arguments other-func)) |
1025 | \end{prog} | |
1026 | evaluates to a function type like @|other-func|, only with an additional | |
1027 | argument of type @|int| added to the front of its argument list. This | |
1028 | could also have been written | |
1029 | \begin{prog} | |
020b9e2b MW |
1030 | (let (\=(args (c-function-arguments other-func)) \+\\ |
1031 | (ret (c-type-subtype other-func))) \-\\ \ind | |
fcb6c0fb MW |
1032 | (c-type (fun \=(lisp ret) ("first" int) . args) |
1033 | \end{prog} | |
684d95c7 MW |
1034 | \descindex{cty}{fun}[|)] |
1035 | \end{describe*} | |
1f7d590d | 1036 | |
684d95c7 MW |
1037 | \begin{describe*} |
1038 | {\dhead{cls}{c-keyword-function-type (c-function-type) | |
1039 | \&key :subtype :arguments :keywords} | |
1040 | \dhead{cty}{fun \=@<return-type> | |
1041 | @{ (@<arg-name> @<arg-type>) @}^* \+\\ | |
1042 | @{ \=:keys @{ (@<kw-name> @<kw-type> | |
1043 | @[@<kw-default>@]) @}^* | |
1044 | @[. @<form>@] @! \+\\ | |
1045 | . @<form> @}}} | |
ced609b8 MW |
1046 | Represents `functions' which accept keyword arguments. Of course, actual C |
1047 | functions can't accept keyword arguments directly, but this type is useful | |
1048 | for describing messages and methods which deal with keyword arguments. | |
1049 | ||
1050 | An instance denotes the type of C function which accepts the position | |
1051 | argument list @<arguments>, and keyword arguments from the @<keywords> | |
1052 | list, and returns @<subtype>. Either or both of the @<arguments> and | |
1053 | @<keywords> lists may be empty. (It is important to note the distinction | |
1054 | between a function which doesn't accept keyword arguments, and one which | |
1055 | does but for which no keyword arguments are defined. In particular, the | |
1056 | latter function can be changed later to accept a keyword argument without | |
1057 | breaking compatibility with old code.) The @<arguments> and @<keywords> | |
1058 | lists must \emph{not} contain @|:ellipsis| markers: a function can accept | |
1059 | keywords, or a variable-length argument tail, but not both. | |
1060 | ||
1061 | Keyword arguments may (but need not) have a \emph{default value} which is | |
1062 | supplied to the function body if the keyword is omitted. | |
1063 | ||
1064 | Keyword functions are never considered to be the same as ordinary | |
1065 | functions. Two keyword function types are considered to be the same if | |
e38e8367 MW |
1066 | their return types are the same, and their positional argument lists |
1067 | consist of arguments with the same type, in the same order: the keyword | |
1068 | arguments accepted by the functions is not significant. | |
ced609b8 MW |
1069 | |
1070 | Keyword functions are constructed using an extended version of the @|fun| | |
684d95c7 MW |
1071 | specifier (or any of its synonyms) used for ordinary C function types. |
1072 | Either the symbol @|:keys| must appear literally in the specifier, or the | |
1073 | @<form> must evaluate to a list containing the symbol @|:keys|. (If | |
1074 | neither of these circumstances obtains, then the specifier constructs an | |
1075 | ordinary function type.) | |
ced609b8 | 1076 | |
e8d70b1b | 1077 | See the description of \descref{cls}{c-function-type} for how a trailing |
ced609b8 MW |
1078 | @<form> is handled. |
1079 | ||
1080 | The list of @<arg-name>s and @<arg-type>s describes the positional | |
1081 | arguments. The list of @<kw-name>s, @<kw-type>s and @<kw-defaults>s | |
1082 | describes the keyword arguments. | |
684d95c7 MW |
1083 | |
1084 | \descindex{cty}{()}[|)] | |
1085 | \descindex{cty}{fn}[|)] | |
1086 | \descindex{cty}{func}[|)] | |
1087 | \descindex{cty}{function}[|)] | |
1088 | \end{describe*} | |
ced609b8 | 1089 | |
1f7d590d | 1090 | \begin{describe}{fun} |
fcb6c0fb MW |
1091 | {make-function-type @<subtype> @<arguments> @> @<c-function-type>} |
1092 | Construct and return a new function type, returning @<subtype> and | |
1093 | accepting the @<arguments>. | |
ced609b8 MW |
1094 | |
1095 | If the @<arguments> list contains a @|:keys| marker, then a | |
e8d70b1b | 1096 | \descref{cls}{c-keyword-function-type}[object] is returned: those arguments |
ced609b8 MW |
1097 | preceding the @|:keys| marker form the positional argument list, and those |
1098 | following the marker form the list of keyword arguments. | |
1099 | \end{describe} | |
1100 | ||
1101 | \begin{describe}{fun} | |
1102 | {make-keyword-function-type @<subtype> @<arguments> @<keywords> | |
1103 | \nlret @<c-keyword-function-type>} | |
1104 | Construct and return a new keyword-function type, returning @<subtype> and | |
1105 | accepting the @<arguments> and @<keywords>. | |
fcb6c0fb MW |
1106 | \end{describe} |
1107 | ||
1108 | \begin{describe}{gf} | |
1109 | {c-function-arguments @<c-function-type> @> @<arguments>} | |
e048fa59 | 1110 | Return the (non-keyword) argument list of the @<c-function-type>. |
1f7d590d MW |
1111 | \end{describe} |
1112 | ||
a75cd932 MW |
1113 | \begin{describe}{gf} |
1114 | {c-function-keywords @<c-function-type> @> @<keywords>} | |
1115 | Return the keyword-argument list of the @<c-function-type>. | |
1116 | \end{describe} | |
1117 | ||
1f7d590d | 1118 | \begin{describe}{fun} |
fcb6c0fb MW |
1119 | {commentify-function-type @<c-function-type> @> @<commentified-c-type>} |
1120 | Return a commentified version of the @<c-function-type>. | |
1121 | ||
1122 | The returned type has the same subtype as the given type, and the argument | |
1123 | list of the returned type is the result of applying | |
1124 | @|commentify-argument-names| to the argument list of the given type. | |
dea4d055 MW |
1125 | \end{describe} |
1126 | ||
074650bc MW |
1127 | \begin{describe}{fun}{reify-variable-argument-tail @<arguments> @> @<list>} |
1128 | If the @<argument> list contains an @|:ellipsis| marker, then replace it | |
1129 | with a @|va_list|. The name for the new argument, if any, is taken from | |
e8d70b1b | 1130 | the \descref{var}{*sod-ap*}[variable]. The new list is returned; the |
074650bc MW |
1131 | original list is not modified, but may share structure with the new list. |
1132 | \end{describe} | |
1133 | ||
84b9d17a MW |
1134 | \begin{describe}{fun} |
1135 | {merge-keyword-lists @<what-function> @<lists> @> @<list>} | |
ced609b8 MW |
1136 | Merge a number of keyword-argument lists together and return the result. |
1137 | ||
84b9d17a MW |
1138 | The @<what-function> is either nil or a function designator; see below. |
1139 | ||
1140 | The @<lists> parameter is a list consisting of a number of | |
1141 | @|(@<report-function> . @<args>)| pairs: in each pair, @<report-function> | |
1142 | is either nil or a function designator, and @<args> is a list of | |
e8d70b1b | 1143 | \descref{cls}{argument} objects. |
ced609b8 MW |
1144 | |
1145 | The resulting list contains exactly one argument for each distinct argument | |
1146 | name appearing in the input @<lists>; this argument will contain the | |
1147 | default value from the earliest occurrence in the input @<lists> of an | |
1148 | argument with that name. | |
1149 | ||
84b9d17a MW |
1150 | If the same name appears multiple times with different types, a continuable |
1151 | error will be signalled, and one of the conflicting argument types will be | |
1152 | chosen arbitrarily. The @<what-function> will be called to establish | |
1153 | information which will be reported to the user. It will be called with no | |
1154 | arguments and is expected to return two values: | |
1155 | \begin{itemize} | |
1156 | \item a file location @<floc> or other object acceptable to | |
e8d70b1b | 1157 | \descref{gf}{file-location}, to be used as the location of the main |
84b9d17a MW |
1158 | error; and |
1159 | \item an object @<what>, whose printed representation should be a noun | |
1160 | phrase describing the object for which the argument lists are being | |
1161 | combined. | |
1162 | \end{itemize} | |
1163 | The phrasing of the error message is `type mismatch in @<what>'. Either, | |
1164 | or both, of @<floc> and @<what> may be nil, though this is considered poor | |
1165 | practice; if @<what-function> is nil, this is equivalent to a function | |
1166 | which returns two nil values. Following the error, the @<report-function>s | |
1167 | for the @<args> lists containing the conflicting argument objects are | |
1168 | called, in an arbitrary order, with a single argument which is the | |
1169 | offending @|argument| object; the function is expected to issue information | |
e8d70b1b | 1170 | messages (see \descref{fun}{info}) to give more detail for diagnosing the |
84b9d17a MW |
1171 | conflict. If a @<report-function> is nil, then nothing happens; this is |
1172 | considered poor practice. | |
ced609b8 MW |
1173 | \end{describe} |
1174 | ||
678b6c0f MW |
1175 | \begin{describe}{fun} |
1176 | {pprint-c-function-type @<return-type> @<stream> | |
1177 | @<print-args> @<print-kernel>} | |
1178 | Provides the top-level structure for printing C function types. | |
1179 | ||
1180 | Output is written to @<stream> to describe a function type returning | |
1181 | @<return-type>, whose declarator kernel (containing the name, and any | |
1182 | further type operands) will be printed by @<print-kernel>, and whose | |
1183 | arguments, if any, will be printed by @<print-args>. | |
1184 | ||
1185 | The @<print-kernel> function is a standard kernel-printing function | |
e8d70b1b | 1186 | following the \descref{gf}{pprint-c-type}[protocol]. |
678b6c0f MW |
1187 | |
1188 | The @<print-args> function is given a single argument, which is the | |
1189 | @<stream> to print on. It should not print the surrounding parentheses. | |
1190 | ||
1191 | The output written to @<stream> looks approximately like | |
1192 | \begin{prog} | |
1193 | @<return-type> @<kernel>(@<args>) | |
1194 | \end{prog} | |
1195 | \end{describe} | |
1196 | ||
1197 | \begin{describe}{fun}{pprint-argument-list @<args> @<stream> @> @<flag>} | |
1198 | Print an argument list to @<stream>. | |
1199 | ||
e8d70b1b | 1200 | The @<args> is a list of \descref{cls}{argument}[objects], optionally |
678b6c0f MW |
1201 | containing an @|:ellipsis| marker. The function returns true if any |
1202 | arguments were actually printed. | |
1203 | \end{describe} | |
1204 | ||
31d4431b | 1205 | |
1f7d590d MW |
1206 | \subsection{Parsing C types} \label{sec:clang.c-types.parsing} |
1207 | ||
756f4928 MW |
1208 | \begin{describe}{fun} |
1209 | {parse-c-type @<scanner> | |
1210 | @> @<result> @<success-flag> @<consumed-flag>} | |
1211 | \end{describe} | |
1212 | ||
1213 | \begin{describe}{fun} | |
1214 | {parse-declarator @<scanner> @<base-type> \&key :kernel :abstractp | |
1215 | \nlret @<result> @<success-flag> @<consumed-flag>} | |
1216 | \end{describe} | |
1217 | ||
31d4431b | 1218 | |
756f4928 MW |
1219 | \subsection{Class types} \label{sec:clang.c-types.class} |
1220 | ||
684d95c7 MW |
1221 | \begin{describe*} |
1222 | {\dhead{cls}{c-class-type (simple-c-type) | |
1223 | \&key :class :tag :qualifiers :name} | |
1224 | \dhead{cty}{class @<name> @<qualifier>^*}} | |
1225 | \end{describe*} | |
756f4928 MW |
1226 | |
1227 | \begin{describe*} | |
1228 | {\dhead{gf}{c-type-class @<class-type> @> @<class>} | |
1229 | \dhead{gf}{setf (c-type-class @<class-type>) @<class>}} | |
1230 | \end{describe*} | |
1231 | ||
1232 | \begin{describe}{fun}{find-class-type @<name> @> @<class-type-or-nil>} | |
1233 | \end{describe} | |
1234 | ||
1235 | \begin{describe}{fun} | |
1236 | {make-class-type @<name> \&optional @<qualifiers> @> @<class-type>} | |
1237 | \end{describe} | |
1238 | ||
756f4928 MW |
1239 | \begin{describe}{fun}{find-sod-class @<name> @> @<class>} |
1240 | \end{describe} | |
1241 | ||
1242 | \begin{describe}{fun}{record-sod-class @<class>} | |
1243 | \end{describe} | |
1244 | ||
1f7d590d MW |
1245 | %%%-------------------------------------------------------------------------- |
1246 | \section{Generating C code} \label{sec:clang.codegen} | |
1247 | ||
fcb6c0fb MW |
1248 | This section deals with Sod's facilities for constructing and manipulating C |
1249 | expressions, declarations, instructions and definitions. | |
1250 | ||
31d4431b | 1251 | |
fcb6c0fb MW |
1252 | \subsection{Temporary names} \label{sec:clang.codegen.temporaries} |
1253 | ||
1254 | Many C-level objects, especially ones with external linkage or inclusion in a | |
1255 | header file, are assigned names which are simple strings, perhaps fixed ones, | |
1256 | perhaps constructed. Other objects don't need meaningful names, and | |
1257 | suitably unique constructed names would be tedious and most likely rather | |
1258 | opaque. Therefore Sod has an ability to construct \emph{temporary names}. | |
1259 | ||
1260 | These aren't temporary in the sense that they name C objects which have | |
1261 | limited lifetimes at runtime. Rather, the idea is that the names be | |
1262 | significant only to small pieces of Lisp code, which will soon forget about | |
1263 | them. | |
1264 | ||
1265 | \subsubsection{The temporary name protocol} | |
1266 | Temporary names are represented by objects which implement a simple protocol. | |
1267 | ||
1268 | \begin{describe}{gf}{format-temporary-name @<var> @<stream>} | |
1269 | \end{describe} | |
1270 | ||
1271 | \begin{describe*} | |
1272 | {\dhead{gf}{var-in-use-p @<var> @> @<generalized-boolean>} | |
73786167 | 1273 | \dhead{gf}{setf (var-in-use-p @<var>) @<generalized-boolean>}} |
fcb6c0fb MW |
1274 | \end{describe*} |
1275 | ||
1276 | \subsubsection{Temporary name objects} | |
1277 | ||
1278 | \begin{describe}{cls}{temporary-name () \&key :tag} | |
1279 | A temporary name object. This is the root of a small collection of | |
1280 | subclasses, but is also usable on its own. | |
1281 | \end{describe} | |
1282 | ||
a75cd932 MW |
1283 | \begin{describe}{gf}{temp-tag @<name> @> @<tag>} |
1284 | \end{describe} | |
1285 | ||
87883222 | 1286 | \begin{describe}{meth}{temporary-name} |
fcb6c0fb MW |
1287 | {commentify-argument-name (@<name> temporary-name) @> nil} |
1288 | \end{describe} | |
1289 | ||
1290 | \begin{table} | |
1291 | \begin{tabular}[C]{*2{>{\codeface}l}} \hlx*{hv} | |
6e26f47b MW |
1292 | \thd{Class} & \thd{Name format} \\ \hlx{vhv} |
1293 | temporary-name & @<tag> \\ | |
1294 | temporary-argument & sod__a@<tag> \\ | |
1295 | temporary-function & sod__f@<tag> \\ | |
1296 | temporary-variable & sod__v@<tag> \\ \hlx*{vh} | |
fcb6c0fb MW |
1297 | \end{tabular} |
1298 | \caption{Temporary name formats} | |
1299 | \label{tab:codegen.codegen.temps-format} | |
1300 | \end{table} | |
1301 | ||
1302 | \begin{describe}{cls}{temporary-argument (temporary-name) \&key :tag} | |
1303 | \end{describe} | |
1304 | ||
1305 | \begin{describe}{cls}{temporary-function (temporary-name) \&key :tag} | |
1306 | \end{describe} | |
1307 | ||
1308 | \begin{describe}{fun}{temporary-function @> @<name>} | |
1309 | \end{describe} | |
1310 | ||
1311 | \begin{describe}{cls} | |
1312 | {temporary-variable (temporary-name) \&key :tag :in-use-p} | |
1313 | \end{describe} | |
1314 | ||
1315 | \subsubsection{Well-known `temporary' names} | |
1316 | ||
1317 | \begin{table} | |
0dfd5c6d MW |
1318 | \def\x#1{\desclabel{var}{#1}} |
1319 | \x{*sod-ap*} \x{*sod-master-ap*} \x{*null-pointer*} | |
fcb6c0fb | 1320 | \begin{tabular}[C]{*2{>{\codeface}l}} \hlx*{hv} |
6e26f47b MW |
1321 | \thd{Variable} & \thd{Name format} \\ \hlx{vhv} |
1322 | {}*sod-ap* & sod__ap \\ | |
1323 | {}*sod-master-ap* & sod__master_ap \\ | |
1324 | {}*null-pointer* & NULL \\ \hlx*{vh} | |
fcb6c0fb MW |
1325 | \end{tabular} |
1326 | \caption{Well-known temporary names} | |
1327 | \label{tab:codegen.codegen.well-known-temps} | |
1328 | \end{table} | |
1329 | ||
31d4431b | 1330 | |
fcb6c0fb MW |
1331 | \subsection{Instructions} \label{sec:clang.codegen.insts} |
1332 | ||
1333 | \begin{describe}{cls}{inst () \&key} | |
1334 | \end{describe} | |
1335 | ||
1336 | \begin{describe}{gf}{inst-metric @<inst>} | |
1337 | \end{describe} | |
1338 | ||
1339 | \begin{describe}{mac} | |
020b9e2b MW |
1340 | {definst @<code> (@<streamvar> \&key @<export>) (@<arg>^*) \\ \ind |
1341 | @[[ @<declaration>^* @! @<doc-string> @]] \\ | |
1342 | @<form>^* | |
1343 | \-\nlret @<code>} | |
fcb6c0fb MW |
1344 | \end{describe} |
1345 | ||
1346 | \begin{describe}{mac} | |
cac85e0b | 1347 | {format-compound-statement |
020b9e2b MW |
1348 | (@<stream> @<child> \&optional @<morep>) \\ \ind |
1349 | @<declaration>^* \\ | |
cac85e0b | 1350 | @<form>^*} |
fcb6c0fb MW |
1351 | \end{describe} |
1352 | ||
7de8c666 MW |
1353 | \begin{describe}{fun} |
1354 | {format-banner-comment @<stream> @<control> \&rest @<args>} | |
1355 | \end{describe} | |
1356 | ||
fcb6c0fb MW |
1357 | \begin{table} |
1358 | \begin{tabular}[C]{ll>{\codeface}l} \hlx*{hv} | |
1359 | \thd{Class name} & | |
6e26f47b MW |
1360 | \thd{Arguments} & |
1361 | \thd{Output format}\\ \hlx{vhv} | |
167524b5 MW |
1362 | @|var| & @<name> @<type> @|\&optional| @<init> |
1363 | & @<type> @<name> @[= @<init>@]; | |
fcb6c0fb MW |
1364 | \\ \hlx{v} |
1365 | @|set| & @<var> @<expr> & @<var> = @<expr>; \\ \hlx{v} | |
1366 | @|update| & @<var> @<op> @<expr> & @<var> @<op>= @<expr>; | |
1367 | \\ \hlx{v} | |
2d8d81c5 MW |
1368 | @|cond| & @<cond> @<conseq> @<alt> & @<cond> ? @<conseq> : @<alt> |
1369 | \\ \hlx{v} | |
fcb6c0fb MW |
1370 | @|return| & @<expr> & return @[@<expr>@]; |
1371 | \\ \hlx{v} | |
1372 | @|break| & --- & break; \\ \hlx{v} | |
1373 | @|continue| & --- & continue; \\ \hlx{v} | |
1374 | @|expr| & @<expr> & @<expr>; \\ \hlx{v} | |
167524b5 MW |
1375 | @|call| & @<func> @|\&rest| @<args> |
1376 | & @<func>(@<arg>_1, | |
fcb6c0fb | 1377 | $\ldots$, |
7de8c666 MW |
1378 | @<arg>_n) \\ \hlx{v} |
1379 | @|banner| & @<control> @|\&rest| @<args> | |
1380 | & /* @<banner> */ \\ \hlx{vhv} | |
fcb6c0fb MW |
1381 | @|block| & @<decls> @<body> & \{ @[@<decls>@] @<body> \} |
1382 | \\ \hlx{v} | |
167524b5 MW |
1383 | @|if| & @<cond> @<conseq> @|\&optional| @<alt> |
1384 | & if (@<cond>) @<conseq> | |
fcb6c0fb | 1385 | @[else @<alt>@] \\ \hlx{v} |
2d8d81c5 MW |
1386 | @|for| & @<init> @<cond> @<update> @<body> & |
1387 | for (@<init>; @<cond>; @<update>) @<body> \\ \hlx{v} | |
fcb6c0fb MW |
1388 | @|while| & @<cond> @<body> & while (@<cond>) @<body> |
1389 | \\ \hlx{v} | |
1390 | @|do-while| & @<body> @<cond> & do @<body> while (@<cond>); | |
1391 | \\ \hlx{v} | |
7de8c666 MW |
1392 | @|function| & |
1393 | \vtop{\hbox{\strut @<name> @<type> @<body>} | |
1394 | \hbox{\strut \quad @|\&optional @<banner>|} | |
1395 | \hbox{\strut \quad @|\&rest| @<banner-args>}} & | |
1396 | \vtop{\hbox{\strut @[/* @<banner> */@]} | |
1397 | \hbox{\strut @<type>_0 @<name>(@<type>_1 @<arg>_1, $\ldots$, | |
167524b5 MW |
1398 | @<type>_n @<arg>_n @[, \dots@])} |
1399 | \hbox{\strut \quad @<body>}} \\ \hlx*{vh} | |
fcb6c0fb MW |
1400 | \end{tabular} |
1401 | \caption{Instruction classes} | |
1402 | \label{tab:codegen.codegen.insts} | |
1403 | \end{table} | |
1404 | ||
0dfd5c6d MW |
1405 | \begin{describe*} |
1406 | {\dhead*{cls}{@<code>-inst (inst) \&key \dots} | |
5968b582 | 1407 | \dhead*{fun}{make-@<code>-inst \dots} |
0dfd5c6d MW |
1408 | \dhead*{gf}{inst-@<slot> @<inst> @> @<value>}} |
1409 | \def\instclass#1#2#3{% | |
1410 | #1{cls}{#3-inst}[#2]% | |
1411 | #1{fun}{make-#3-inst}[#2]% | |
1412 | } | |
1413 | \def\instslot#1#2#3{#1{gf}{inst-#3}[#2]} | |
1414 | \def\makelabels#1#2{% | |
1415 | \def\x{\instclass{#1}{#2}} | |
1416 | \x{var} \x{set} \x{update} \x{cond} \x{return} \x{break} \x{continue} | |
1417 | \x{expr} \x{call} \x{banner} \x{block} \x{if} \x{for} \x{while} | |
1418 | \x{do-while} \x{function} | |
1419 | \def\x{\instslot{#1}{#2}} | |
1420 | \x{name} \x{type} \x{init} \x{var} \x{expr} \x{op} \x{cond} \x{conseq} | |
1421 | \x{alt} \x{func} \x{args} \x{control} \x{decls} \x{body} \x{update} | |
1422 | \x{banner} \x{banner-args} | |
1423 | } | |
1424 | \makelabels{\desclabel}{|(} | |
1425 | ||
1426 | Sod provides a number of built-in instruction types generated by | |
1427 | \descref{mac}{definst}: see \xref{tab:codegen.codegen.insts}. | |
1428 | ||
1429 | \makelabels{\descindex}{|)} | |
1430 | \end{describe*} | |
1431 | ||
31d4431b | 1432 | |
fcb6c0fb MW |
1433 | \subsection{Code generation} \label{sec:clang.codegen.codegen} |
1434 | ||
1435 | \begin{describe}{gf}{codegen-functions @<codegen> @> @<list>} | |
1436 | \end{describe} | |
1437 | ||
1438 | \begin{describe}{gf} | |
1439 | {ensure-var @<codegen> @<name> @<type> \&optional @<init>} | |
1440 | \end{describe} | |
1441 | ||
1442 | \begin{describe}{gf}{emit-inst @<codegen> @<inst>} | |
1443 | \end{describe} | |
1444 | ||
1445 | \begin{describe}{gf}{emit-insts @<codegen> @<insts>} | |
1446 | \end{describe} | |
1447 | ||
1448 | \begin{describe}{gf}{emit-decl @<codegen> @<decl>} | |
1449 | \end{describe} | |
1450 | ||
7c3f8ae6 | 1451 | \begin{describe}{gf}{emit-decls @<codegen> @<decls>} |
fcb6c0fb MW |
1452 | \end{describe} |
1453 | ||
7de8c666 MW |
1454 | \begin{describe}{fun}{emit-banner @<codegen> @<control> \&rest @<args>} |
1455 | \end{describe} | |
1456 | ||
fcb6c0fb MW |
1457 | \begin{describe}{gf}{codegen-push @<codegen>} |
1458 | \end{describe} | |
1459 | ||
1460 | \begin{describe}{gf}{codegen-pop @<codegen> @> @<decls> @<insts>} | |
1461 | \end{describe} | |
1462 | ||
1463 | \begin{describe}{gf}{codegen-pop-block @<codegen> @> @<block-inst>} | |
1464 | \end{describe} | |
1465 | ||
1466 | \begin{describe}{gf} | |
1467 | {codegen-pop-function @<codegen> @<name> @<type> @> @<name>} | |
1468 | \end{describe} | |
1469 | ||
1470 | \begin{describe}{gf}{codegen-add-function @<codegen> @<function>} | |
1471 | \end{describe} | |
1472 | ||
1473 | \begin{describe}{fun} | |
1474 | {codegen-build-function @<codegen> @<name> @<type> @<vars> @<insts> | |
1475 | @> @<name>} | |
1476 | \end{describe} | |
1477 | ||
1478 | \begin{describe}{gf}{temporary-var @<codegen> @<type> @> @<name>} | |
1479 | \end{describe} | |
1480 | ||
1481 | \begin{describe}{mac} | |
020b9e2b MW |
1482 | {with-temporary-var (@<codegen> @<var> @<type>) \\ \ind |
1483 | @<declaration>^* \\ | |
1484 | @<form>^* | |
1485 | \-\nlret @<value>^*} | |
fcb6c0fb MW |
1486 | \end{describe} |
1487 | ||
1488 | \begin{describe}{fun}{deliver-expr @<codegen> @<target> @<expr>} | |
1489 | \end{describe} | |
1490 | ||
357885be MW |
1491 | \begin{describe}{fun} |
1492 | {deliver-call @<codegen> @<target> @<func> \&rest @<args>} | |
1493 | \end{describe} | |
1494 | ||
fcb6c0fb MW |
1495 | \begin{describe}{fun}{convert-stmts @<codegen> @<target> @<type> @<func>} |
1496 | \end{describe} | |
1497 | ||
1498 | \begin{describe}{cls}{codegen () \&key :vars :insts (:temp-index 0)} | |
1499 | \end{describe} | |
1500 | ||
2c7465ac MW |
1501 | %%%-------------------------------------------------------------------------- |
1502 | \section{Literal C code fragments} \label{sec:clang.fragment} | |
1503 | ||
1504 | \begin{describe}{cls}{c-fragment () \&key :location :text} | |
1505 | \end{describe} | |
1506 | ||
1dd7dba9 MW |
1507 | \begin{describe*} |
1508 | {\dhead{gf}{c-fragment-text @<fragment> @> @<string>} | |
1509 | \dhead{meth}{c-fragment} | |
1510 | {file-location (@<fragment> c-fragment) @> @<floc>}} | |
1511 | \end{describe*} | |
2c7465ac MW |
1512 | |
1513 | \begin{describe}{fun} | |
1514 | {scan-c-fragment @<scanner> @<end-chars> | |
1515 | @> @<result> @<success-flag> @<consumed-flag>} | |
1516 | \end{describe} | |
1517 | ||
1518 | \begin{describe}{fun} | |
1519 | {parse-delimited-fragment @<scanner> @<begin> @<end> \&key :keep-end | |
1520 | \nlret @<result> @<success-flag> @<consumed-flag>} | |
1521 | \end{describe} | |
1522 | ||
dea4d055 MW |
1523 | %%%----- That's all, folks -------------------------------------------------- |
1524 | ||
1525 | %%% Local variables: | |
1526 | %%% mode: LaTeX | |
1527 | %%% TeX-master: "sod.tex" | |
1528 | %%% TeX-PDF-mode: t | |
1529 | %%% End: |