not specified, clients may still not rely on receiving fresh objects.
A convenient S-expression notation is provided by the
-\descref{c-type}[macro]{mac}. Use of this macro is merely an abbreviation
+\descref{mac}{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 \descref{defctype}{mac},
-\descref{c-type-alias}{mac} and \descref{define-c-type-syntax}{mac}.
+can be extended in order to support new classes: see \descref{mac}{defctype},
+\descref{mac}{c-type-alias} and \descref{mac}{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
There are two protocols for printing C types. Unfortunately they have
similar names.
\begin{itemize}
-\item The \descref{print-c-type}[function]{gf} prints a C type value using
+\item The \descref{gf}{print-c-type}[function] prints a C type value using
the S-expression notation. It is mainly useful for diagnostic purposes.
-\item The \descref{pprint-c-type}[function]{gf} prints a C type as a
+\item The \descref{gf}{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.
+\begin{describe}{fun}{c-name-case @<name> @> @<string>}
+\end{describe}
+
\subsection{The C type root class} \label{sec:clang.c-types.root}
\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}{gf} is
+ If @<type-spec> is a list, then \descref{gf}{expand-c-type-form} is
invoked.
\end{describe}
The generic function @|c-type-equal-p| uses the @|and| method combination.
- \begin{describe}{meth}{c-type-equal-p @<c-type>_1 @<c-type>_2}
+ \begin{describe}{meth}{t,t}{c-type-equal-p @<c-type>_1 @<c-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 @<c-type>_1 @<c-type>_2}
+ \begin{describe}{ar-meth}{}{c-type-equal-p @<c-type>_1 @<c-type>_2}
A default around-method for @|c-type-equal-p| is defined. It returns
true if @<c-type>_1 and @<c-type>_2 are @|eql|; otherwise it delegates to
the primary methods. Since several common kinds of C types are interned,
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
- \descref{maybe-in-parens}[macro]{mac}.
+ \descref{mac}{maybe-in-parens}[macro].
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 \descref{c-type-space}[function]{fun}.
+ trailing space. See also the \descref{fun}{c-type-space}[function].
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 @<c-type> @<stream> @<kernel>}
+ \begin{describe}{ar-meth}{}{pprint-c-type @<c-type> @<stream> @<kernel>}
A default around method is defined on @|pprint-c-type| which `canonifies'
non-function @<kernel> arguments. In particular:
\begin{itemize}
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}.
+methods to \descref{gf}{c-qualifier-keyword}.
\begin{describe}{cls}{qualifiable-c-type (c-type) \&key :qualifiers}
The class @|qualifiable-c-type| describes C types which can bear
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
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>}
+ \begin{describe}{meth}{keyword}
+ {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}
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}
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}
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.
evaluated).
Each of the @<string>s is associated with the resulting type for retrieval
- by \descref{find-simple-c-type}{fun}. Furthermore, a variable
+ by \descref{fun}{find-simple-c-type}. Furthermore, a variable
@|c-type-@<name>| is defined, for the first @<name> only, and initialized
with the newly constructed C type object.
\begin{describe}{fun}
{find-simple-c-type @<string> @> @{ @<simple-c-type> @! @|nil| @}}
If @<string> is the name of a simple C type, as established by the
- \descref{define-simple-c-type}[macro]{mac}, then return the corresponding
+ \descref{mac}{define-simple-c-type}[macro], then return the corresponding
@|simple-c-type| object; otherwise, return @|nil|.
\end{describe}
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|
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
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
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
+ keyword-argument list (e.g., in a \descref{cls}{c-keyword-function-type}
+ [object]), 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}
including file from defining such names as macros. This generic function
is used to convert names into a safe form.
- \begin{describe}{meth}{commentify-argument-name (@<name> null) @> nil}
+ \begin{describe}{meth}{null}
+ {commentify-argument-name (@<name> null) @> nil}
Returns nil: if the argument name is already omitted, it's safe for use
in a header file.
\end{describe}
- \begin{describe}{meth}{commentify-argument-name (@<name> t) @> @<string>}
+ \begin{describe}{meth}{t}
+ {commentify-argument-name (@<name> t) @> @<string>}
Returns the print form of @<name> wrapped in a C comment, as
@`/*@<name>*/'.
\end{describe}
arguments; or
\item a possibly-improper list tail, beginning with an atom either as a
list item or as the final list cdr, indicating that the entire list tail
- is Lisp expression which is to be evaluated to compute the remaining
+ is a Lisp expression which is to be evaluated to compute the remaining
arguments.
\end{itemize}
A tail expression may return a list of @|argument| objects, optionally
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
these circumstances obtains, then the specifier constructs an ordinary
function type.)
- See the description of \descref{c-function-type}{cls} for how a trailing
+ See the description of \descref{cls}{c-function-type} for how a trailing
@<form> is handled.
The list of @<arg-name>s and @<arg-type>s describes the positional
accepting the @<arguments>.
If the @<arguments> list contains a @|:keys| marker, then a
- \descref{c-keyword-function-type}[object]{cls} is returned: those arguments
+ \descref{cls}{c-keyword-function-type}[object] 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}{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}
\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
+ the \descref{var}{*sod-ap*}[variable]. The new list is returned; the
original list is not modified, but may share structure with the new list.
\end{describe}
The @<lists> parameter is a list consisting of a number of
@|(@<report-function> . @<args>)| pairs: in each pair, @<report-function>
is either nil or a function designator, and @<args> is a list of
- \descref{argument}{cls} objects.
+ \descref{cls}{argument} objects.
The resulting list contains exactly one argument for each distinct argument
name appearing in the input @<lists>; this argument will contain the
arguments and is expected to return two values:
\begin{itemize}
\item a file location @<floc> or other object acceptable to
- \descref{file-location}{gf}, to be used as the location of the main
+ \descref{gf}{file-location}, to be used as the location of the main
error; and
\item an object @<what>, whose printed representation should be a noun
phrase describing the object for which the argument lists are being
for the @<args> lists containing the conflicting argument objects are
called, in an arbitrary order, with a single argument which is the
offending @|argument| object; the function is expected to issue information
- messages (see \descref{info}{fun}) to give more detail for diagnosing the
+ messages (see \descref{fun}{info}) to give more detail for diagnosing the
conflict. If a @<report-function> is nil, then nothing happens; this is
considered poor practice.
\end{describe}
arguments, if any, will be printed by @<print-args>.
The @<print-kernel> function is a standard kernel-printing function
- following the \descref{pprint-c-type}[protocol]{gf}.
+ following the \descref{gf}{pprint-c-type}[protocol].
The @<print-args> function is given a single argument, which is the
@<stream> to print on. It should not print the surrounding parentheses.
\begin{describe}{fun}{pprint-argument-list @<args> @<stream> @> @<flag>}
Print an argument list to @<stream>.
- The @<args> is a list of \descref{argument}[objects]{cls}, optionally
+ The @<args> is a list of \descref{cls}{argument}[objects], optionally
containing an @|:ellipsis| marker. The function returns true if any
arguments were actually printed.
\end{describe}
{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*}
{\dhead{gf}{var-in-use-p @<var> @> @<generalized-boolean>}
- \dhead[setf var-in-use-p]
- {gf}{setf (var-in-use-p @<var>) @<generalized-boolean>}}
+ \dhead{gf}{setf (var-in-use-p @<var>) @<generalized-boolean>}}
\end{describe*}
\subsubsection{Temporary name objects}
subclasses, but is also usable on its own.
\end{describe}
-\begin{describe}{meth}
+\begin{describe}{gf}{temp-tag @<name> @> @<tag>}
+\end{describe}
+
+\begin{describe}{meth}{temporary-name}
{commentify-argument-name (@<name> temporary-name) @> nil}
\end{describe}
\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 \\
\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}
\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>
~mdw / sod / blobdiff