X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/cac85e0be5833902081c903f75e348b949294fb9..b492babc8de898bd22d638d7c25f24356896a3a9:/doc/clang.tex

diff --git a/doc/clang.tex b/doc/clang.tex
index 9462942..58b8cd2 100644
--- a/doc/clang.tex
+++ b/doc/clang.tex
@@ -7,7 +7,7 @@
 
 %%%----- Licensing notice ---------------------------------------------------
 %%%
-%%% This file is part of the Sensble Object Design, an object system for C.
+%%% This file is part of the Sensible Object Design, an object system for C.
 %%%
 %%% SOD is free software; you can redistribute it and/or modify
 %%% it under the terms of the GNU General Public License as published by
@@ -120,8 +120,9 @@ type specifier.  Type specifiers fit into two syntactic categories.
 \end{describe}
 
 \begin{describe}{mac}
-    {defctype @{ @<name> @! (@<name> @<nickname>^*) @} @<type-spec>
-      @> @<names>}
+    {defctype \=@{ @<name> @! (@<name>^+) @} @<type-spec> \+ \\
+                @[[ @|:export| @<export-flag> @]]^* \-
+       \nlret @<names>}
   Defines a new symbolic type specifier @<name>; if a list of @<name>s is
   given, then all are defined in the same way.  The type constructed by using
   any of the @<name>s is as described by the type specifier @<type-spec>.
@@ -129,6 +130,13 @@ type specifier.  Type specifiers fit into two syntactic categories.
   The resulting type object is constructed once, at the time that the macro
   expansion is evaluated; the same (@|eq|) value is used each time any
   @<name> is used in a type specifier.
+
+  A variable named @|c-type-@<name>|, for the first @<name> only, is defined
+  and initialized to contain the C type object so constructed.  Altering or
+  binding this name is discouraged.
+
+  If @<export-flag> is true, then the variable name, and all of the @<name>s,
+  are exported from the current package.
 \end{describe}
 
 \begin{describe}{mac}{c-type-alias @<original> @<alias>^* @> @<aliases>}
@@ -355,9 +363,11 @@ In Sod, the leaf types are
   \begin{tabular}[C]{ll}                                           \hlx*{hv}
     \thd{C type}        & \thd{Specifiers}                      \\ \hlx{vhv}
     @|void|             & @|void|                               \\ \hlx{v}
-    @|char|             & @|char|                               \\ \hlx{v}
-    @|unsigned char|    & @|unsigned-char|, @|uchar|            \\ \hlx{}
-    @|signed char|      & @|signed-char|, @|schar|              \\ \hlx{v}
+    @|_Bool|            & @|bool|                               \\ \hlx{v}
+    @|char|             & @|char|                               \\ \hlx{}
+    @|wchar_t|          & @|wchar-t|                            \\ \hlx{v}
+    @|signed char|      & @|signed-char|, @|schar|              \\ \hlx{}
+    @|unsigned char|    & @|unsigned-char|, @|uchar|            \\ \hlx{v}
     @|short|            & @|short|, @|signed-short|, @|short-int|,
                           @|signed-short-int| @|sshort|         \\ \hlx{}
     @|unsigned short|   & @|unsigned-short|, @|unsigned-short-int|,
@@ -370,17 +380,26 @@ In Sod, the leaf types are
     @|unsigned long|    & @|unsigned-long|, @|unsigned-long-int|,
                           @|ulong|                              \\ \hlx{v}
     @|long long|        & @|long-long|, @|signed-long-long|,
-                          @|long-long-int|,                     \\
+                          @|long-long-int|,                     \\ \hlx{}
                         & \qquad @|signed-long-long-int|,
                           @|llong|, @|sllong|                   \\ \hlx{v}
     @|unsigned long long|
                         & @|unsigned-long-long|, @|unsigned-long-long-int|,
                           @|ullong|                             \\ \hlx{v}
