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