+++ /dev/null
-%%% -*-latex-*-
-%%%
-%%% Description of the internal class structure and protocol
-%%%
-%%% (c) 2009 Straylight/Edgeware
-%%%
-
-%%%----- Licensing notice ---------------------------------------------------
-%%%
-%%% This file is part of the Simple Object Definition system.
-%%%
-%%% SOD is free software; you can redistribute it and/or modify
-%%% it under the terms of the GNU General Public License as published by
-%%% the Free Software Foundation; either version 2 of the License, or
-%%% (at your option) any later version.
-%%%
-%%% SOD is distributed in the hope that it will be useful,
-%%% but WITHOUT ANY WARRANTY; without even the implied warranty of
-%%% MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
-%%% GNU General Public License for more details.
-%%%
-%%% You should have received a copy of the GNU General Public License
-%%% along with SOD; if not, write to the Free Software Foundation,
-%%% Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
-
-\chapter{Protocol overview} \label{ch:proto}
-
-This chapter provides an overview of the Sod translator's internal object
-model. It describes most of the important classes and generic functions, how
-they are used to build a model of a Sod module and produce output code, and
-how an extension might modify the translator's behaviour.
-
-I assume familiarity with the Common Lisp Object System (CLOS). Familiarity
-with the CLOS Metaobject Protocol isn't necessary but may be instructive.
-
-%%%--------------------------------------------------------------------------
-\section{A tour through the translator}
-
-At the very highest level, the Sod translator works in two phases: it
-\emph{parses} source files into an internal representation, and then it
-\emph{generates} output files from the internal representation.
-
-The function @|read-module| is given a pathname for a file: it opens the
-file, parses the program text, and returns a @|module| instance describing
-the classes and other items found.
-
-At the other end, the main output function is @|output-module|, which is
-given a module, an output stream and a
-
-
-%%%--------------------------------------------------------------------------
-\section{Specification conventions} \label{sec:proto.conventions}
-
-Throughout this specification, the phrase `it is an error' indicates that a
-particular circumstance is erroneous and results in unspecified and possibly
-incorrect behaviour. In particular, the situation need not be immediately
-diagnosed, and the consequences may be far-reaching.
-
-The following conventions apply throughout this specification.
-
-\begin{itemize}
-
-\item If a specification describes an argument as having a particular type or
- syntax, then it is an error to provide an argument not having that
- particular type or syntax.
-
-\item If a specification describes a function then that function might be
- implemented as a generic function; it is an error to attempt to (re)define
- it as a generic function, or to attempt to add methods to it. A function
- specified as being a generic function will certainly be so; if user methods
- are permitted on the generic function then this will be specified.
-
-\item Where a class precedence list is specified, either explicitly or
- implicitly by a class hierarchy, the implementation may include additional
- superclasses not specified here. Such additional superclasses will not
- affect the order of specified classes in the class precedence lists either
- of specified classes themselves or of user-defined subclasses of specified
- classes.
-
-\item Unless otherwise specified, generic functions use the standard method
- combination.
-
-\item The specifications for methods are frequently brief; they should be
- read in conjunction with and in the context of the specification for the
- generic function and specializing classes, if any.
-
-\item An object $o$ is a \emph{direct instance} of a class $c$ if @|(eq
- (class-of $o$) $c$)|; $o$ is an \emph{instance} of $c$ if it is a direct
- instance of any subclass of $c$.
-
-\item If a class is specified as being \emph{abstract} then it is an error to
- construct direct instances of it, e.g., using @|make-instance|.
-
-\item If an object is specified as being \emph{immutable} then it is an error
- to mutate it, e.g., using @|(setf (slot-value \ldots) \ldots)|. Programs
- may rely on immutable objects retaining their state.
-
-\item A value is \emph{fresh} if it is guaranteed to be not @|eql| to any
- previously existing value.
-
-\item Unless otherwise specified, it is an error to change the class of an
- instance of any class described here; and it is an error to change the
- class of an object to a class described here.
-
-\end{itemize}
-
-\subsection{Format of the entries} \label{sec:proto.conventions.format}
-
-Most symbols defined by the protocol have their own entries. An entry begins
-with a header line, showing a synopsis of the symbol on the left, and the
-category (function, class, macro, etc.) on the right.
-
-\begin{describe}{fun}{example-function @<required>
- \&optional @<optional>
- \&rest @<rest>
- \&key :keyword}
- The synopsis for a function, generic function or method describes the
- function's lambda-list using the usual syntax. Note that keyword arguments
- are shown by naming their keywords; in the description, the value passed
- for the keyword argument @|:keyword| is shown as @<keyword>.
-
- For a method, specializers are shown using the usual @|defmethod| syntax,
- e.g.,
- \begin{quote} \sffamily
- some-generic-function ((@<specialized> list) @<unspecialized>)
- \end{quote}
-\end{describe}
-
-\begin{describe}{mac}{example-macro
- ( @{ @<symbol> @! (@<symbol> @<form>) @}^* ) \\ \push
- @[[ @<declaration>^* @! @<documentation-string> @]] \\
- @<body-form>^*}
- The synopsis for a macro describes the acceptable syntax using the
- following notation.
- \begin{itemize}
- \item Literal symbols, e.g., keywords and parenthesis, are shown in
- @|monospace|.
- \item Metasyntactic variables are shown in @<italics>.
- \item Items are grouped together by braces `@{ $\dots$ @}'. The notation
- `@{ $\dots$ @}^*' indicates that the enclosed items may be repeated zero
- or more times; `@{ $\dots$ @}^+' indicates that the enclosed items may be
- repeated one or more times. This notation may be applied to a single
- item without the braces.
- \item Optional items are shown enclosed in brackets `@[ $\dots$ @]'.
- \item Alternatives are separated by vertical bars `@!'; the vertical bar
- has low precedence, so alternatives extend as far as possible between
- bars and up to the enclosing brackets if any.
- \item A sequence of alternatives enclosed in double-brackets `@[[ $\ldots$
- @]]' indicates that the alternatives may occur in any order, but each may
- appear at most once unless marked by a star.
- \end{itemize}
- For example, the notation at the head of this example describes syntax
- for @|let|.
-\end{describe}
-
-\begin{describe}{cls}{example-class (direct-super other-direct-super) \&key
- :initarg}
- The synopsis for a class lists the class's direct superclasses, and the
- acceptable initargs in the form of a lambda-list. The initargs may be
- passed to @|make-instance| when constructing an instance of the class or a
- subclass of it. If instances of the class may be reinitialized, or if
- objects can be changed to be instances of the class, then these initargs
- may also be passed to @|reinitialize-instance| and/or @|change-class| as
- applicable; the class description will state explicitly when these
- operations are allowed.
-\end{describe}
-
-%%%--------------------------------------------------------------------------
-\section{C type representation} \label{sec:proto.c-types}
-
-\subsection{Overview} \label{sec:proto.c-types.over}
-
-The Sod translator represents C types in a fairly simple and direct way.
-However, because it spends a fair amount of its time dealing with C types, it
-provides a number of useful operations and macros.
-
-The class hierarchy is shown in~\xref{fig:proto.c-types}.
-
-\begin{figure} \centering
- \parbox{10pt}{\begin{tabbing}
- @|c-type| \\ \push
- @|qualifiable-c-type| \\ \push
- @|simple-c-type| \\ \push
- @|c-class-type| \- \\
- @|tagged-c-type| \\ \push
- @|c-struct-type| \\
- @|c-union-type| \\
- @|c-enum-type| \- \\
- @|c-pointer-type| \- \\
- @|c-array-type| \\
- @|c-function-type|
- \end{tabbing}}
- \caption{Classes representing C types}
-\label{fig:proto.c-types}
-\end{figure}
-
-C type objects are immutable unless otherwise specified.
-
-\subsubsection{Constructing C type objects}
-There is a constructor function for each non-abstract class of C type object.
-Note, however, that constructor functions need not generate a fresh type
-object if a previously existing type object is suitable. In this case, we
-say that the objects are \emph{interned}. Some constructor functions are
-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|.
-
-The descriptions of each of the various classes include descriptions of the
-initargs which may be passed to @|make-instance| when constructing a new
-instance of the class. However, the constructor functions and S-expression
-syntax are strongly recommended over direct use of @|make-instance|.
-
-\subsubsection{Printing}
-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.
-\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:proto.c-types.root}
-
-\begin{describe}{cls}{c-type ()}
- The class @|c-type| marks the root of the built-in C type hierarchy.
-
- Users may define subclasses of @|c-type|. All non-abstract subclasses must
- have a primary method defined on @|pprint-c-type|; unless instances of the
- subclass are interned, a method on @|c-type-equal-p| is also required.
-
- The class @|c-type| is abstract.
-\end{describe}
-
-\subsection{C type S-expression notation} \label{sec:proto.c-types.sexp}
-
-The S-expression representation of a type is described syntactically as a
-type specifier. Type specifiers fit into two syntactic categories.
-\begin{itemize}
-\item A \emph{symbolic type specifier} consists of a symbol. It has a
- single, fixed meaning: if @<name> is a symbolic type specifier, then each
- use of @<name> in a type specifier evaluates to the same (@|eq|) type
- object, until the @<name> is redefined.
-\item A \emph{type operator} is a symbol; the corresponding specifier is a
- list whose @|car| is the operator. The remaining items in the list are
- arguments to the type operator.
-\end{itemize}
-
-\begin{describe}{mac}{c-type @<type-spec> @to @<type>}
- Evaluates to a C type object, as described by the type specifier
- @<type-spec>.
-\end{describe}
-
-\begin{describe}{mac}{
- defctype @{ @<name> @! (@<name>^*) @} @<type-spec> @to @<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>.
-
- 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.
-\end{describe}
-
-\begin{describe}{mac}{c-type-alias @<original> @<alias>^* @to @<aliases>}
- Defines each @<alias> as being a type operator identical in behaviour to
- @<original>. If @<original> is later redefined then the behaviour of the
- @<alias>es changes too.
-\end{describe}
-
-\begin{describe}{mac}{%
- define-c-type-syntax @<name> @<lambda-list> \\ \push
- @<form>^* \-\\
- @to @<name>}
- Defines the symbol @<name> as a new type operator. When a list of the form
- @|(@<name> @<argument>^*)| is used as a type specifier, the @<argument>s
- are bound to fresh variables according to @<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 type specified by the arguments.
-
- The @<form>s may call @|expand-c-type-spec| in order to recursively expand
- type specifiers among its arguments.
-\end{describe}
-
-\begin{describe}{fun}{expand-c-type-spec @<type-spec> @to @<form>}
- Returns the Lisp form that @|(c-type @<type-spec>)| would expand into.
-\end{describe}
-
-\begin{describe}{gf}{%
- print-c-type @<stream> @<type> \&optional @<colon> @<atsign>}
- Print the C type object @<type> to @<stream> in S-expression form. The
- @<colon> and @<atsign> arguments may be interpreted in any way which seems
- appropriate: they are provided so that @|print-c-type| may be called via
- @|format|'s @|\char`\~/\dots/| command; they are not set when
- @|print-c-type| is called by Sod functions.
-
- There should be a method defined for every C type class; there is no
- default method.
-\end{describe}
-
-\subsection{Comparing C types} \label{sec:proto.c-types.cmp}
-
-It is necessary to compare C types for equality, for example when checking
-argument lists for methods. This is done by @|c-type-equal-p|.
-
-\begin{describe}{gf}{c-type-equal-p @<type>_1 @<type>_2 @to @<boolean>}
- The generic function @|c-type-equal-p| compares two C types @<type>_1 and
- @<type>_2 for equality; it returns true if the two types are equal and
- false if they are not.
-
- Two types are equal if they are structurally similar, where this property
- is defined by methods for each individual class; see the descriptions of
- the classes for the details.
-
- The generic function @|c-type-equal-p| uses the @|and| method combination.
-
- \begin{describe}{meth}{c-type-equal-p @<type>_1 @<type>_2}
- A default primary method for @|c-type-equal-p| is defined. It simply
- returns @|nil|. This way, methods can specialize on both arguments
- without fear that a call will fail because no methods are applicable.
- \end{describe}
- \begin{describe}{ar-meth}{c-type-equal-p @<type>_1 @<type>_2}
- A default around-method for @|c-type-equal-p| is defined. It returns
- true if @<type>_1 and @<type>_2 are @|eql|; otherwise it delegates to the
- primary methods. Since several common kinds of C types are interned,
- this is a common case worth optimizing.
- \end{describe}
-\end{describe}
-
-\subsection{Outputting C types} \label{sec:proto.c-types.output}
-
-\begin{describe}{gf}{pprint-c-type @<type> @<stream> @<kernel>}
- The generic function @|pprint-c-type| pretty-prints to @<stream> a C-syntax
- declaration of an object or function of type @<type>. The result is
- written to @<stream>.
-
- A C declaration has two parts: a sequence of \emph{declaration specifiers}
- and a \emph{declarator}. The declarator syntax involves parentheses and
- operators, in order to reflect the operators applicable to the declared
- variable. For example, the name of a pointer variable is preceded by @`*';
- the name of an array is followed by dimensions enclosed in @`['\dots @`]'.
-
- The @<kernel> argument must be a function designator (though see the
- standard around-method); it is invoked as
- \begin{quote} \codeface
- (funcall @<kernel> @<stream> @<priority> @<spacep>)
- \end{quote}
- It should write to @<stream> -- which may not be the same stream originally
- passed into the generic function -- the `kernel' of the declarator, i.e.,
- the part to which prefix and/or postfix operators are attached to form the
- full declarator.
-
- The methods on @|pprint-c-type| specialized for compound types work by
- recursively calling @|pprint-c-type| on the subtype, passing down a closure
- which prints the necessary additional declarator operators before calling
- the original @<kernel> function. The additional arguments @<priority> and
- @<spacep> support this implementation technique.
-
- The @<priority> argument describes the surrounding operator context. It is
- zero if no type operators are directly attached to the kernel (i.e., there
- are no operators at all, or the kernel is enclosed in parentheses), one if
- a prefix operator is directly attached, or two if a postfix operator is
- directly attached. If the @<kernel> function intends to provide its own
- additional declarator operators, it should check the @<priority> in order
- to determine whether parentheses are necessary. See also the
- @|maybe-in-parens| macro (page~\pageref{mac:maybe-in-parens}).
-
- The @<spacep> 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 @<spacep> 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}).
-
- Every concrete subclass of @|c-type| is expected to provide a primary
- method on this function. There is no default primary method.
-
- \begin{describe}{ar-meth}{pprint-c-type @<type> @<stream> @<kernel>}
- A default around method is defined on @|pprint-c-type| which `canonifies'
- non-function @<kernel> arguments. In particular:
- \begin{itemize}
- \item if @<kernel> is nil, then @|pprint-c-type| is called recursively
- with a @<kernel> function that does nothing; and
- \item if @<kernel> is any other kind of object, then @|pprint-c-type| is
- called recursively with a @<kernel> function that prints the object as
- if by @|princ|, preceded if necessary by space using @|c-type-space|.
- \end{itemize}
- \end{describe}
-\end{describe}
-
-\begin{describe}{fun}{c-type-space @<stream>}
- Writes a space and other pretty-printing instructions to @<stream> in order
- visually to separate a declarator from the preceding declaration
- specifiers. The precise details are subject to change.
-\end{describe}
-
-\begin{describe}{mac}{%
- maybe-in-parens (@<stream-var> @<guard-form>) \\ \push
- @<form>^*}
- The @<guard-form> is evaluated, and then the @<form>s are evaluated in
- sequence within a pretty-printer logical block writing to the stream named
- by the symbol @<stream-var>. If the @<guard-form> evaluates to nil, then
- the logical block has empty prefix and suffix strings; if it evaluates to a
- non-nil value, then the logical block has prefix and suffix @`(' and @`)'
- respectively.
-
- Note that this may cause @<stream> to be bound to a different stream object
- within the @<form>s.
-\end{describe}
-
-\subsection{Type qualifiers and qualifiable types}
-\label{sec:proto.ctypes.qual}
-
-\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|,
- @|restrict| and @|volatile|.
-
- The @<qualifiers> are a list of keyword symbols @|:const|, @|:restrict| and
- @|:volatile|. There is no built-in limitation to these particular
- 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.
-
- The class @|qualifiable-c-type| is abstract.
-\end{describe}
-
-\begin{describe}{gf}{c-type-qualifiers @<type> @to @<list>}
- Returns the qualifiers of the @|qualifiable-c-type| instance @<type> as an
- immutable list.
-\end{describe}
-
-\begin{describe}{fun}{qualify-type @<type> @<qualifiers>}
- The argument @<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
- bears the given @<qualifiers>.
-
- The @<type> is not modified. If @<type> is interned, then the returned
- type will be interned.
-\end{describe}
-
-\begin{describe}{fun}{format-qualifiers @<qualifiers>}
- Returns a string containing the qualifiers listed in @<qualifiers> in C
- syntax, with a space after each. In particular, if @<qualifiers> is
- non-null then the final character of the returned string will be a space.
-\end{describe}
-
-\subsection{Leaf types} \label{sec:proto.c-types.leaf}
-
-A \emph{leaf type} is a type which is not defined in terms of another type.
-In Sod, the leaf types are
-\begin{itemize}
-\item \emph{simple types}, including builtin types like @|int| and @|char|,
- as well as type names introduced by @|typename|, because Sod isn't
- interested in what the type name means, merely that it names a type; and
-\item \emph{tagged types}, i.e., enum, struct and union types which are named
- by a keyword identifying the kind of type, and a \emph{tag}.
-\end{itemize}
-
-\begin{describe}{cls}{simple-c-type (qualifiable-c-type)
- \&key :qualifiers :name}
- The class of `simple types'; an instance denotes the type @<qualifiers>
- @<name>.
-
- A simple type object maintains a \emph{name}, which is a string whose
- contents are the C name for the type. The initarg @|:name| may be used to
- provide this name when calling @|make-instance|.
-
- Two simple type objects are equal if and only if they have @|string=| names
- and matching qualifiers.
-
- A number of symbolic type specifiers for builtin types are predefined as
- shown in \xref{tab:proto.c-types.simple}. These are all defined as if by
- @|define-simple-c-type|, so can be used to construct qualified types.
-\end{describe}
-
-\begin{table}
- \begin{tabular}[C]{|l|l|} \hlx{hv}
- \textbf{C type} & \textbf{Specifiers} \\ \hlx{vhv}
- @|void| & @|void| \\ \hlx{vhv}
- @|char| & @|char| \\ \hlx{v}
- @|unsigned char| & @|unsigned-char|, @|uchar| \\ \hlx{v}
- @|signed char| & @|signed-char|, @|schar| \\ \hlx{vhv}
- @|short| & @|short|, @|signed-short|, @|short-int|,
- @|signed-short-int| @|sshort| \\ \hlx{v}
- @|unsigned short| & @|unsigned-short|, @|unsigned-short-int|,
- @|ushort| \\ \hlx{vhv}
- @|int| & @|int|, @|signed|, @|signed-int|,
- @|sint| \\ \hlx{v}
- @|unsigned int| & @|unsigned|, @|unsigned-int|, @|uint| \\ \hlx{vhv}
- @|long| & @|long|, @|signed-long|, @|long-int|,
- @|signed-long-int|, @|slong| \\ \hlx{v}
- @|unsigned long| & @|unsigned-long|, @|unsigned-long-int|,
- @|ulong| \\ \hlx{vhv}
- @|long long| & @|long-long|, @|signed-long-long|,
- @|long-long-int|, \\
- & \qquad @|signed-long-long-int|,
- @|llong|, @|sllong| \\ \hlx{v}
- @|unsigned long long|
- & @|unsigned-long-long|, @|unsigned-long-long-int|,
- @|ullong| \\ \hlx{vhv}
- @|float| & @|float| \\ \hlx{v}
- @|double| & @|double| \\ \hlx{vhv}
- @|va_list| & @|va-list| \\ \hlx{v}
- @|size_t| & @|size-t| \\ \hlx{v}
- @|ptrdiff_t| & @|ptrdiff-t| \\ \hlx{vh}
- \end{tabular}
- \caption{Builtin symbolic type specifiers for simple C types}
- \label{tab:proto.c-types.simple}
-\end{table}
-
-\begin{describe}{fun}{make-simple-type @<name> \&optional @<qualifiers>}
- Return the (unique interned) simple C type object for the C type whose name
- is @<name> (a string) and which has the given @<qualifiers> (a list of
- keywords).
-\end{describe}
-
-\begin{describe}{gf}{c-type-name @<type>}
- Returns the name of a @|simple-c-type| instance @<type> as an immutable
- string.
-\end{describe}
-
-\begin{describe}{mac}{%
- define-simple-c-type @{ @<name> @! (@<name>^*) @} @<string>}
- 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).
-\end{describe}
-
-\begin{describe}{cls}{tagged-c-type (qualifiable-c-type)
- \&key :qualifiers :tag}
- Provides common behaviour for C tagged types. A @<tag> is a string
- containing a C identifier.
-
- Two tagged types are equal if and only if they have the same class, their
- @<tag>s are @|string=|, and they have matching qualifiers. (User-defined
- subclasses may have additional methods on @|c-type-equal-p| which impose
- further restrictions.)
-\end{describe}
-\begin{boxy}[Bug]
- Sod maintains distinct namespaces for the three kinds of tagged types. In
- C, there is only one namespace for tags which is shared between enums,
- structs and unions.
-\end{boxy}
-
-\begin{describe}{gf}{c-tagged-type-kind @<type>}
- Returns a symbol classifying the tagged @<type>: one of @|enum|, @|struct|
- or @|union|. User-defined subclasses of @|tagged-c-type| should return
- their own classification symbols. It is intended that @|(string-downcase
- (c-tagged-type-kind @<type>))| be valid C syntax.\footnote{%
- Alas, C doesn't provide a syntactic category for these keywords;
- \Cplusplus\ calls them a @<class-key>.} %
-\end{describe}
-
-\begin{describe}{cls}{c-enum-type (tagged-c-type) \&key :qualifiers :tag}
- Represents a C enumerated type. An instance denotes the C type @|enum|
- @<tag>. See the direct superclass @|tagged-c-type| for details.
-
- The type specifier @|(enum @<tag> @<qualifier>^*)| returns the (unique
- interned) enumerated type with the given @<tag> and @<qualifier>s (all
- evaluated).
-\end{describe}
-\begin{describe}{fun}{make-enum-type @<tag> \&optional @<qualifiers>}
- Return the (unique interned) C type object for the enumerated C type whose
- tag is @<tag> (a string) and which has the given @<qualifiers> (a list of
- keywords).
-\end{describe}
-
-\begin{describe}{cls}{c-struct-type (tagged-c-type) \&key :qualifiers :tag}
- Represents a C structured type. An instance denotes the C type @|struct|
- @<tag>. See the direct superclass @|tagged-c-type| for details.
-
- The type specifier @|(struct @<tag> @<qualifier>^*)| returns the (unique
- interned) structured type with the given @<tag> and @<qualifier>s (all
- evaluated).
-\end{describe}
-\begin{describe}{fun}{make-struct-type @<tag> \&optional @<qualifiers>}
- Return the (unique interned) C type object for the structured C type whose
- tag is @<tag> (a string) and which has the given @<qualifiers> (a list of
- keywords).
-\end{describe}
-
-\begin{describe}{cls}{c-union-type (tagged-c-type) \&key :qualifiers :tag}
- Represents a C union type. An instance denotes the C type @|union|
- @<tag>. See the direct superclass @|tagged-c-type|
- for details.
-
- The type specifier @|(union @<tag> @<qualifier>^*)| returns the (unique
- interned) union type with the given @<tag> and @<qualifier>s (all
- evaluated).
-\end{describe}
-\begin{describe}{fun}{make-union-type @<tag> \&optional @<qualifiers>}
- Return the (unique interned) C type object for the union C type whose tag
- is @<tag> (a string) and which has the given @<qualifiers> (a list of
- keywords).
-\end{describe}
-
-\subsection{Pointers and arrays} \label{sec:proto.c-types.ptr-array}
-
-Pointers and arrays are \emph{compound types}: they're defined in terms of
-existing types. A pointer describes the type of objects it points to; an
-array describes the type of array element.
-\begin{describe}{gf}{c-type-subtype @<type>}
- Returns the underlying type of a compound type @<type>. Precisely what
- this means depends on the class of @<type>.
-\end{describe}
-
-\begin{describe}{cls}{c-pointer-type (qualifiable-c-type)
- \&key :qualifiers :subtype}
- Represents a C pointer type. An instance denotes the C type @<subtype>
- @|*|@<qualifiers>.
-
- The @<subtype> 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 @|(* @<type-spec> @<qualifier>^*)| returns a type
- qualified pointer-to-@<subtype>, where @<subtype> is the type specified by
- @<type-spec> and the @<qualifier>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 of pointer to
- characters; the symbol @|const-string| is a type specifier for the type
- pointer to constant characters.
-\end{describe}
-\begin{describe}{fun}{make-pointer-type @<subtype> \&optional @<qualifiers>}
- Return an object describing the type of qualified pointers to @<subtype>.
- If @<subtype> is interned, then the returned pointer type object is
- interned also.
-\end{describe}
-
-\begin{describe}{cls}{c-array-type (c-type) \&key :subtype :dimensions}
- Represents a multidimensional C array type. The @<dimensions> are a list
- of dimension specifiers $d_0$, $d_1$, \ldots, $d_{n-1}$; an instance then
- denotes the C type @<subtype> @|[$d_0$][$d_1$]$\ldots$[$d_{n-1}$]|. An
- individual dimension specifier is either a string containing a C integral
- constant expression, or nil which is equivalent to an empty string. Only
- the first (outermost) dimension $d_0$ should be empty.
-
- C doesn't actually have multidimensional arrays as a primitive notion;
- rather, it permits an array (with known extent) to be the element type of
- an array, which achieves an equivalent effect. C arrays are stored in
- row-major order: i.e., if we write down the indices of the elements of an
- array in order of ascending address, the rightmost index varies fastest;
- hence, the type constructed is more accurately an array of $d_0$ arrays of
- $d_1$ of \ldots\ arrays of $d_{n-1}$ elements of type @<subtype>. We shall
- continue to abuse terminology and refer to multidimensional arrays.
-
- The type specifier @|([] @<type-spec> @<dimension>^*)| constructs a
- multidimensional array with the given @<dimension>s whose elements have the
- type specified by @<type-spec>. 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}
-\begin{describe}{fun}{make-array-type @<subtype> @<dimensions>}
- Return an object describing the type of arrays with given @<dimensions> and
- with element type @<subtype> (an instance of @|c-type|). The @<dimensions>
- argument is a list whose elements are strings or nil; see the description
- of the class @|c-array-type| above for details.
-\end{describe}
-\begin{describe}{gf}{c-array-dimensions @<type>}
- Returns the dimensions of @<type>, an array type, as an immutable list.
-\end{describe}
-
-\subsection{Function types} \label{sec:proto.c-types.fun}
-
-\begin{describe}{cls}{c-function-type (c-type) \&key :subtype :arguments}
- Represents C function types. An instance denotes the C type of a C
- function which
-\end{describe}
-
-%%%----- That's all, folks --------------------------------------------------
-
-%%% Local variables:
-%%% mode: LaTeX
-%%% TeX-master: "sod.tex"
-%%% TeX-PDF-mode: t
-%%% End:
~mdw / sod / blobdiff