X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/e8d70b1b4abe17f1425aa7b8d4e582cd02372766..2c6153373f927d948a74b283ebb16330af8ee49a:/doc/clang.tex?ds=sidebyside

diff --git a/doc/clang.tex b/doc/clang.tex
index 92c822b..aebc94d 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -91,6 +91,9 @@ similar names.
 Neither generic function defines a default primary method; subclasses of
 @|c-type| must define their own methods in order to print correctly.
 
+\begin{describe}{fun}{c-name-case @<name> @> @<string>}
+\end{describe}
+
 
 \subsection{The C type root class} \label{sec:clang.c-types.root}
 
@@ -318,11 +321,11 @@ 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}
+    \thd{C name}        & \thd{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}
@@ -347,12 +350,16 @@ methods to \descref{gf}{c-qualifier-keyword}.
   The class @|qualifiable-c-type| is abstract.
 \end{describe}
 
+\begin{describe}{fun}
+    {canonify-qualifiers @<qualifiers> @> @<canonfied-qualifiers>}
+\end{describe}
+
 \begin{describe}{gf}{c-type-qualifiers @<c-type> @> @<list>}
   Returns the qualifiers of the @|qualifiable-c-type| instance @<c-type> as
   an immutable list.
 \end{describe}
 
-\begin{describe}{fun}{qualify-type @<c-type> @<qualifiers> @> @<c-type>}
+\begin{describe}{fun}{qualify-c-type @<c-type> @<qualifiers> @> @<c-type>}
   The argument @<c-type> must be an instance of @|qualifiable-c-type|,
   currently bearing no qualifiers, and @<qualifiers> a list of qualifier
   keywords.  The result is a C type object like @<c-type> except that it
@@ -438,7 +445,7 @@ complicated objects.
   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
+  If @<spec> is a list, then \descref{gf}{expand-c-storage-specifier-form} is
   invoked.
 \end{describe}
 
@@ -501,6 +508,16 @@ 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}}}
+
   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
   @|define-simple-c-type|, so can be used to construct qualified types.
@@ -535,6 +552,18 @@ In Sod, the leaf types are
                           @|ullong|                             \\ \hlx{v}
     @|size_t|           & @|size-t|                             \\ \hlx{}
     @|ptrdiff_t|        & @|ptrdiff-t|                          \\ \hlx{v}
+    @|int$n$_t|         & @|int$n$-t|
+                          (for $n \in \{ @|8|, @|16|, @|32|, @|64| \}$)
+                                                                \\ \hlx{}
+    @|uint$n$_t|        & @|uint$n$-t|                          \\ \hlx{}
+    @|int_least$n$_t|   & @|int_least$n$-t|                     \\ \hlx{}
+    @|uint_least$n$_t|  & @|uint_least$n$-t|                    \\ \hlx{}
+    @|int_fast$n$_t|    & @|int_fast$n$-t|                      \\ \hlx{}
+    @|uint_fast$n$_t|   & @|uint_fast$n$-t|                     \\ \hlx{v}
+    @|intptr_t|         & @|intptr-t|                           \\ \hlx{}
+    @|uintptr_t|        & @|uintptr-t|                          \\ \hlx{}
+    @|intmax_t|         & @|intmax-t|                           \\ \hlx{}
+    @|uintmax_t|        & @|uintmax-t|                          \\ \hlx{v}
     @|float|            & @|float|                              \\ \hlx{}
     @|double|           & @|double|                             \\ \hlx{}
     @|long double|      & @|long-double|                        \\ \hlx{v}
@@ -610,6 +639,14 @@ In Sod, the leaf types are
   structs and unions.
 \end{boxy}
 
+\begin{describe}{gf}{c-type-tag @<c-type> @> @<keyword>}
+\end{describe}
+
+\begin{describe}{fun}
+    {make-c-tagged-type @<kind> @<tag> \&optional @<qualifiers>
+      @> @<tagged-type>}
+\end{describe}
+
 \begin{describe}{gf}{c-tagged-type-kind @<c-type> @> @<keyword>}
   Returns a keyword classifying the tagged @<c-type>: one of @|:enum|,
   @|:struct| or @|:union|.  User-defined subclasses of @|tagged-c-type|
@@ -636,6 +673,7 @@ In Sod, the leaf types are
   interned) enumerated type with the given @<tag> and @<qualifier>s (all
   evaluated).
 \end{describe}
+
 \begin{describe}{fun}
     {make-enum-type @<tag> \&optional @<qualifiers> @> @<c-enum-type>}
   Return the (unique interned) C type object for the enumerated C type whose
@@ -651,6 +689,7 @@ In Sod, the leaf types are
   interned) structured type with the given @<tag> and @<qualifier>s (all
   evaluated).
 \end{describe}
+
 \begin{describe}{fun}
     {make-struct-type @<tag> \&optional @<qualifiers> @> @<c-struct-type>}
   Return the (unique interned) C type object for the structured C type whose
@@ -954,9 +993,9 @@ function type is the type of the function's return value.
 
   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.
+  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
@@ -1001,7 +1040,12 @@ function type is the type of the function's return value.
 
 \begin{describe}{gf}
     {c-function-arguments @<c-function-type> @> @<arguments>}