+    @|size_t|           & @|size-t|                             \\ \hlx{}
+    @|ptrdiff_t|        & @|ptrdiff-t|                          \\ \hlx{v}
     @|float|            & @|float|                              \\ \hlx{}
-    @|double|           & @|double|                             \\ \hlx{v}
-    @|va_list|          & @|va-list|                            \\ \hlx{v}
-    @|size_t|           & @|size-t|                             \\ \hlx{v}
-    @|ptrdiff_t|        & @|ptrdiff-t|                          \\ \hlx*{vh}
+    @|double|           & @|double|                             \\ \hlx{}
+    @|long double|      & @|long-double|                        \\ \hlx{v}
+    @|float _Imaginary| & @|float-imaginary|                    \\ \hlx{}
+    @|double _Imaginary|& @|double-imaginary|                   \\ \hlx{}
+    @|long double _Imaginary|
+                        & @|long-double-imaginary|              \\ \hlx{v}
+    @|float _Complex|   & @|float-complex|                      \\ \hlx{}
+    @|double _Complex|  & @|double-complex|                     \\ \hlx{}
+    @|long double _Complex|
+                        & @|long-double-complex|                \\ \hlx{v}
+    @|va_list|          & @|va-list|                            \\ \hlx*{vh}
   \end{tabular}
   \caption{Builtin symbolic type specifiers for simple C types}
   \label{tab:codegen.c-types.simple}
@@ -399,13 +418,21 @@ In Sod, the leaf types are
 \end{describe}
 
 \begin{describe}{mac}
-    {define-simple-c-type @{ @<name> @! (@<name>^*) @} @<string> @> @<name>}
+    {define-simple-c-type \=@{ @<name> @! (@<name>^+) @} @<string> \+ \\
+                            @[[ @|:export| @<export-flag> @]] \-
+      \nlret @<name>}
   Define type specifiers for a new simple C type.  Each symbol @<name> is
   defined as a symbolic type specifier for the (unique interned) simple C
   type whose name is the value of @<string>.  Further, each @<name> is
   defined to be a type operator: the type specifier @|(@<name>
   @<qualifier>^*)| evaluates to the (unique interned) simple C type whose
   name is @<string> and which has the @<qualifiers> (which are evaluated).
+
+  Furthermore, a variable @|c-type-@<name>| is defined, for the first @<name>
+  only, and initialized with the newly constructed C type object.
+
+  If @<export-flag> is true, then the @|c-type-@<name>| variable name, and
+  all of the @<name>s, are exported from the current package.
 \end{describe}
 
 \begin{describe}{cls}{tagged-c-type (qualifiable-c-type)
@@ -597,13 +624,13 @@ function type is the type of the function's return value.
   argument name.
 \end{describe}
 
-\begin{describe}{fun}{argument-name @<argument> @> @<name>}
-  Return the name of the @<argument>, as it was supplied to @|make-argument|.
-\end{describe}
-
-\begin{describe}{fun}{argument-type @<argument> @> @<c-type>}
-  Return the type of the @<argument>, as it was supplied to @|make-argument|.
-\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|.
+\end{describe*}
 
 \begin{describe}{gf}
     {commentify-argument-name @<name> @> @<commentified-name>}
@@ -657,14 +684,19 @@ 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 @|(fun @<return-type> @{ (@<arg-name> @<arg-type>) @}^*
-  @[:ellipsis @! . @<form> @])| constructs a function type.  The function has
-  the subtype @<return-type>.  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 @<arg-name>/@<arg-type> 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
+  \begin{prog}
+    (fun @<return-type>
+         @{ (@<arg-name> @<arg-type>) @}^*
+         @[:ellipsis @! . @<form>@])
+  \end{prog}
+  constructs a function type.  The function has the subtype @<return-type>.
+  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
+  @<arg-name>/@<arg-type> 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;
@@ -716,6 +748,44 @@ function type is the type of the function's return value.
 
 \subsection{Parsing C types} \label{sec:clang.c-types.parsing}
 
+\begin{describe}{fun}
+    {parse-c-type @<scanner>
+      @> @<result> @<success-flag> @<consumed-flag>}
+\end{describe}
+
+\begin{describe}{fun}
+    {parse-declarator @<scanner> @<base-type> \&key :kernel :abstractp
+      \nlret @<result> @<success-flag> @<consumed-flag>}
+\end{describe}
+
+\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{gf}{c-type-class @<class-type> @> @<class>}
+     \dhead{gf}{setf (c-type-class @<class-type>) @<class>}}
+\end{describe*}
+
+\begin{describe}{fun}{find-class-type @<name> @> @<class-type-or-nil>}
+\end{describe}
+
+\begin{describe}{fun}
+    {make-class-type @<name> \&optional @<qualifiers> @> @<class-type>}
+\end{describe}
+
+\begin{describe}{fun}
+    {make-class-type @<name> \&optional @<qualifiers> @> @<class-type>}
+\end{describe}
+
+\begin{describe}{fun}{find-sod-class @<name> @> @<class>}
+\end{describe}
+
+\begin{describe}{fun}{record-sod-class @<class>}
+\end{describe}
+
 %%%--------------------------------------------------------------------------
 \section{Generating C code} \label{sec:clang.codegen}
 
