X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/e43d353268fc869045f757932d78d6073db9de6e..4fd69126f8b52945e0a572d1cf4a347468c1ced5:/doc/clang.tex diff --git a/doc/clang.tex b/doc/clang.tex index e8bb1b5..700033f 100644 --- a/doc/clang.tex +++ b/doc/clang.tex @@ -65,11 +65,12 @@ specified to return interned objects: programs may rely on receiving the same (@|eq|) type object for similar (possibly merely @|equal|) arguments. Where not specified, clients may still not rely on receiving fresh objects. -A convenient S-expression notation is provided by the @|c-type| macro. Use -of this macro is merely an abbreviation for corresponding use of the various -constructor functions, and therefore interns type objects in the same manner. -The syntax accepted by the macro can be extended in order to support new -classes: see @|defctype|, @|c-type-alias| and @|define-c-type-syntax|. +A convenient S-expression notation is provided by the +\descref{c-type}[macro]{mac}. Use of this macro is merely an abbreviation +for corresponding use of the various constructor functions, and therefore +interns type objects in the same manner. The syntax accepted by the macro +can be extended in order to support new classes: see \descref{defctype}{mac}, +\descref{c-type-alias}{mac} and \descref{define-c-type-syntax}{mac}. The descriptions of each of the various classes include descriptions of the initargs which may be passed to @|make-instance| when constructing a new @@ -80,14 +81,15 @@ syntax are strongly recommended over direct use of @|make-instance|. There are two protocols for printing C types. Unfortunately they have similar names. \begin{itemize} -\item The @|print-c-type| function prints a C type value using the - S-expression notation. It is mainly useful for diagnostic purposes. -\item The @|pprint-c-type| function prints a C type as a C-syntax - declaration. +\item The \descref{print-c-type}[function]{gf} prints a C type value using + the S-expression notation. It is mainly useful for diagnostic purposes. +\item The \descref{pprint-c-type}[function]{gf} prints a C type as a + C-syntax declaration. \end{itemize} Neither generic function defines a default primary method; subclasses of @|c-type| must define their own methods in order to print correctly. + \subsection{The C type root class} \label{sec:clang.c-types.root} \begin{describe}{cls}{c-type ()} @@ -100,6 +102,7 @@ Neither generic function defines a default primary method; subclasses of The class @|c-type| is abstract. \end{describe} + \subsection{C type S-expression notation} \label{sec:clang.c-types.sexp} The S-expression representation of a type is described syntactically as a @@ -161,8 +164,16 @@ type specifier. Type specifiers fit into two syntactic categories. type specifiers among its arguments. \end{describe} -\begin{describe}{fun}{expand-c-type-spec @ @> @

} +\begin{describe}{gf}{expand-c-type-spec @ @> @} Returns the Lisp form that @|(c-type @)| would expand into. + + If @ is a list, then \descref{expand-c-type-form}{fun} is + invoked. +\end{describe} + +\begin{describe}{gf}{expand-c-type-form @ @ @> @} + Returns the Lisp form that @|(c-type (@ . @)| would expand + into. \end{describe} \begin{describe}{gf} @@ -177,6 +188,7 @@ type specifier. Type specifiers fit into two syntactic categories. default method. \end{describe} + \subsection{Comparing C types} \label{sec:clang.c-types.cmp} It is necessary to compare C types for equality, for example when checking @@ -207,6 +219,7 @@ argument lists for methods. This is done by @|c-type-equal-p|. \end{describe} \end{describe} + \subsection{Outputting C types} \label{sec:clang.c-types.output} \begin{describe}{gf}{pprint-c-type @ @ @} @@ -243,15 +256,14 @@ argument lists for methods. This is done by @|c-type-equal-p|. directly attached. If the @ function intends to provide its own additional declarator operators, it should check the @ in order to determine whether parentheses are necessary. See also the - @|maybe-in-parens| macro (page~\pageref{mac:maybe-in-parens}). + \descref{maybe-in-parens}[macro]{mac}. The @ argument indicates whether a space needs to be printed in order to separate the declarator from the declaration specifiers. A kernel which contains an identifier should insert a space before the identifier when @ is non-nil. An `empty' kernel, as found in an abstract declarator (one that specifies no name), looks more pleasing without a - trailing space. See also the @|c-type-space| function - (page~\pageref{fun:c-type-space}). + trailing space. See also the \descref{c-type-space}[function]{fun}. Every concrete subclass of @|c-type| is expected to provide a primary method on this function. There is no default primary method. @@ -290,6 +302,7 @@ argument lists for methods. This is done by @|c-type-equal-p|. within the @s. \end{describe} + \subsection{Type qualifiers and qualifiable types} \label{sec:clang.ctypes.qual} @@ -303,8 +316,8 @@ argument lists for methods. This is done by @|c-type-equal-p|. qualifiers; others keywords may be used, though this isn't recommended. Two qualifiable types are equal only if they have \emph{matching - qualifiers}: i.e., every qualifier attached to one is also attached to - the other: order is not significant, and neither is multiplicity. + qualifiers}: i.e., every qualifier attached to one is also attached to the + other: order is not significant, and neither is multiplicity. The class @|qualifiable-c-type| is abstract. \end{describe} @@ -324,12 +337,30 @@ argument lists for methods. This is done by @|c-type-equal-p|. type will be interned. \end{describe} -\begin{describe}{fun}{format-qualifiers @} +\begin{describe}{fun}{format-qualifiers @ @> @} Returns a string containing the qualifiers listed in @ in C syntax, with a space after each. In particular, if @ is non-null then the final character of the returned string will be a space. \end{describe} +\begin{describe}{gf}{c-qualifier-keyword @ @> @} + Return, as a string, the C keyword corresponding to the Lisp @. + + There is a standard method, which deals with many qualifiers. Additional + methods exist for qualifier keywords which need special handling, such as + @|:atomic|; they are not listed here explicitly. + + \begin{describe}{meth}{c-qualifier-keyword @ @> @} + Returns the @'s print-name, in lower case. This is sufficient + for the standard qualifiers @|:const|, @|:restrict|, and @|:volatile|. + \end{describe} +\end{describe} + +\begin{describe}{fun}{c-type-qualifier-keywords @ @> @} + Return the @'s qualifiers, as a list of C keyword names. +\end{describe} + + \subsection{Leaf types} \label{sec:clang.c-types.leaf} A \emph{leaf type} is a type which is not defined in terms of another type. @@ -515,6 +546,7 @@ In Sod, the leaf types are keywords). \end{describe} + \subsection{Compound C types} \label{sec:code.c-types.compound} Some C types are \emph{compound types}: they're defined in terms of existing @@ -526,10 +558,11 @@ protocol. this means depends on the class of @. \end{describe} + \subsection{Pointer types} \label{sec:clang.c-types.pointer} -Pointers compound types. The subtype of a pointer type is the type it points -to. +Pointers are compound types. The subtype of a pointer type is the type it +points to. \begin{describe}{cls} {c-pointer-type (qualifiable-c-type) \&key :qualifiers :subtype} @@ -558,6 +591,7 @@ to. interned also. \end{describe} + \subsection{Array types} \label{sec:clang.c-types.array} Arrays implement the compound-type protocol. The subtype of an array type is @@ -599,6 +633,7 @@ the array element type. Returns the dimensions of @, an array type, as an immutable list. \end{describe} + \subsection{Function types} \label{sec:clang.c-types.fun} Function types implement the compound-type protocol. The subtype of a @@ -625,8 +660,8 @@ function type is the type of the function's return value. \end{describe} \begin{describe*} - {\dhead{fun}{argument-name @ @> @} - \dhead{fun}{argument-type @ @> @}} + {\dhead{fun}{argument-name @ @> @} + \dhead{fun}{argument-type @ @> @}} Accessor functions for @|argument| objects. They return the name (for @|argument-name|) or type (for @|argument-type|) from the object, as passed to @|make-argument|. @@ -746,6 +781,7 @@ function type is the type of the function's return value. @|commentify-argument-names| to the argument list of the given type. \end{describe} + \subsection{Parsing C types} \label{sec:clang.c-types.parsing} \begin{describe}{fun} @@ -758,6 +794,7 @@ function type is the type of the function's return value. \nlret @ @ @} \end{describe} + \subsection{Class types} \label{sec:clang.c-types.class} \begin{describe}{cls} @@ -792,6 +829,7 @@ function type is the type of the function's return value. This section deals with Sod's facilities for constructing and manipulating C expressions, declarations, instructions and definitions. + \subsection{Temporary names} \label{sec:clang.codegen.temporaries} Many C-level objects, especially ones with external linkage or inclusion in a @@ -859,12 +897,14 @@ Temporary names are represented by objects which implement a simple protocol. \begin{tabular}[C]{*2{>{\codeface}l}} \hlx*{hv} \thd{\textbf{Variable}} & \thd{\textbf{Name format}} \\ \hlx{vhv} {}*sod-ap* & sod__ap \\ - {}*sod-master-ap* & sod__master_ap \\ \hlx*{vh} + {}*sod-master-ap* & sod__master_ap \\ + {}*null-pointer* & NULL \\ \hlx*{vh} \end{tabular} \caption{Well-known temporary names} \label{tab:codegen.codegen.well-known-temps} \end{table} + \subsection{Instructions} \label{sec:clang.codegen.insts} \begin{describe}{cls}{inst () \&key} @@ -892,7 +932,8 @@ Temporary names are represented by objects which implement a simple protocol. \thd{Class name} & \thd{Arguments} & \thd{Output format} \\ \hlx{vhv} - @|var| & @ @ @ & @ @ @[= @@]; + @|var| & @ @ @|\&optional| @ + & @ @ @[= @@]; \\ \hlx{v} @|set| & @@ & @ = @; \\ \hlx{v} @|update| & @ @ @ & @ @= @; @@ -902,31 +943,29 @@ Temporary names are represented by objects which implement a simple protocol. @|break| & --- & break; \\ \hlx{v} @|continue| & --- & continue; \\ \hlx{v} @|expr| & @ & @; \\ \hlx{v} - @|call| & @ @ & @(@_1, + @|call| & @ @|\&rest| @ + & @(@_1, $\ldots$, - @_n) \\ \hlx{v} - @|va-start| & @ @ & va_start(@, @); - \\ \hlx{v} - @|va-copy| & @ @ & va_copy(@, @); - \\ \hlx{v} - @|va-end| & @ & va_end(@); \\ \hlx{vhv} + @_n) \\ \hlx{vhv} @|block| & @ @ & \{ @[@@] @ \} \\ \hlx{v} - @|if| & @ @ @ & if (@) @ + @|if| & @ @ @|\&optional| @ + & if (@) @ @[else @@] \\ \hlx{v} @|while| & @ @ & while (@) @ \\ \hlx{v} @|do-while| & @ @ & do @ while (@); \\ \hlx{v} @|function| & @ @ @ & - @_0 @(@_1 @_1, $\ldots$, - @_n @_n @[, \dots@]) - @ \\ \hlx*{vh} + \vtop{\hbox{\strut @_0 @(@_1 @_1, $\ldots$, + @_n @_n @[, \dots@])} + \hbox{\strut \quad @}} \\ \hlx*{vh} \end{tabular} \caption{Instruction classes} \label{tab:codegen.codegen.insts} \end{table} + \subsection{Code generation} \label{sec:clang.codegen.codegen} \begin{describe}{gf}{codegen-functions @ @> @} @@ -982,6 +1021,10 @@ Temporary names are represented by objects which implement a simple protocol. \begin{describe}{fun}{deliver-expr @ @ @} \end{describe} +\begin{describe}{fun} + {deliver-call @ @ @ \&rest @} +\end{describe} + \begin{describe}{fun}{convert-stmts @ @ @ @} \end{describe}