X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/6e26f47b940265ad1338c642b78fcb3447b0b355..684d95c7eb6ec755d38efacbc377e9e60ba7044e:/doc/clang.tex diff --git a/doc/clang.tex b/doc/clang.tex index aebc94d..de9e8df 100644 --- a/doc/clang.tex +++ b/doc/clang.tex @@ -53,7 +53,7 @@ The class hierarchy is shown in~\xref{fig:codegen.c-types.classes}. @|c-keyword-function-type| \- \end{tabbing}} \caption{Classes representing C types} -\label{fig:codegen.c-types.classes} + \label{fig:codegen.c-types.classes} \end{figure} C type objects are immutable unless otherwise specified. @@ -181,6 +181,11 @@ type specifier. Type specifiers fit into two syntactic categories. into. \end{describe} +\begin{describe}{cty}{lisp @
^*} + Evaluates the @s as an implicit @|progn|, and returns the value(s) of + the final @ as a C type. +\end{describe} + \begin{describe}{gf} {print-c-type @ @ \&optional @ @} Print the C type object @ to @ in S-expression form. The @@ -193,6 +198,28 @@ type specifier. Type specifiers fit into two syntactic categories. default method. \end{describe} +\begin{describe*} + {\dhead{sym}{c-type} + \dhead{meth}{symbol,(eql 'c-type)} + {documentation (@ symbol) + (@ (eql 'c-type))} + \dhead{meth}{symbol,(eql 'c-type)} + {setf \=(documentation (@ symbol) + (@ (eql 'c-type))) \\ + \>@}} +\end{describe*} + +\begin{describe*} + {\dhead{sym}{c-type-form} + \dhead{meth}{symbol,(eql 'c-type-form)} + {documentation (@ symbol) + (@ (eql 'c-type-form))} + \dhead{meth}{symbol,(eql 'c-type-form)} + {setf \=(documentation (@ symbol) + (@ (eql 'c-type-form))) \\ + \>@}} +\end{describe*} + \subsection{Comparing C types} \label{sec:clang.c-types.cmp} @@ -407,16 +434,18 @@ Every Lisp keyword is potentially a storage specifier, which simply maps to its lower-case print name in C; but other storage specifiers may be more complicated objects. -\begin{describe}{cls} - {c-storage-specifiers-type (c-type) \&key :subtype :specifiers} +\begin{describe*} + {\dhead{cls}{c-storage-specifiers-type (c-type) + \&key :subtype :specifiers} + \dhead{cty}{specs @ @^*}} A type which carries storage specifiers. The @ is the actual type, and may be any C type; the @ are a list of storage-specifier objects. - The type specifier @|(specs @ @^*)| wraps the - @ in a @|c-storage-specifiers-type|, carrying the @s, - which are a list of storage specifiers in S-expression notation. -\end{describe} + The type specifier @|specs| wraps the @ in a + @|c-storage-specifiers-type|, carrying the @s, which are a list + of storage specifiers in S-expression notation. +\end{describe*} \begin{describe}{fun}{c-type-specifiers @ @> @} Returns the list of type specifiers attached to the @ object, which @@ -454,7 +483,13 @@ complicated objects. @|(c-type (specs @ (@ . @)))|. \end{describe} +\begin{describe}{cstg}{lisp @^*} + Evaluates the @s as an implicit @|progn|, and returns the value(s) of + the final @ as a storage-specifier. +\end{describe} + \begin{describe}{gf}{pprint-c-storage-specifier @ @} + Prints the storage-specifier @ to @, in C syntax. \end{describe} \begin{describe}{gf} @@ -474,14 +509,16 @@ complicated objects. @. \end{describe} -\begin{describe}{cls}{alignas-storage-specifier () \&key :alignment} - The class of @|_Alignas| storage specifiers; an instance denotes the - specifier @|_Alignas(@)|. The @ parameter may be any - printable object, but is usually a string or C fragment. - - The storage specifier form @|(alignas @)| returns a storage - specifier @|_Alignas(@)|, where @ is evaluated. -\end{describe} +\begin{describe*} + {\dhead{cls}{alignas-storage-specifier () \&key :alignment} + \dhead{cstg}{alignas @}} + The class of \mbox{@|_Alignas|} storage specifiers; an instance denotes the + specifier \mbox{@|_Alignas(@)|}. The @ parameter may + be any printable object, but is usually a string or C fragment. + + The storage specifier form @|alignas| returns a storage specifier + \mbox{@|_Alignas(@)|}, where @ is evaluated. +\end{describe*} \subsection{Leaf types} \label{sec:clang.c-types.leaf} @@ -508,15 +545,21 @@ In Sod, the leaf types are Two simple type objects are equal if and only if they have @|string=| names and matching qualifiers. - \def\x#1{\desclabel{const}{c-type-#1}} - \x{bool} \x{char} \x{wchar-t} \x{signed-char} \x{unsigned-char} \x{short} - \x{unsigned-short} \x{int} \x{unsigned} \x{long} \x{unsigned-long} - \x{long-long} \x{unsigned-long-long} \x{size-t} \x{ptrdiff-t} \x{float} - \x{double} \x{long-double} \x{float-imaginary} \x{double-imaginary} - \x{long-double-imaginary} \x{float-complex} \x{double-complex} - \x{long-double-complex} \x{va-list} \x{void} - \crossproduct\x{{{int}{uint}}{{}{-least}{-fast}}{{8}{16}{32}{64}}{{-t}}} - \crossproduct\x{{{int}{uint}}{{ptr}{max}}{{-t}}} + \def\x#1{\desclabel{cty}{#1}} + \def\y#1{\desclabel{const}{c-type-#1}\x{#1}} + \y{bool} \y{wchar-t} + \y{int} \x{signed} \y{unsigned} \y{signed-char} + \crossproduct\y{{{}{unsigned-}}{{char}{short}{long}{long-long}}} + \crossproduct\x{{{}{signed-}{unsigned-}}{{short}{long}{long-long}}{{-int}}} + \crossproduct\x{{{signed-}{unsigned-}}{{int}}} + \crossproduct\x{{{signed-}}{{short}{int}{long}{long-long}}} + \crossproduct\x{{{s}{u}}{{char}{short}{int}{long}{llong}}} \x{llong} + \y{size-t} \y{ptrdiff-t} \y{float} + \y{double} \y{long-double} \y{float-imaginary} \y{double-imaginary} + \y{long-double-imaginary} \y{float-complex} \y{double-complex} + \y{long-double-complex} \y{va-list} \y{void} + \crossproduct\y{{{int}{uint}}{{}{-least}{-fast}}{{8}{16}{32}{64}}{{-t}}} + \crossproduct\y{{{int}{uint}}{{ptr}{max}}{{-t}}} A number of symbolic type specifiers for builtin types are predefined as shown in \xref{tab:codegen.c-types.simple}. These are all defined as if by @@ -665,14 +708,15 @@ In Sod, the leaf types are type class as a symbol. \end{describe} -\begin{describe}{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag} +\begin{describe*} + {\dhead{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag} + \dhead{cty}{enum @ @^*}} Represents a C enumerated type. An instance denotes the C type @|enum| @. See the direct superclass @|tagged-c-type| for details. - The type specifier @|(enum @ @^*)| returns the (unique - interned) enumerated type with the given @ and @s (all - evaluated). -\end{describe} + The type specifier @|enum| returns the (unique interned) enumerated type + with the given @ and @s (all evaluated). +\end{describe*} \begin{describe}{fun} {make-enum-type @ \&optional @ @> @} @@ -681,14 +725,15 @@ In Sod, the leaf types are keywords). \end{describe} -\begin{describe}{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag} +\begin{describe*} + {\dhead{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag} + \dhead{cty}{struct @ @^*}} Represents a C structured type. An instance denotes the C type @|struct| @. See the direct superclass @|tagged-c-type| for details. - The type specifier @|(struct @ @^*)| returns the (unique - interned) structured type with the given @ and @s (all - evaluated). -\end{describe} + The type specifier @|struct| returns the (unique interned) structured type + with the given @ and @s (all evaluated). +\end{describe*} \begin{describe}{fun} {make-struct-type @ \&optional @ @> @} @@ -697,15 +742,17 @@ In Sod, the leaf types are keywords). \end{describe} -\begin{describe}{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag} +\begin{describe*} + {\dhead{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag} + \dhead{cty}{union @ @^*}} Represents a C union type. An instance denotes the C type @|union| @. See the direct superclass @|tagged-c-type| for details. - The type specifier @|(union @ @^*)| returns the (unique - interned) union type with the given @ and @s (all - evaluated). -\end{describe} + The type specifier @|union| returns the (unique interned) union type with + the given @ and @s (all evaluated). +\end{describe*} + \begin{describe}{fun} {make-union-type @ \&optional @ @> @} Return the (unique interned) C type object for the union C type whose tag @@ -733,8 +780,10 @@ underlying type of the object. Note that, as far as Sod is concerned, atomic types are not the same as atomic-qualified types: you must be consistent about which you use. -\begin{describe}{cls} - {c-atomic-type (qualifiable-c-type) \&key :qualifiers :subtype} +\begin{describe*} + {\dhead{cls}{c-atomic-type (qualifiable-c-type) + \&key :qualifiers :subtype} + \dhead{cty}{atomic @ @^*}} Represents an atomic type. An instance denotes the C type @|_Atomic(@)|. @@ -744,11 +793,10 @@ about which you use. have matching qualifiers. It is possible, though probably not useful, to have an atomic-qualified atomic type. - The type specifier @|(atomic @ @^*)| returns a type - qualified atomic @, where @ is the type specified by - @ and the @s are qualifier keywords (which are - evaluated). -\end{describe} + The type specifier @|atomic| returns a type qualified atomic @, + where @ is the type specified by @ and the + @s are qualifier keywords (which are evaluated). +\end{describe*} \begin{describe}{fun} {make-atomic-type @ \&optional @ @> @} @@ -763,24 +811,29 @@ about which you use. 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} +\begin{describe*} + {\dhead{cls}{c-pointer-type (qualifiable-c-type) + \&key :qualifiers :subtype} + \dhead{cty}{* @ @^*} + \dhead{cty}{string} + \dhead{cty}{const-string}} Represents a C pointer type. An instance denotes the C type @ @|*|@. The @ may be any C type. Two pointer types are equal if and only if their subtypes are equal and they have matching qualifiers. - The type specifier @|(* @ @^*)| returns a type - qualified pointer-to-@, where @ is the type specified by - @ and the @s are qualifier keywords (which are - evaluated). The synonyms @|ptr| and @|pointer| may be used in place of the - star @`*'. + \desclabel{cty}{ptr} + \desclabel{cty}{pointer} + The type specifier @|*| returns a type qualified pointer-to-@, + where @ is the type specified by @ and the + @s are qualifier keywords (which are evaluated). The synonyms + @|ptr| and @|pointer| may be used in place of the star @`*'. The symbol @|string| is a type specifier for the type pointer to characters; the symbol @|const-string| is a type specifier for the type pointer to constant characters. -\end{describe} +\end{describe*} \begin{describe}{fun} {make-pointer-type @ \&optional @ @@ -796,7 +849,11 @@ points to. Arrays implement the compound-type protocol. The subtype of an array type is the array element type. -\begin{describe}{cls}{c-array-type (c-type) \&key :subtype :dimensions} +\begin{describe*} + {\dhead{cls}{c-array-type (c-type) \&key :subtype :dimensions} + \dhead{cty}{[] @ @^*}} + \desclabel{cty}{array}[|(] + \desclabel{cty}{vec}[|(] Represents a multidimensional C array type. The @ are a list of dimension specifiers $d_0$, $d_1$, \ldots, $d_{n-1}$; an instance then denotes the C type @ @|[$d_0$][$d_1$]$\ldots$[$d_{n-1}$]|. An @@ -813,12 +870,15 @@ the array element type. $d_1$ of \ldots\ arrays of $d_{n-1}$ elements of type @. We shall continue to abuse terminology and refer to multidimensional arrays. - The type specifier @|([] @ @^*)| constructs a - multidimensional array with the given @s whose elements have the - type specified by @. If no dimensions are given then a - single-dimensional array with unspecified extent. The synonyms @|array| - and @|vector| may be used in place of the brackets @`[]'. -\end{describe} + The type specifier @|[]| constructs a multidimensional array with the given + @s whose elements have the type specified by @. If + no dimensions are given then a single-dimensional array with unspecified + extent. The synonyms @|array| and @|vec| may be used in place of the + brackets @`[]'. + + \desclabel{cty}{array}[|)] + \desclabel{cty}{vec}[|)] +\end{describe*} \begin{describe}{fun} {make-array-type @ @ @> @} @@ -910,7 +970,16 @@ function type is the type of the function's return value. unchanged. \end{describe} -\begin{describe}{cls}{c-function-type (c-type) \&key :subtype :arguments} +\begin{describe*} + {\dhead{cls}{c-function-type (c-type) \&key :subtype :arguments} + \dhead*{cty}{fun @ + @{ (@ @) @}^* + @[:ellipsis @! . @@]}} + \desclabel{cty}{()}[|(] + \desclabel{cty}{fn}[|(] + \desclabel{cty}{func}[|(] + \desclabel{cty}{function}[|(] + \descindex{cty}{fun}[|(] Represents C function types. An instance denotes the type of a C function which accepts the @ and returns @. @@ -928,19 +997,13 @@ function type is the type of the function's return value. in the same order, and either both or neither argument list ends with @|:ellipsis|; argument names are not compared. - The type specifier - \begin{prog} - (fun @ - @{ (@ @) @}^* - @[:ellipsis @! . @@]) - \end{prog} - constructs a function type. The function has the subtype @. - The remaining items in the type-specifier list are used to construct the - argument list. The argument items are a possibly improper list, beginning - with zero or more \emph{explicit arguments}: two-item - @/@ lists. For each such list, an @|argument| object - is constructed with the given name (evaluated) and type. Following the - explicit arguments, there may be + The type specifier @|fun| constructs a function type. The function has the + subtype @. The remaining items in the type-specifier list are + used to construct the argument list. The argument items are a possibly + improper list, beginning with zero or more \emph{explicit arguments}: + two-item @/@ lists. For each such list, an @|argument| + object is constructed with the given name (evaluated) and type. Following + the explicit arguments, there may be \begin{itemize} \item nothing, in which case the function's argument list consists only of the explicit arguments; @@ -968,11 +1031,18 @@ function type is the type of the function's return value. (ret (c-type-subtype other-func))) \-\\ \ind (c-type (fun \=(lisp ret) ("first" int) . args) \end{prog} -\end{describe} + \descindex{cty}{fun}[|)] +\end{describe*} -\begin{describe}{cls} - {c-keyword-function-type (c-function-type) - \&key :subtype :arguments :keywords} +\begin{describe*} + {\dhead{cls}{c-keyword-function-type (c-function-type) + \&key :subtype :arguments :keywords} + \dhead{cty}{fun \=@ + @{ (@ @) @}^* \+\\ + @{ \=:keys @{ (@ @ + @[@@]) @}^* + @[. @@] @! \+\\ + . @ @}}} Represents `functions' which accept keyword arguments. Of course, actual C functions can't accept keyword arguments directly, but this type is useful for describing messages and methods which deal with keyword arguments. @@ -998,19 +1068,11 @@ function type is the type of the function's return value. arguments accepted by the functions is not significant. Keyword functions are constructed using an extended version of the @|fun| - specifier used for ordinary C function types. The extended syntax is as - follows. - \begin{prog} - (fun \=@ - @{ (@ @) @}^* \+\\ - @{ \=:keys @{ (@ @ @[@@]) @}^* - @[. @@] @! \+\\ - . @ @} - \end{prog} - where either the symbol @|:keys| appears literally in the specifier, or the - @ evaluates to a list containing the symbol @|:keys|. (If neither of - these circumstances obtains, then the specifier constructs an ordinary - function type.) + specifier (or any of its synonyms) used for ordinary C function types. + Either the symbol @|:keys| must appear literally in the specifier, or the + @ must evaluate to a list containing the symbol @|:keys|. (If + neither of these circumstances obtains, then the specifier constructs an + ordinary function type.) See the description of \descref{cls}{c-function-type} for how a trailing @ is handled. @@ -1018,7 +1080,12 @@ function type is the type of the function's return value. The list of @s and @s describes the positional arguments. The list of @s, @s and @s describes the keyword arguments. -\end{describe} + + \descindex{cty}{()}[|)] + \descindex{cty}{fn}[|)] + \descindex{cty}{func}[|)] + \descindex{cty}{function}[|)] +\end{describe*} \begin{describe}{fun} {make-function-type @ @ @> @} @@ -1151,9 +1218,11 @@ function type is the type of the function's return value. \subsection{Class types} \label{sec:clang.c-types.class} -\begin{describe}{cls} - {c-class-type (simple-c-type) \&key :class :tag :qualifiers :name} -\end{describe} +\begin{describe*} + {\dhead{cls}{c-class-type (simple-c-type) + \&key :class :tag :qualifiers :name} + \dhead{cty}{class @ @^*}} +\end{describe*} \begin{describe*} {\dhead{gf}{c-type-class @ @> @} @@ -1335,7 +1404,7 @@ Temporary names are represented by objects which implement a simple protocol. \begin{describe*} {\dhead*{cls}{@-inst (inst) \&key \dots} - \dhead*{fn}{make-@-inst \dots} + \dhead*{fun}{make-@-inst \dots} \dhead*{gf}{inst-@ @ @> @}} \def\instclass#1#2#3{% #1{cls}{#3-inst}[#2]%