X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/678b6c0f7fe1d62abdf249b173a8a922c4e5c1d3..7119ea4ebe5d0bd756adfb12dde51a113ae408b0:/doc/clang.tex

diff --git a/doc/clang.tex b/doc/clang.tex
index 38e4b20..0c6c4bb 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -46,9 +46,11 @@ The class hierarchy is shown in~\xref{fig:codegen.c-types.classes}.
           @|c-struct-type| \\
           @|c-union-type| \\
           @|c-enum-type| \- \\
+        @|c-atomic-type| \\
         @|c-pointer-type| \- \\
       @|c-array-type| \\
-      @|c-function-type|
+      @|c-function-type| \\ \ind
+        @|c-keyword-function-type| \-
   \end{tabbing}}
   \caption{Classes representing C types}
 \label{fig:codegen.c-types.classes}
@@ -164,8 +166,16 @@ type specifier.  Type specifiers fit into two syntactic categories.
   type specifiers among its arguments.
 \end{describe}
 
-\begin{describe}{fun}{expand-c-type-spec @<type-spec> @> @<form>}
+\begin{describe}{gf}{expand-c-type-spec @<type-spec> @> @<form>}
   Returns the Lisp form that @|(c-type @<type-spec>)| would expand into.
+
+  If @<type-spec> is a list, then \descref{expand-c-type-form}{fun} is
+  invoked.
+\end{describe}
+
+\begin{describe}{gf}{expand-c-type-form @<head> @<tail> @> @<form>}
+  Returns the Lisp form that @|(c-type (@<head> . @<tail>)| would expand
+  into.
 \end{describe}
 
 \begin{describe}{gf}
@@ -298,6 +308,29 @@ argument lists for methods.  This is done by @|c-type-equal-p|.
 \subsection{Type qualifiers and qualifiable types}
 \label{sec:clang.ctypes.qual}
 
+Qualifiers -- @|const|, @|volatile|, and so on -- are represented as lists of
+keywords attached to types.  Not all C types can carry qualifiers: notably,
+function and array types cannot be qualified.
+
+For the most part, the C qualifier keywords correspond to like-named Lisp
+keywords, only the Lisp keyword names are in uppercase.  The correspondence
+is shown in \xref{tab:clang.ctypes.qual}.
+
+\begin{table}
+  \begin{tabular}[C]{*2{>{\codeface}l}l}                           \hlx*{hv}
+    \thd{\textbf{C name}}       & \thd{\textbf{Lisp name}}      \\ \hlx{vhv}
+    _Atomic                     & :atomic                       \\
+    const                       & :const                        \\
+    restrict                    & :restrict                     \\
+    volatile                    & :volatile                     \\ \hlx*{vh}
+  \end{tabular}
+  \caption{C and Lisp qualifier names} \label{tab:clang.ctypes.qual}
+\end{table}
+
+The default behaviour, on output, is to convert keywords to lowercase and
+hope for the best: special cases can be dealt with by adding appropriate
+methods to \descref{c-qualifier-keyword}{gf}.
+
 \begin{describe}{cls}{qualifiable-c-type (c-type) \&key :qualifiers}
   The class @|qualifiable-c-type| describes C types which can bear
   `qualifiers' (\Cplusplus\ calls them `cv-qualifiers'): @|const|,
@@ -335,6 +368,113 @@ argument lists for methods.  This is done by @|c-type-equal-p|.
   non-null then the final character of the returned string will be a space.
 \end{describe}
 
+\begin{describe}{gf}{c-qualifier-keyword @<qualifier> @> @<string>}
+  Return, as a string, the C keyword corresponding to the Lisp @<qualifier>.
+
+  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 @<keyword> @> @<string>}
+    Returns the @<keyword>'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 @<c-type> @> @<list>}
+  Return the @<c-type>'s qualifiers, as a list of C keyword names.
+\end{describe}
+
+
+\subsection{Storage specifiers} \label{sec:clang.ctypes.specs}
+
+Some declaration specifiers, mostly to do with how to store the specific
+object in question, are determinedly `top level', and, unlike qualifiers,
+don't stay attached to the base type when acted on by declarator operators.
+Sod calls these `storage specifiers', though no such category exists in the C
+standard.  They have their own protocol, which is similar in many ways to
+that of C types.
+
+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}
+  A type which carries storage specifiers.  The @<subtype> is the actual
+  type, and may be any C type; the @<specifiers> are a list of
+  storage-specifier objects.
+
+  The type specifier @|(specs @<subtype> @<specifier>^*)| wraps the
+  @<subtype> in a @|c-storage-specifiers-type|, carrying the @<specifier>s,
+  which are a list of storage specifiers in S-expression notation.
+\end{describe}
+
+\begin{describe}{fun}{c-type-specifiers @<type> @> @<list>}
+  Returns the list of type specifiers attached to the @<type> object, which
+  must be a @|c-storage-specifiers-type|.
+\end{describe}
+
+\begin{describe}{mac}
+    {define-c-storage-specifier-syntax @<name> @<lambda-list> \\ \ind
+      @[[ @<declaration>^* @! @<doc-string> @]] \\
+      @<form>^* \-
+     \nlret @<name>}
+
+  Defines the symbol @<name> as a new storage-specifier operator.  When a
+  list of the form @|(@<name> @<argument>^*)| is used as a storage specifier,
+  the @<argument>s are bound to fresh variables according to the
+  @<lambda-list> (a destructuring lambda-list) and the @<form>s evaluated in
+  order in the resulting lexical environment as an implicit @<progn>.  The
+  value should be a Lisp form which will evaluate to the storage-specifier
+  object described by the arguments.
+
+  The @<form>s may call @|expand-c-storage-specifier| in order to recursively
+  expand storage specifiers among its arguments.
+\end{describe}
+
+\begin{describe}{gf}{expand-c-storage-specifier @<spec> @> @<form>}
+  Returns the Lisp form that @<spec> expands to within @|(c-type (specs
+  @<subtype> @<spec>))|.
+
+  If @<spec> is a list, then \descref{expand-c-storage-specifier-form} is
+  invoked.
+\end{describe}
+
+\begin{describe}{gf}{expand-c-storage-specifier-form @<spec> @> @<form>}
+  Returns the Lisp form that @|(@<head> . @<tail>)| expands to within
+  @|(c-type (specs @<subtype> (@<head> . @<tail>)))|.
+\end{describe}
+
+\begin{describe}{gf}{pprint-c-storage-specifier @<spec> @<stream>}
+\end{describe}
+
+\begin{describe}{gf}
+    {print-c-storage-specifier @<stream> @<spec>
+                               \&optional @<colon> @<atsign>}
+\end{describe}
+
+\begin{describe}{fun}{wrap-c-type @<func> @<base-type> @> @<c-type>}
+  Apply @<func> to the underlying C type of @<base-type> to create a new
+  `wrapped' type, and attach the storage specifiers of @<base-type> to the
+  wrapped type.
+
+  If @<base-type> is \emph{not} a @|c-storage-specifiers-type|, then return
+  @|(funcall @<func> @<base-type>)|.  Otherwise, return a new
+  @|c-storage-specifiers-type|, with the same specifiers, but whose subtype
+  is the result of applying @<func> to the subtype of the original
+  @<base-type>.
+\end{describe}
+
+\begin{describe}{cls}{alignas-storage-specifier () \&key :alignment}
+  The class of @|_Alignas| storage specifiers; an instance denotes the
+  specifier @|_Alignas(@<alignment>)|.  The @<alignment> parameter may be any
+  printable object, but is usually a string or C fragment.
+
+  The storage specifier form @|(alignas @<alignment>)| returns a storage
+  specifier @|_Alignas(@<alignment>)|, where @<alignment> is evaluated.
+\end{describe}
+
 
 \subsection{Leaf types} \label{sec:clang.c-types.leaf}
 
@@ -534,6 +674,38 @@ protocol.
 \end{describe}
 
 
+\subsection{Atomic types} \label{sec:clang.c-types.atomic}
+
+Atomic types are compound types.  The subtype of an atomic type is simply the
+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}
+  Represents an atomic type.  An instance denotes the C type
+  @|_Atomic(@<subtype>)|.
+
+  The @<subtype> may be any C type.\footnote{%
+    C does not permit atomic function or array types.} %
+  Two atomic types are equal if and only if their subtypes are equal and they
+  have matching qualifiers.  It is possible, though probably not useful, to
+  have an atomic-qualified atomic type.
+
+  The type specifier @|(atomic @<type-spec> @<qualifier>^*)| returns a type
+  qualified atomic @<subtype>, where @<subtype> is the type specified by
+  @<type-spec> and the @<qualifier>s are qualifier keywords (which are
+  evaluated).
+\end{describe}
+
+\begin{describe}{fun}
+    {make-atomic-type @<c-type> \&optional @<qualifiers> @> @<c-atomic-type>}
+  Return an object describing the type qualified atomic @<subtype>.  If
+  @<subtype> is interned, then the returned atomic type object is interned
+  also.
+\end{describe}
+
+
 \subsection{Pointer types} \label{sec:clang.c-types.pointer}
 
 Pointers are compound types.  The subtype of a pointer type is the type it
@@ -623,7 +795,8 @@ function type is the type of the function's return value.
   not return nil.
 \end{describe}
 
-\begin{describe}{fun}{make-argument @<name> @<c-type> @> @<argument>}
+\begin{describe}{fun}
+    {make-argument @<name> @<c-type> \&optional @<default> @> @<argument>}
   Construct and a return a new @<argument> object.  The argument has type
   @<c-type>, which must be a @|c-type| object, and is named @<name>.
 
@@ -632,14 +805,21 @@ function type is the type of the function's return value.
   suitable for function definitions.  If @<name> is not nil, then the
   @<name>'s print representation, with @|*print-escape*| nil, is used as the
   argument name.
+
+  A @<default> may be supplied.  If the argument is used in a
+  keyword-argument list (e.g., in a \descref{c-keyword-function-type}
+  [object]{cls}), and the @<default> value is provided and non-nil, then its
+  (unescaped) printed representation is used to provide a default value if
+  the keyword argument is not supplied by the caller.
 \end{describe}
 
 \begin{describe*}
     {\dhead{fun}{argument-name @<argument> @> @<name>}
-     \dhead{fun}{argument-type @<argument> @> @<c-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|.
+     \dhead{fun}{argument-type @<argument> @> @<c-type>}
+     \dhead{fun}{argument-default @<argument> @> @<default>}}
+  Accessor functions for @|argument| objects.  They return the appropriate
+  component of the object, as set by to @|make-argument|.  The @<default> is
+  nil if no default was provided to @|make-argument|.
 \end{describe*}
 
 \begin{describe}{gf}
@@ -736,10 +916,72 @@ function type is the type of the function's return value.
   \end{prog}
 \end{describe}
 
+\begin{describe}{cls}
+    {c-keyword-function-type (c-function-type)
+      \&key :subtype :arguments :keywords}
+  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.
+
+  An instance denotes the type of C function which accepts the position
+  argument list @<arguments>, and keyword arguments from the @<keywords>
+  list, and returns @<subtype>.  Either or both of the @<arguments> and
+  @<keywords> lists may be empty.  (It is important to note the distinction
+  between a function which doesn't accept keyword arguments, and one which
+  does but for which no keyword arguments are defined.  In particular, the
+  latter function can be changed later to accept a keyword argument without
+  breaking compatibility with old code.)  The @<arguments> and @<keywords>
+  lists must \emph{not} contain @|:ellipsis| markers: a function can accept
+  keywords, or a variable-length argument tail, but not both.
+
+  Keyword arguments may (but need not) have a \emph{default value} which is
+  supplied to the function body if the keyword is omitted.
+
+  Keyword functions are never considered to be the same as ordinary
+  functions.  Two keyword function types are considered to be the same if
+  their return types are the same, and their positional argument lists consist of
+  arguments with the same type, in the same order: the keyword 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 \=@<return-type>
+           @{ (@<arg-name> @<arg-type>) @}^* \+ \\
+           @{ \=:keys @{ (@<kw-name> @<kw-type> @[@<kw-default>@]) @}^*
+                   @[. @<form>@] @! \+ \\
+                 . @<form> @}
+  \end{prog}
+  where either the symbol @|:keys| appears literally in the specifier, or the
+  @<form> evaluates 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{c-function-type}{cls} for how a trailing
+  @<form> is handled.
+
+  The list of @<arg-name>s and @<arg-type>s describes the positional
+  arguments.  The list of @<kw-name>s, @<kw-type>s and @<kw-defaults>s
+  describes the keyword arguments.
+\end{describe}
+
 \begin{describe}{fun}
     {make-function-type @<subtype> @<arguments> @> @<c-function-type>}
   Construct and return a new function type, returning @<subtype> and
   accepting the @<arguments>.
+
+  If the @<arguments> list contains a @|:keys| marker, then a
+  \descref{c-keyword-function-type}[object]{cls} is returned: those arguments
+  preceding the @|:keys| marker form the positional argument list, and those
+  following the marker form the list of keyword arguments.
+\end{describe}
+
+\begin{describe}{fun}
+    {make-keyword-function-type @<subtype> @<arguments> @<keywords>
+      \nlret @<c-keyword-function-type>}
+  Construct and return a new keyword-function type, returning @<subtype> and
+  accepting the @<arguments> and @<keywords>.
 \end{describe}
 
 \begin{describe}{gf}
@@ -756,6 +998,32 @@ function type is the type of the function's return value.
   @|commentify-argument-names| to the argument list of the given type.
 \end{describe}
 
+\begin{describe}{fun}{reify-variable-argument-tail @<arguments> @> @<list>}
+  If the @<argument> list contains an @|:ellipsis| marker, then replace it
+  with a @|va_list|.  The name for the new argument, if any, is taken from
+  the \descref{*sod-ap*}[variable]{var}.  The new list is returned; the
+  original list is not modified, but may share structure with the new list.
+\end{describe}
+
+\begin{describe}{fun}{merge-keyword-lists @<lists> @> @<list>}
+  Merge a number of keyword-argument lists together and return the result.
+
+  The @<lists> parameter is a list consisting of a number of @|(@<args>
+  . @<origin>)| pairs: in each pair, @<args> is a list of
+  \descref{argument}{cls} objects, and @<origin> is either nil or an object
+  whose printed representation describes the origin of the corresponding
+  @<args> list, suitable for inclusion in an error message.
+
+  The resulting list contains exactly one argument for each distinct argument
+  name appearing in the input @<lists>; this argument will contain the
+  default value from the earliest occurrence in the input @<lists> of an
+  argument with that name.
+
+  If the same name appears multiple times with different types, an error is
+  signalled quoting the name, conflicting types, and (if non-nil) the origins
+  of the offending argument objects.
+\end{describe}
+
 \begin{describe}{fun}
     {pprint-c-function-type @<return-type> @<stream>
                             @<print-args> @<print-kernel>}