-  Return the arguments list of the @<c-function-type>.
+  Return the (non-keyword) argument list of the @<c-function-type>.
+\end{describe}
+
+\begin{describe}{gf}
+    {c-function-keywords @<c-function-type> @> @<keywords>}
+  Return the keyword-argument list of the @<c-function-type>.
 \end{describe}
 
 \begin{describe}{fun}
@@ -1167,17 +1211,20 @@ Temporary names are represented by objects which implement a simple protocol.
   subclasses, but is also usable on its own.
 \end{describe}
 
+\begin{describe}{gf}{temp-tag @<name> @> @<tag>}
+\end{describe}
+
 \begin{describe}{meth}{temporary-name}
     {commentify-argument-name (@<name> temporary-name) @> nil}
 \end{describe}
 
 \begin{table}
   \begin{tabular}[C]{*2{>{\codeface}l}}                            \hlx*{hv}
-    \thd{\textbf{Class}} & \thd{\textbf{Name format}}           \\ \hlx{vhv}
-    temporary-name              & @<tag>                        \\
-    temporary-argument          & sod__a@<tag>                  \\
-    temporary-function          & sod__f@<tag>                  \\
-    temporary-variable          & sod__v@<tag>                  \\ \hlx*{vh}
+    \thd{Class}         & \thd{Name format}                     \\ \hlx{vhv}
+    temporary-name      & @<tag>                                \\
+    temporary-argument  & sod__a@<tag>                          \\
+    temporary-function  & sod__f@<tag>                          \\
+    temporary-variable  & sod__v@<tag>                          \\ \hlx*{vh}
   \end{tabular}
   \caption{Temporary name formats}
   \label{tab:codegen.codegen.temps-format}
@@ -1199,11 +1246,13 @@ Temporary names are represented by objects which implement a simple protocol.
 \subsubsection{Well-known `temporary' names}
 
 \begin{table}
+  \def\x#1{\desclabel{var}{#1}}
+  \x{*sod-ap*} \x{*sod-master-ap*} \x{*null-pointer*}
   \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                \\
-    {}*null-pointer*            & NULL                          \\ \hlx*{vh}
+    \thd{Variable}      & \thd{Name format}                     \\ \hlx{vhv}
+    {}*sod-ap*          & sod__ap                               \\
+    {}*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}
@@ -1239,8 +1288,8 @@ Temporary names are represented by objects which implement a simple protocol.
 \begin{table}
   \begin{tabular}[C]{ll>{\codeface}l}                              \hlx*{hv}
     \thd{Class name} &
-    \thd{Arguments} &
-    \thd{Output format}                                         \\ \hlx{vhv}
+                  \thd{Arguments} &
+                                             \thd{Output format}\\ \hlx{vhv}
     @|var|      & @<name> @<type> @|\&optional| @<init>
                                            & @<type> @<name> @[= @<init>@];
                                                                 \\ \hlx{v}
@@ -1284,6 +1333,33 @@ Temporary names are represented by objects which implement a simple protocol.
   \label{tab:codegen.codegen.insts}
 \end{table}
 
+\begin{describe*}
+    {\dhead*{cls}{@<code>-inst (inst) \&key \dots}
+     \dhead*{fn}{make-@<code>-inst \dots}
+     \dhead*{gf}{inst-@<slot> @<inst> @> @<value>}}
+  \def\instclass#1#2#3{%
+    #1{cls}{#3-inst}[#2]%
+    #1{fun}{make-#3-inst}[#2]%
+  }
+  \def\instslot#1#2#3{#1{gf}{inst-#3}[#2]}
+  \def\makelabels#1#2{%
+    \def\x{\instclass{#1}{#2}}
+      \x{var} \x{set} \x{update} \x{cond} \x{return} \x{break} \x{continue}
+      \x{expr} \x{call} \x{banner} \x{block} \x{if} \x{for} \x{while}
+      \x{do-while} \x{function}
+    \def\x{\instslot{#1}{#2}}
+      \x{name} \x{type} \x{init} \x{var} \x{expr} \x{op} \x{cond} \x{conseq}
+      \x{alt} \x{func} \x{args} \x{control} \x{decls} \x{body} \x{update}
+      \x{banner} \x{banner-args}
+  }
+  \makelabels{\desclabel}{|(}
+
+  Sod provides a number of built-in instruction types generated by
+  \descref{mac}{definst}: see \xref{tab:codegen.codegen.insts}.
+
+  \makelabels{\descindex}{|)}
+\end{describe*}
+
 
 \subsection{Code generation} \label{sec:clang.codegen.codegen}
 
@@ -1359,8 +1435,11 @@ Temporary names are represented by objects which implement a simple protocol.
 \begin{describe}{cls}{c-fragment () \&key :location :text}
 \end{describe}
 
-\begin{describe}{gf}{c-fragment-text @<fragment> @> @<string>}
-\end{describe}
+\begin{describe*}
+    {\dhead{gf}{c-fragment-text @<fragment> @> @<string>}
+     \dhead{meth}{c-fragment}
+       {file-location (@<fragment> c-fragment) @> @<floc>}}
+\end{describe*}
 
 \begin{describe}{fun}
     {scan-c-fragment @<scanner> @<end-chars>