@@ -789,8 +859,7 @@ 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                \\
-    {}*sod-tmp-ap*              & sod__tmp_ap                   \\ \hlx*{vh}
+    {}*sod-master-ap*           & sod__master_ap                \\ \hlx*{vh}
   \end{tabular}
   \caption{Well-known temporary names}
   \label{tab:codegen.codegen.well-known-temps}
@@ -835,12 +904,7 @@ Temporary names are represented by objects which implement a simple protocol.
     @|expr|     & @<expr>                  & @<expr>;           \\ \hlx{v}
     @|call|     & @<func> @<args>          & @<func>(@<arg>_1,
                                                      $\ldots$,
-                                                     @<arg>_n)  \\ \hlx{v}
-    @|va-start| & @<ap> @<arg>             & va_start(@<ap>, @<arg>);
-                                                                \\ \hlx{v}
-    @|va-copy|  & @<to> @<from>            & va_copy(@<to>, @<from>);
-                                                                \\ \hlx{v}
-    @|va-end|   & @<ap>                    & va_end(@<ap>);     \\ \hlx{vhv}
+                                                     @<arg>_n)  \\ \hlx{vhv}
     @|block|    & @<decls> @<body>         & \{ @[@<decls>@] @<body> \}
                                                                 \\ \hlx{v}
     @|if|       & @<cond> @<conseq> @<alt> & if (@<cond>) @<conseq>
@@ -876,7 +940,7 @@ Temporary names are represented by objects which implement a simple protocol.
 \begin{describe}{gf}{emit-decl @<codegen> @<decl>}
 \end{describe}
 
-\begin{describe}{gf}{emit-declss @<codegen> @<decls>}
+\begin{describe}{gf}{emit-decls @<codegen> @<decls>}
 \end{describe}
 
 \begin{describe}{gf}{codegen-push @<codegen>}
@@ -913,6 +977,10 @@ Temporary names are represented by objects which implement a simple protocol.
 \begin{describe}{fun}{deliver-expr @<codegen> @<target> @<expr>}
 \end{describe}
 
+\begin{describe}{fun}
+    {deliver-call @<codegen> @<target> @<func> \&rest @<args>}
+\end{describe}
+
 \begin{describe}{fun}{convert-stmts @<codegen> @<target> @<type> @<func>}
 \end{describe}
 
@@ -938,7 +1006,6 @@ Temporary names are represented by objects which implement a simple protocol.
       \nlret @<result> @<success-flag> @<consumed-flag>}
 \end{describe}
 
-\relax
 %%%----- That's all, folks --------------------------------------------------
 
 %%% Local variables: