3 %%% C language utilities
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{C language utilities} \label{ch:clang}
28 %%%--------------------------------------------------------------------------
29 \section{C type representation} \label{sec:clang.c-types}
31 \subsection{Overview} \label{sec:clang.c-types.over}
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.
37 The class hierarchy is shown in~\xref{fig:codegen.c-types.classes}.
39 \begin{figure} \centering
40 \parbox{10pt}{\begin{tabbing}
42 @|qualifiable-c-type| \\ \ind
43 @|simple-c-type| \\ \ind
45 @|tagged-c-type| \\ \ind
49 @|c-pointer-type| \- \\
51 @|c-function-type| \\ \ind
52 @|c-keyword-function-type| \-
54 \caption{Classes representing C types}
55 \label{fig:codegen.c-types.classes}
58 C type objects are immutable unless otherwise specified.
60 \subsubsection{Constructing C type objects}
61 There is a constructor function for each non-abstract class of C type object.
62 Note, however, that constructor functions need not generate a fresh type
63 object if a previously existing type object is suitable. In this case, we
64 say that the objects are \emph{interned}. Some constructor functions are
65 specified to return interned objects: programs may rely on receiving the same
66 (@|eq|) type object for similar (possibly merely @|equal|) arguments. Where
67 not specified, clients may still not rely on receiving fresh objects.
69 A convenient S-expression notation is provided by the
70 \descref{c-type}[macro]{mac}. Use of this macro is merely an abbreviation
71 for corresponding use of the various constructor functions, and therefore
72 interns type objects in the same manner. The syntax accepted by the macro
73 can be extended in order to support new classes: see \descref{defctype}{mac},
74 \descref{c-type-alias}{mac} and \descref{define-c-type-syntax}{mac}.
76 The descriptions of each of the various classes include descriptions of the
77 initargs which may be passed to @|make-instance| when constructing a new
78 instance of the class. However, the constructor functions and S-expression
79 syntax are strongly recommended over direct use of @|make-instance|.
81 \subsubsection{Printing}
82 There are two protocols for printing C types. Unfortunately they have
85 \item The \descref{print-c-type}[function]{gf} prints a C type value using
86 the S-expression notation. It is mainly useful for diagnostic purposes.
87 \item The \descref{pprint-c-type}[function]{gf} prints a C type as a
90 Neither generic function defines a default primary method; subclasses of
91 @|c-type| must define their own methods in order to print correctly.
94 \subsection{The C type root class} \label{sec:clang.c-types.root}
96 \begin{describe}{cls}{c-type ()}
97 The class @|c-type| marks the root of the built-in C type hierarchy.
99 Users may define subclasses of @|c-type|. All non-abstract subclasses must
100 have a primary method defined on @|pprint-c-type|; unless instances of the
101 subclass are interned, a method on @|c-type-equal-p| is also required.
103 The class @|c-type| is abstract.
107 \subsection{C type S-expression notation} \label{sec:clang.c-types.sexp}
109 The S-expression representation of a type is described syntactically as a
110 type specifier. Type specifiers fit into two syntactic categories.
112 \item A \emph{symbolic type specifier} consists of a symbol. It has a
113 single, fixed meaning: if @<name> is a symbolic type specifier, then each
114 use of @<name> in a type specifier evaluates to the same (@|eq|) type
115 object, until the @<name> is redefined.
116 \item A \emph{type operator} is a symbol; the corresponding specifier is a
117 list whose @|car| is the operator. The remaining items in the list are
118 arguments to the type operator.
121 \begin{describe}{mac}{c-type @<type-spec> @> @<c-type>}
122 Evaluates to a C type object, as described by the type specifier
126 \begin{describe}{mac}
127 {defctype \=@{ @<name> @! (@<name>^+) @} @<type-spec> \+ \\
128 @[[ @|:export| @<export-flag> @]]^* \-
130 Defines a new symbolic type specifier @<name>; if a list of @<name>s is
131 given, then all are defined in the same way. The type constructed by using
132 any of the @<name>s is as described by the type specifier @<type-spec>.
134 The resulting type object is constructed once, at the time that the macro
135 expansion is evaluated; the same (@|eq|) value is used each time any
136 @<name> is used in a type specifier.
138 A variable named @|c-type-@<name>|, for the first @<name> only, is defined
139 and initialized to contain the C type object so constructed. Altering or
140 binding this name is discouraged.
142 If @<export-flag> is true, then the variable name, and all of the @<name>s,
143 are exported from the current package.
146 \begin{describe}{mac}{c-type-alias @<original> @<alias>^* @> @<aliases>}
147 Defines each @<alias> as being a type operator identical in behaviour to
148 @<original>. If @<original> is later redefined then the behaviour of the
149 @<alias>es changes too.
152 \begin{describe}{mac}
153 {define-c-type-syntax @<name> @<lambda-list> \\ \ind
154 @[[ @<declaration>^* @! @<doc-string> @]] \\
157 Defines the symbol @<name> as a new type operator. When a list of the form
158 @|(@<name> @<argument>^*)| is used as a type specifier, the @<argument>s
159 are bound to fresh variables according to @<lambda-list> (a destructuring
160 lambda-list) and the @<form>s evaluated in order in the resulting lexical
161 environment as an implicit @|progn|. The value should be a Lisp form which
162 will evaluate to the type specified by the arguments.
164 The @<form>s may call @|expand-c-type-spec| in order to recursively expand
165 type specifiers among its arguments.
168 \begin{describe}{fun}{expand-c-type-spec @<type-spec> @> @<form>}
169 Returns the Lisp form that @|(c-type @<type-spec>)| would expand into.
173 {print-c-type @<stream> @<type> \&optional @<colon> @<atsign>}
174 Print the C type object @<type> to @<stream> in S-expression form. The
175 @<colon> and @<atsign> arguments may be interpreted in any way which seems
176 appropriate: they are provided so that @|print-c-type| may be called via
177 @|format|'s @|\char`\~/\dots/| command; they are not set when
178 @|print-c-type| is called by Sod functions.
180 There should be a method defined for every C type class; there is no
185 \subsection{Comparing C types} \label{sec:clang.c-types.cmp}
187 It is necessary to compare C types for equality, for example when checking
188 argument lists for methods. This is done by @|c-type-equal-p|.
191 {c-type-equal-p @<c-type>_1 @<c-type>_2 @> @<generalized-boolean>}
192 The generic function @|c-type-equal-p| compares two C types @<c-type>_1 and
193 @<c-type>_2 for equality; it returns true if the two types are equal and
194 false if they are not.
196 Two types are equal if they are structurally similar, where this property
197 is defined by methods for each individual class; see the descriptions of
198 the classes for the details.
200 The generic function @|c-type-equal-p| uses the @|and| method combination.
202 \begin{describe}{meth}{c-type-equal-p @<c-type>_1 @<c-type>_2}
203 A default primary method for @|c-type-equal-p| is defined. It simply
204 returns @|nil|. This way, methods can specialize on both arguments
205 without fear that a call will fail because no methods are applicable.
207 \begin{describe}{ar-meth}{c-type-equal-p @<c-type>_1 @<c-type>_2}
208 A default around-method for @|c-type-equal-p| is defined. It returns
209 true if @<c-type>_1 and @<c-type>_2 are @|eql|; otherwise it delegates to
210 the primary methods. Since several common kinds of C types are interned,
211 this is a common case worth optimizing.
216 \subsection{Outputting C types} \label{sec:clang.c-types.output}
218 \begin{describe}{gf}{pprint-c-type @<c-type> @<stream> @<kernel>}
219 The generic function @|pprint-c-type| pretty-prints to @<stream> a C-syntax
220 declaration of an object or function of type @<c-type>. The result is
221 written to @<stream>.
223 A C declaration has two parts: a sequence of \emph{declaration specifiers}
224 and a \emph{declarator}. The declarator syntax involves parentheses and
225 operators, in order to reflect the operators applicable to the declared
226 variable. For example, the name of a pointer variable is preceded by @`*';
227 the name of an array is followed by dimensions enclosed in @`['\dots @`]'.
229 The @<kernel> argument must be a function designator (though see the
230 standard around-method); it is invoked as
231 \begin{quote} \codeface
232 (funcall @<kernel> @<stream> @<priority> @<spacep>)
234 It should write to @<stream> -- which may not be the same stream originally
235 passed into the generic function -- the `kernel' of the declarator, i.e.,
236 the part to which prefix and/or postfix operators are attached to form the
239 The methods on @|pprint-c-type| specialized for compound types work by
240 recursively calling @|pprint-c-type| on the subtype, passing down a closure
241 which prints the necessary additional declarator operators before calling
242 the original @<kernel> function. The additional arguments @<priority> and
243 @<spacep> support this implementation technique.
245 The @<priority> argument describes the surrounding operator context. It is
246 zero if no type operators are directly attached to the kernel (i.e., there
247 are no operators at all, or the kernel is enclosed in parentheses), one if
248 a prefix operator is directly attached, or two if a postfix operator is
249 directly attached. If the @<kernel> function intends to provide its own
250 additional declarator operators, it should check the @<priority> in order
251 to determine whether parentheses are necessary. See also the
252 \descref{maybe-in-parens}[macro]{mac}.
254 The @<spacep> argument indicates whether a space needs to be printed in
255 order to separate the declarator from the declaration specifiers. A kernel
256 which contains an identifier should insert a space before the identifier
257 when @<spacep> is non-nil. An `empty' kernel, as found in an abstract
258 declarator (one that specifies no name), looks more pleasing without a
259 trailing space. See also the \descref{c-type-space}[function]{fun}.
261 Every concrete subclass of @|c-type| is expected to provide a primary
262 method on this function. There is no default primary method.
264 \begin{describe}{ar-meth}{pprint-c-type @<c-type> @<stream> @<kernel>}
265 A default around method is defined on @|pprint-c-type| which `canonifies'
266 non-function @<kernel> arguments. In particular:
268 \item if @<kernel> is nil, then @|pprint-c-type| is called recursively
269 with a @<kernel> function that does nothing; and
270 \item if @<kernel> is any other kind of object, then @|pprint-c-type| is
271 called recursively with a @<kernel> function that prints the object as
272 if by @|princ|, preceded if necessary by space using @|c-type-space|.
277 \begin{describe}{fun}{c-type-space @<stream>}
278 Writes a space and other pretty-printing instructions to @<stream> in order
279 visually to separate a declarator from the preceding declaration
280 specifiers. The precise details are subject to change.
283 \begin{describe}{mac}
284 {maybe-in-parens (@<stream-var> @<guard-form>)
287 The @<guard-form> is evaluated, and then the @<form>s are evaluated in
288 sequence within a pretty-printer logical block writing to the stream named
289 by the symbol @<stream-var>. If the @<guard-form> evaluates to nil, then
290 the logical block has empty prefix and suffix strings; if it evaluates to a
291 non-nil value, then the logical block has prefix and suffix @`(' and @`)'
294 Note that this may cause @<stream> to be bound to a different stream object
299 \subsection{Type qualifiers and qualifiable types}
300 \label{sec:clang.ctypes.qual}
302 \begin{describe}{cls}{qualifiable-c-type (c-type) \&key :qualifiers}
303 The class @|qualifiable-c-type| describes C types which can bear
304 `qualifiers' (\Cplusplus\ calls them `cv-qualifiers'): @|const|,
305 @|restrict| and @|volatile|.
307 The @<qualifiers> are a list of keyword symbols @|:const|, @|:restrict| and
308 @|:volatile|. There is no built-in limitation to these particular
309 qualifiers; others keywords may be used, though this isn't recommended.
311 Two qualifiable types are equal only if they have \emph{matching
312 qualifiers}: i.e., every qualifier attached to one is also attached to the
313 other: order is not significant, and neither is multiplicity.
315 The class @|qualifiable-c-type| is abstract.
318 \begin{describe}{gf}{c-type-qualifiers @<c-type> @> @<list>}
319 Returns the qualifiers of the @|qualifiable-c-type| instance @<c-type> as
323 \begin{describe}{fun}{qualify-type @<c-type> @<qualifiers> @> @<c-type>}
324 The argument @<c-type> must be an instance of @|qualifiable-c-type|,
325 currently bearing no qualifiers, and @<qualifiers> a list of qualifier
326 keywords. The result is a C type object like @<c-type> except that it
327 bears the given @<qualifiers>.
329 The @<c-type> is not modified. If @<c-type> is interned, then the returned
330 type will be interned.
333 \begin{describe}{fun}{format-qualifiers @<qualifiers> @> @<string>}
334 Returns a string containing the qualifiers listed in @<qualifiers> in C
335 syntax, with a space after each. In particular, if @<qualifiers> is
336 non-null then the final character of the returned string will be a space.
340 \subsection{Leaf types} \label{sec:clang.c-types.leaf}
342 A \emph{leaf type} is a type which is not defined in terms of another type.
343 In Sod, the leaf types are
345 \item \emph{simple types}, including builtin types like @|int| and @|char|,
346 as well as type names introduced by @|typename|, because Sod isn't
347 interested in what the type name means, merely that it names a type; and
348 \item \emph{tagged types}, i.e., enum, struct and union types which are named
349 by a keyword identifying the kind of type, and a \emph{tag}.
352 \begin{describe}{cls}{simple-c-type (qualifiable-c-type)
353 \&key :qualifiers :name}
354 The class of `simple types'; an instance denotes the type @<qualifiers>
357 A simple type object maintains a \emph{name}, which is a string whose
358 contents are the C name for the type. The initarg @|:name| may be used to
359 provide this name when calling @|make-instance|.
361 Two simple type objects are equal if and only if they have @|string=| names
362 and matching qualifiers.
364 A number of symbolic type specifiers for builtin types are predefined as
365 shown in \xref{tab:codegen.c-types.simple}. These are all defined as if by
366 @|define-simple-c-type|, so can be used to construct qualified types.
370 \begin{tabular}[C]{ll} \hlx*{hv}
371 \thd{C type} & \thd{Specifiers} \\ \hlx{vhv}
372 @|void| & @|void| \\ \hlx{v}
373 @|_Bool| & @|bool| \\ \hlx{v}
374 @|char| & @|char| \\ \hlx{}
375 @|wchar_t| & @|wchar-t| \\ \hlx{v}
376 @|signed char| & @|signed-char|, @|schar| \\ \hlx{}
377 @|unsigned char| & @|unsigned-char|, @|uchar| \\ \hlx{v}
378 @|short| & @|short|, @|signed-short|, @|short-int|,
379 @|signed-short-int| @|sshort| \\ \hlx{}
380 @|unsigned short| & @|unsigned-short|, @|unsigned-short-int|,
382 @|int| & @|int|, @|signed|, @|signed-int|,
384 @|unsigned int| & @|unsigned|, @|unsigned-int|, @|uint| \\ \hlx{v}
385 @|long| & @|long|, @|signed-long|, @|long-int|,
386 @|signed-long-int|, @|slong| \\ \hlx{}
387 @|unsigned long| & @|unsigned-long|, @|unsigned-long-int|,
389 @|long long| & @|long-long|, @|signed-long-long|,
390 @|long-long-int|, \\ \hlx{}
391 & \qquad @|signed-long-long-int|,
392 @|llong|, @|sllong| \\ \hlx{v}
393 @|unsigned long long|
394 & @|unsigned-long-long|, @|unsigned-long-long-int|,
396 @|size_t| & @|size-t| \\ \hlx{}
397 @|ptrdiff_t| & @|ptrdiff-t| \\ \hlx{v}
398 @|float| & @|float| \\ \hlx{}
399 @|double| & @|double| \\ \hlx{}
400 @|long double| & @|long-double| \\ \hlx{v}
401 @|float _Imaginary| & @|float-imaginary| \\ \hlx{}
402 @|double _Imaginary|& @|double-imaginary| \\ \hlx{}
403 @|long double _Imaginary|
404 & @|long-double-imaginary| \\ \hlx{v}
405 @|float _Complex| & @|float-complex| \\ \hlx{}
406 @|double _Complex| & @|double-complex| \\ \hlx{}
407 @|long double _Complex|
408 & @|long-double-complex| \\ \hlx{v}
409 @|va_list| & @|va-list| \\ \hlx*{vh}
411 \caption{Builtin symbolic type specifiers for simple C types}
412 \label{tab:codegen.c-types.simple}
415 \begin{describe}{fun}
416 {make-simple-type @<name> \&optional @<qualifiers> @> @<c-type>}
417 Return the (unique interned) simple C type object for the C type whose name
418 is @<name> (a string) and which has the given @<qualifiers> (a list of
422 \begin{describe}{gf}{c-type-name @<c-type> @> @<string>}
423 Returns the name of a @|simple-c-type| instance @<c-type> as an immutable
427 \begin{describe}{mac}
428 {define-simple-c-type \=@{ @<name> @! (@<name>^+) @} @<string> \+ \\
429 @[[ @|:export| @<export-flag> @]] \-
431 Define type specifiers for a new simple C type. Each symbol @<name> is
432 defined as a symbolic type specifier for the (unique interned) simple C
433 type whose name is the value of @<string>. Further, each @<name> is
434 defined to be a type operator: the type specifier @|(@<name>
435 @<qualifier>^*)| evaluates to the (unique interned) simple C type whose
436 name is @<string> and which has the @<qualifiers> (which are evaluated).
438 Furthermore, a variable @|c-type-@<name>| is defined, for the first @<name>
439 only, and initialized with the newly constructed C type object.
441 If @<export-flag> is true, then the @|c-type-@<name>| variable name, and
442 all of the @<name>s, are exported from the current package.
445 \begin{describe}{cls}{tagged-c-type (qualifiable-c-type)
446 \&key :qualifiers :tag}
447 Provides common behaviour for C tagged types. A @<tag> is a string
448 containing a C identifier.
450 Two tagged types are equal if and only if they have the same class, their
451 @<tag>s are @|string=|, and they have matching qualifiers. (User-defined
452 subclasses may have additional methods on @|c-type-equal-p| which impose
453 further restrictions.)
456 Sod maintains distinct namespaces for the three kinds of tagged types. In
457 C, there is only one namespace for tags which is shared between enums,
461 \begin{describe}{gf}{c-tagged-type-kind @<c-type> @> @<keyword>}
462 Returns a keyword classifying the tagged @<c-type>: one of @|:enum|,
463 @|:struct| or @|:union|. User-defined subclasses of @|tagged-c-type|
464 should return their own classification symbols. It is intended that
465 @|(string-downcase (c-tagged-type-kind @<c-type>))| be valid C
467 Alas, C doesn't provide a syntactic category for these keywords;
468 \Cplusplus\ calls them a @<class-key>.} %
469 There is a method defined for each of the built-in tagged type classes
470 @|c-struct-type|, @|c-union-type| and @|c-enum-type|.
473 \begin{describe}{gf}{kind-c-tagged-type @<keyword> @> @<symbol>}
474 This is not quite the inverse of @|c-tagged-type-kind|. Given a keyword
475 naming a kind of tagged type, return the name of the corresponding C
476 type class as a symbol.
479 \begin{describe}{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag}
480 Represents a C enumerated type. An instance denotes the C type @|enum|
481 @<tag>. See the direct superclass @|tagged-c-type| for details.
483 The type specifier @|(enum @<tag> @<qualifier>^*)| returns the (unique
484 interned) enumerated type with the given @<tag> and @<qualifier>s (all
487 \begin{describe}{fun}
488 {make-enum-type @<tag> \&optional @<qualifiers> @> @<c-enum-type>}
489 Return the (unique interned) C type object for the enumerated C type whose
490 tag is @<tag> (a string) and which has the given @<qualifiers> (a list of
494 \begin{describe}{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag}
495 Represents a C structured type. An instance denotes the C type @|struct|
496 @<tag>. See the direct superclass @|tagged-c-type| for details.
498 The type specifier @|(struct @<tag> @<qualifier>^*)| returns the (unique
499 interned) structured type with the given @<tag> and @<qualifier>s (all
502 \begin{describe}{fun}
503 {make-struct-type @<tag> \&optional @<qualifiers> @> @<c-struct-type>}
504 Return the (unique interned) C type object for the structured C type whose
505 tag is @<tag> (a string) and which has the given @<qualifiers> (a list of
509 \begin{describe}{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag}
510 Represents a C union type. An instance denotes the C type @|union|
511 @<tag>. See the direct superclass @|tagged-c-type|
514 The type specifier @|(union @<tag> @<qualifier>^*)| returns the (unique
515 interned) union type with the given @<tag> and @<qualifier>s (all
518 \begin{describe}{fun}
519 {make-union-type @<tag> \&optional @<qualifiers> @> @<c-union-type>}
520 Return the (unique interned) C type object for the union C type whose tag
521 is @<tag> (a string) and which has the given @<qualifiers> (a list of
526 \subsection{Compound C types} \label{sec:code.c-types.compound}
528 Some C types are \emph{compound types}: they're defined in terms of existing
529 types. The classes which represent compound types implement a common
532 \begin{describe}{gf}{c-type-subtype @<c-type> @> @<subtype>}
533 Returns the underlying type of a compound type @<c-type>. Precisely what
534 this means depends on the class of @<c-type>.
538 \subsection{Pointer types} \label{sec:clang.c-types.pointer}
540 Pointers are compound types. The subtype of a pointer type is the type it
543 \begin{describe}{cls}
544 {c-pointer-type (qualifiable-c-type) \&key :qualifiers :subtype}
545 Represents a C pointer type. An instance denotes the C type @<subtype>
548 The @<subtype> may be any C type. Two pointer types are equal if and only
549 if their subtypes are equal and they have matching qualifiers.
551 The type specifier @|(* @<type-spec> @<qualifier>^*)| returns a type
552 qualified pointer-to-@<subtype>, where @<subtype> is the type specified by
553 @<type-spec> and the @<qualifier>s are qualifier keywords (which are
554 evaluated). The synonyms @|ptr| and @|pointer| may be used in place of the
557 The symbol @|string| is a type specifier for the type pointer to
558 characters; the symbol @|const-string| is a type specifier for the type
559 pointer to constant characters.
562 \begin{describe}{fun}
563 {make-pointer-type @<c-type> \&optional @<qualifiers>
564 @> @<c-pointer-type>}
565 Return an object describing the type qualified pointer to @<subtype>.
566 If @<subtype> is interned, then the returned pointer type object is
571 \subsection{Array types} \label{sec:clang.c-types.array}
573 Arrays implement the compound-type protocol. The subtype of an array type is
574 the array element type.
576 \begin{describe}{cls}{c-array-type (c-type) \&key :subtype :dimensions}
577 Represents a multidimensional C array type. The @<dimensions> are a list
578 of dimension specifiers $d_0$, $d_1$, \ldots, $d_{n-1}$; an instance then
579 denotes the C type @<subtype> @|[$d_0$][$d_1$]$\ldots$[$d_{n-1}$]|. An
580 individual dimension specifier is either a string containing a C integral
581 constant expression, or nil which is equivalent to an empty string. Only
582 the first (outermost) dimension $d_0$ should be empty.
584 C doesn't actually have multidimensional arrays as a primitive notion;
585 rather, it permits an array (with known extent) to be the element type of
586 an array, which achieves an equivalent effect. C arrays are stored in
587 row-major order: i.e., if we write down the indices of the elements of an
588 array in order of ascending address, the rightmost index varies fastest;
589 hence, the type constructed is more accurately an array of $d_0$ arrays of
590 $d_1$ of \ldots\ arrays of $d_{n-1}$ elements of type @<subtype>. We shall
591 continue to abuse terminology and refer to multidimensional arrays.
593 The type specifier @|([] @<type-spec> @<dimension>^*)| constructs a
594 multidimensional array with the given @<dimension>s whose elements have the
595 type specified by @<type-spec>. If no dimensions are given then a
596 single-dimensional array with unspecified extent. The synonyms @|array|
597 and @|vector| may be used in place of the brackets @`[]'.
600 \begin{describe}{fun}
601 {make-array-type @<subtype> @<dimensions> @> @<c-array-type>}
602 Return an object describing the type of arrays with given @<dimensions> and
603 with element type @<subtype> (an instance of @|c-type|). The @<dimensions>
604 argument is a list whose elements are strings or nil; see the description
605 of the class @|c-array-type| above for details.
608 \begin{describe}{gf}{c-array-dimensions @<c-type> @> @<list>}
609 Returns the dimensions of @<c-type>, an array type, as an immutable list.
613 \subsection{Function types} \label{sec:clang.c-types.fun}
615 Function types implement the compound-type protocol. The subtype of a
616 function type is the type of the function's return value.
618 \begin{describe}{cls}{argument}
619 Represents an ordinary function argument.
622 \begin{describe}{fun}{argumentp @<value> @> @<generalized-boolean>}
623 Decide whether @<value> is an @<argument> object: if so, return non-nil; if
627 \begin{describe}{fun}
628 {make-argument @<name> @<c-type> \&optional @<default> @> @<argument>}
629 Construct and a return a new @<argument> object. The argument has type
630 @<c-type>, which must be a @|c-type| object, and is named @<name>.
632 The @<name> may be nil to indicate that the argument has no name: in this
633 case the argument will be formatted as an abstract declarator, which is not
634 suitable for function definitions. If @<name> is not nil, then the
635 @<name>'s print representation, with @|*print-escape*| nil, is used as the
638 A @<default> may be supplied. If the argument is used in a
639 keyword-argument list (e.g., in a \descref{c-keyword-function-type}
640 [object]{cls}), and the @<default> value is provided and non-nil, then its
641 (unescaped) printed representation is used to provide a default value if
642 the keyword argument is not supplied by the caller.
646 {\dhead{fun}{argument-name @<argument> @> @<name>}
647 \dhead{fun}{argument-type @<argument> @> @<c-type>}
648 \dhead{fun}{argument-default @<argument> @> @<default>}}
649 Accessor functions for @|argument| objects. They return the appropriate
650 component of the object, as set by to @|make-argument|. The @<default> is
651 nil if no default was provided to @|make-argument|.
655 {commentify-argument-name @<name> @> @<commentified-name>}
656 Convert the argument name @<name> so that it's suitable to declare the
657 function in a header file.
659 Robust header files shouldn't include literal argument names in
660 declarations of functions or function types, since this restricts the
661 including file from defining such names as macros. This generic function
662 is used to convert names into a safe form.
664 \begin{describe}{meth}{commentify-argument-name (@<name> null) @> nil}
665 Returns nil: if the argument name is already omitted, it's safe for use
668 \begin{describe}{meth}{commentify-argument-name (@<name> t) @> @<string>}
669 Returns the print form of @<name> wrapped in a C comment, as
674 \begin{describe}{fun}
675 {commentify-argument-names @<arguments> @> @<commentified-arguments>}
676 Convert the @<arguments> list so that it's suitable for use in a header
679 The @<arguments> list should be a list whose items are @|argument| objects
680 or the keyword @|:ellipsis|. The return value is a list constructed as
681 follows. For each @|argument| object in the input list, there is a
682 corresponding @|argument| object in the returned list, with the same type,
683 and whose name is the result of @|commentify-argument-name| applied to the
684 input argument name; an @|:ellipsis| in the input list is passed through
688 \begin{describe}{cls}{c-function-type (c-type) \&key :subtype :arguments}
689 Represents C function types. An instance denotes the type of a C
690 function which accepts the @<arguments> and returns @<subtype>.
692 The @<arguments> are a possibly empty list. All but the last element of
693 the list must be @|argument| objects; the final element may instead be the
694 keyword @|:ellipsis|, which denotes a variable argument list.
696 An @<arguments> list consisting of a single argument with type @|void| is
697 converted into an empty list. On output as C code, an empty argument list
698 is written as @|void|. It is not possible to represent a pre-ANSI C
699 function without prototypes.
701 Two function types are considered to be the same if their return types are
702 the same, and their argument lists consist of arguments with the same type,
703 in the same order, and either both or neither argument list ends with
704 @|:ellipsis|; argument names are not compared.
709 @{ (@<arg-name> @<arg-type>) @}^*
710 @[:ellipsis @! . @<form>@])
712 constructs a function type. The function has the subtype @<return-type>.
713 The remaining items in the type-specifier list are used to construct the
714 argument list. The argument items are a possibly improper list, beginning
715 with zero or more \emph{explicit arguments}: two-item
716 @<arg-name>/@<arg-type> lists. For each such list, an @|argument| object
717 is constructed with the given name (evaluated) and type. Following the
718 explicit arguments, there may be
720 \item nothing, in which case the function's argument list consists only of
721 the explicit arguments;
722 \item the keyword @|:ellipsis|, as the final item in the type-specifier
723 list, indicating a variable argument list may follow the explicit
725 \item a possibly-improper list tail, beginning with an atom either as a
726 list item or as the final list cdr, indicating that the entire list tail
727 is Lisp expression which is to be evaluated to compute the remaining
730 A tail expression may return a list of @|argument| objects, optionally
731 followed by an @|:ellipsis|.
735 (c-type (fun \=(lisp (c-type-subtype other-func)) \+ \\
736 ("first" int) . (c-function-arguments other-func))
738 evaluates to a function type like @|other-func|, only with an additional
739 argument of type @|int| added to the front of its argument list. This
740 could also have been written
742 (let (\=(args (c-function-arguments other-func)) \+ \\
743 (ret (c-type-subtype other-func))) \- \\ \ind
744 (c-type (fun \=(lisp ret) ("first" int) . args)
748 \begin{describe}{cls}
749 {c-keyword-function-type (c-function-type)
750 \&key :subtype :arguments :keywords}
751 Represents `functions' which accept keyword arguments. Of course, actual C
752 functions can't accept keyword arguments directly, but this type is useful
753 for describing messages and methods which deal with keyword arguments.
755 An instance denotes the type of C function which accepts the position
756 argument list @<arguments>, and keyword arguments from the @<keywords>
757 list, and returns @<subtype>. Either or both of the @<arguments> and
758 @<keywords> lists may be empty. (It is important to note the distinction
759 between a function which doesn't accept keyword arguments, and one which
760 does but for which no keyword arguments are defined. In particular, the
761 latter function can be changed later to accept a keyword argument without
762 breaking compatibility with old code.) The @<arguments> and @<keywords>
763 lists must \emph{not} contain @|:ellipsis| markers: a function can accept
764 keywords, or a variable-length argument tail, but not both.
766 Keyword arguments may (but need not) have a \emph{default value} which is
767 supplied to the function body if the keyword is omitted.
769 Keyword functions are never considered to be the same as ordinary
770 functions. Two keyword function types are considered to be the same if
771 their return types are the same, and their positional argument lists consist of
772 arguments with the same type, in the same order: the keyword arguments
773 accepted by the functions is not significant.
775 Keyword functions are constructed using an extended version of the @|fun|
776 specifier used for ordinary C function types. The extended syntax is as
779 (fun \=@<return-type>
780 @{ (@<arg-name> @<arg-type>) @}^* \+ \\
781 @{ \=:keys @{ (@<kw-name> @<kw-type> @[@<kw-default>@]) @}^*
782 @[. @<form>@] @! \+ \\
785 where either the symbol @|:keys| appears literally in the specifier, or the
786 @<form> evaluates to a list containing the symbol @|:keys|. (If neither of
787 these circumstances obtains, then the specifier constructs an ordinary
790 See the description of \descref{c-function-type}{cls} for how a trailing
793 The list of @<arg-name>s and @<arg-type>s describes the positional
794 arguments. The list of @<kw-name>s, @<kw-type>s and @<kw-defaults>s
795 describes the keyword arguments.
798 \begin{describe}{fun}
799 {make-function-type @<subtype> @<arguments> @> @<c-function-type>}
800 Construct and return a new function type, returning @<subtype> and
801 accepting the @<arguments>.
803 If the @<arguments> list contains a @|:keys| marker, then a
804 \descref{c-keyword-function-type}[object]{cls} is returned: those arguments
805 preceding the @|:keys| marker form the positional argument list, and those
806 following the marker form the list of keyword arguments.
809 \begin{describe}{fun}
810 {make-keyword-function-type @<subtype> @<arguments> @<keywords>
811 \nlret @<c-keyword-function-type>}
812 Construct and return a new keyword-function type, returning @<subtype> and
813 accepting the @<arguments> and @<keywords>.
817 {c-function-arguments @<c-function-type> @> @<arguments>}
818 Return the arguments list of the @<c-function-type>.
821 \begin{describe}{fun}
822 {commentify-function-type @<c-function-type> @> @<commentified-c-type>}
823 Return a commentified version of the @<c-function-type>.
825 The returned type has the same subtype as the given type, and the argument
826 list of the returned type is the result of applying
827 @|commentify-argument-names| to the argument list of the given type.
830 \begin{describe}{fun}{reify-variable-argument-tail @<arguments> @> @<list>}
831 If the @<argument> list contains an @|:ellipsis| marker, then replace it
832 with a @|va_list|. The name for the new argument, if any, is taken from
833 the \descref{*sod-ap*}[variable]{var}. The new list is returned; the
834 original list is not modified, but may share structure with the new list.
837 \begin{describe}{fun}{merge-keyword-lists @<lists> @> @<list>}
838 Merge a number of keyword-argument lists together and return the result.
840 The @<lists> parameter is a list consisting of a number of @|(@<args>
841 . @<origin>)| pairs: in each pair, @<args> is a list of
842 \descref{argument}{cls} objects, and @<origin> is either nil or an object
843 whose printed representation describes the origin of the corresponding
844 @<args> list, suitable for inclusion in an error message.
846 The resulting list contains exactly one argument for each distinct argument
847 name appearing in the input @<lists>; this argument will contain the
848 default value from the earliest occurrence in the input @<lists> of an
849 argument with that name.
851 If the same name appears multiple times with different types, an error is
852 signalled quoting the name, conflicting types, and (if non-nil) the origins
853 of the offending argument objects.
856 \begin{describe}{fun}
857 {pprint-c-function-type @<return-type> @<stream>
858 @<print-args> @<print-kernel>}
859 Provides the top-level structure for printing C function types.
861 Output is written to @<stream> to describe a function type returning
862 @<return-type>, whose declarator kernel (containing the name, and any
863 further type operands) will be printed by @<print-kernel>, and whose
864 arguments, if any, will be printed by @<print-args>.
866 The @<print-kernel> function is a standard kernel-printing function
867 following the \descref{pprint-c-type}[protocol]{gf}.
869 The @<print-args> function is given a single argument, which is the
870 @<stream> to print on. It should not print the surrounding parentheses.
872 The output written to @<stream> looks approximately like
874 @<return-type> @<kernel>(@<args>)
878 \begin{describe}{fun}{pprint-argument-list @<args> @<stream> @> @<flag>}
879 Print an argument list to @<stream>.
881 The @<args> is a list of \descref{argument}[objects]{cls}, optionally
882 containing an @|:ellipsis| marker. The function returns true if any
883 arguments were actually printed.
887 \subsection{Parsing C types} \label{sec:clang.c-types.parsing}
889 \begin{describe}{fun}
890 {parse-c-type @<scanner>
891 @> @<result> @<success-flag> @<consumed-flag>}
894 \begin{describe}{fun}
895 {parse-declarator @<scanner> @<base-type> \&key :kernel :abstractp
896 \nlret @<result> @<success-flag> @<consumed-flag>}
900 \subsection{Class types} \label{sec:clang.c-types.class}
902 \begin{describe}{cls}
903 {c-class-type (simple-c-type) \&key :class :tag :qualifiers :name}
907 {\dhead{gf}{c-type-class @<class-type> @> @<class>}
908 \dhead{gf}{setf (c-type-class @<class-type>) @<class>}}
911 \begin{describe}{fun}{find-class-type @<name> @> @<class-type-or-nil>}
914 \begin{describe}{fun}
915 {make-class-type @<name> \&optional @<qualifiers> @> @<class-type>}
918 \begin{describe}{fun}
919 {make-class-type @<name> \&optional @<qualifiers> @> @<class-type>}
922 \begin{describe}{fun}{find-sod-class @<name> @> @<class>}
925 \begin{describe}{fun}{record-sod-class @<class>}
928 %%%--------------------------------------------------------------------------
929 \section{Generating C code} \label{sec:clang.codegen}
931 This section deals with Sod's facilities for constructing and manipulating C
932 expressions, declarations, instructions and definitions.
935 \subsection{Temporary names} \label{sec:clang.codegen.temporaries}
937 Many C-level objects, especially ones with external linkage or inclusion in a
938 header file, are assigned names which are simple strings, perhaps fixed ones,
939 perhaps constructed. Other objects don't need meaningful names, and
940 suitably unique constructed names would be tedious and most likely rather
941 opaque. Therefore Sod has an ability to construct \emph{temporary names}.
943 These aren't temporary in the sense that they name C objects which have
944 limited lifetimes at runtime. Rather, the idea is that the names be
945 significant only to small pieces of Lisp code, which will soon forget about
948 \subsubsection{The temporary name protocol}
949 Temporary names are represented by objects which implement a simple protocol.
951 \begin{describe}{gf}{format-temporary-name @<var> @<stream>}
955 {\dhead{gf}{var-in-use-p @<var> @> @<generalized-boolean>}
956 \dhead[setf var-in-use-p]
957 {gf}{setf (var-in-use-p @<var>) @<generalized-boolean>}}
960 \subsubsection{Temporary name objects}
962 \begin{describe}{cls}{temporary-name () \&key :tag}
963 A temporary name object. This is the root of a small collection of
964 subclasses, but is also usable on its own.
967 \begin{describe}{meth}
968 {commentify-argument-name (@<name> temporary-name) @> nil}
972 \begin{tabular}[C]{*2{>{\codeface}l}} \hlx*{hv}
973 \thd{\textbf{Class}} & \thd{\textbf{Name format}} \\ \hlx{vhv}
974 temporary-name & @<tag> \\
975 temporary-argument & sod__a@<tag> \\
976 temporary-function & sod__f@<tag> \\
977 temporary-variable & sod__v@<tag> \\ \hlx*{vh}
979 \caption{Temporary name formats}
980 \label{tab:codegen.codegen.temps-format}
983 \begin{describe}{cls}{temporary-argument (temporary-name) \&key :tag}
986 \begin{describe}{cls}{temporary-function (temporary-name) \&key :tag}
989 \begin{describe}{fun}{temporary-function @> @<name>}
992 \begin{describe}{cls}
993 {temporary-variable (temporary-name) \&key :tag :in-use-p}
996 \subsubsection{Well-known `temporary' names}
999 \begin{tabular}[C]{*2{>{\codeface}l}} \hlx*{hv}
1000 \thd{\textbf{Variable}} & \thd{\textbf{Name format}} \\ \hlx{vhv}
1001 {}*sod-ap* & sod__ap \\
1002 {}*sod-master-ap* & sod__master_ap \\
1003 {}*null-pointer* & NULL \\ \hlx*{vh}
1005 \caption{Well-known temporary names}
1006 \label{tab:codegen.codegen.well-known-temps}
1010 \subsection{Instructions} \label{sec:clang.codegen.insts}
1012 \begin{describe}{cls}{inst () \&key}
1015 \begin{describe}{gf}{inst-metric @<inst>}
1018 \begin{describe}{mac}
1019 {definst @<code> (@<streamvar> \&key @<export>) (@<arg>^*) \\ \ind
1020 @[[ @<declaration>^* @! @<doc-string> @]] \\
1025 \begin{describe}{mac}
1026 {format-compound-statement
1027 (@<stream> @<child> \&optional @<morep>) \\ \ind
1032 \begin{describe}{fun}
1033 {format-banner-comment @<stream> @<control> \&rest @<args>}
1037 \begin{tabular}[C]{ll>{\codeface}l} \hlx*{hv}
1040 \thd{Output format} \\ \hlx{vhv}
1041 @|var| & @<name> @<type> @|\&optional| @<init>
1042 & @<type> @<name> @[= @<init>@];
1044 @|set| & @<var> @<expr> & @<var> = @<expr>; \\ \hlx{v}
1045 @|update| & @<var> @<op> @<expr> & @<var> @<op>= @<expr>;
1047 @|cond| & @<cond> @<conseq> @<alt> & @<cond> ? @<conseq> : @<alt>
1049 @|return| & @<expr> & return @[@<expr>@];
1051 @|break| & --- & break; \\ \hlx{v}
1052 @|continue| & --- & continue; \\ \hlx{v}
1053 @|expr| & @<expr> & @<expr>; \\ \hlx{v}
1054 @|call| & @<func> @|\&rest| @<args>
1057 @<arg>_n) \\ \hlx{v}
1058 @|banner| & @<control> @|\&rest| @<args>
1059 & /* @<banner> */ \\ \hlx{vhv}
1060 @|block| & @<decls> @<body> & \{ @[@<decls>@] @<body> \}
1062 @|if| & @<cond> @<conseq> @|\&optional| @<alt>
1063 & if (@<cond>) @<conseq>
1064 @[else @<alt>@] \\ \hlx{v}
1065 @|for| & @<init> @<cond> @<update> @<body> &
1066 for (@<init>; @<cond>; @<update>) @<body> \\ \hlx{v}
1067 @|while| & @<cond> @<body> & while (@<cond>) @<body>
1069 @|do-while| & @<body> @<cond> & do @<body> while (@<cond>);
1072 \vtop{\hbox{\strut @<name> @<type> @<body>}
1073 \hbox{\strut \quad @|\&optional @<banner>|}
1074 \hbox{\strut \quad @|\&rest| @<banner-args>}} &
1075 \vtop{\hbox{\strut @[/* @<banner> */@]}
1076 \hbox{\strut @<type>_0 @<name>(@<type>_1 @<arg>_1, $\ldots$,
1077 @<type>_n @<arg>_n @[, \dots@])}
1078 \hbox{\strut \quad @<body>}} \\ \hlx*{vh}
1080 \caption{Instruction classes}
1081 \label{tab:codegen.codegen.insts}
1085 \subsection{Code generation} \label{sec:clang.codegen.codegen}
1087 \begin{describe}{gf}{codegen-functions @<codegen> @> @<list>}
1090 \begin{describe}{gf}
1091 {ensure-var @<codegen> @<name> @<type> \&optional @<init>}
1094 \begin{describe}{gf}{emit-inst @<codegen> @<inst>}
1097 \begin{describe}{gf}{emit-insts @<codegen> @<insts>}
1100 \begin{describe}{gf}{emit-decl @<codegen> @<decl>}
1103 \begin{describe}{gf}{emit-decls @<codegen> @<decls>}
1106 \begin{describe}{fun}{emit-banner @<codegen> @<control> \&rest @<args>}
1109 \begin{describe}{gf}{codegen-push @<codegen>}
1112 \begin{describe}{gf}{codegen-pop @<codegen> @> @<decls> @<insts>}
1115 \begin{describe}{gf}{codegen-pop-block @<codegen> @> @<block-inst>}
1118 \begin{describe}{gf}
1119 {codegen-pop-function @<codegen> @<name> @<type> @> @<name>}
1122 \begin{describe}{gf}{codegen-add-function @<codegen> @<function>}
1125 \begin{describe}{fun}
1126 {codegen-build-function @<codegen> @<name> @<type> @<vars> @<insts>
1130 \begin{describe}{gf}{temporary-var @<codegen> @<type> @> @<name>}
1133 \begin{describe}{mac}
1134 {with-temporary-var (@<codegen> @<var> @<type>) \\ \ind
1140 \begin{describe}{fun}{deliver-expr @<codegen> @<target> @<expr>}
1143 \begin{describe}{fun}
1144 {deliver-call @<codegen> @<target> @<func> \&rest @<args>}
1147 \begin{describe}{fun}{convert-stmts @<codegen> @<target> @<type> @<func>}
1150 \begin{describe}{cls}{codegen () \&key :vars :insts (:temp-index 0)}
1153 %%%--------------------------------------------------------------------------
1154 \section{Literal C code fragments} \label{sec:clang.fragment}
1156 \begin{describe}{cls}{c-fragment () \&key :location :text}
1159 \begin{describe}{gf}{c-fragment-text @<fragment> @> @<string>}
1162 \begin{describe}{fun}
1163 {scan-c-fragment @<scanner> @<end-chars>
1164 @> @<result> @<success-flag> @<consumed-flag>}
1167 \begin{describe}{fun}
1168 {parse-delimited-fragment @<scanner> @<begin> @<end> \&key :keep-end
1169 \nlret @<result> @<success-flag> @<consumed-flag>}
1172 %%%----- That's all, folks --------------------------------------------------
1174 %%% Local variables:
1176 %%% TeX-master: "sod.tex"