From fcb6c0fb72f7e2211322cfc303ee403bdf3ddd7d Mon Sep 17 00:00:00 2001 From: Mark Wooding Date: Sun, 30 Aug 2015 10:58:38 +0100 Subject: [PATCH] doc/: Actually write documentation. Mostly this is importing synopses which need to have stuff written about them and around them. But it's all progress, right? --- doc/clang.tex | 354 +++++++++++++++++++++++++++++++++++++++++---- doc/misc.tex | 438 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/parsing.tex | 360 ++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 1091 insertions(+), 61 deletions(-) create mode 100644 doc/misc.tex diff --git a/doc/clang.tex b/doc/clang.tex index 8a21449..bd1053f 100644 --- a/doc/clang.tex +++ b/doc/clang.tex @@ -347,35 +347,35 @@ In Sod, the leaf types are \end{describe} \begin{table} - \begin{tabular}[C]{|l|l|} \hlx{hv} - \textbf{C type} & \textbf{Specifiers} \\ \hlx{vhv} - @|void| & @|void| \\ \hlx{vhv} + \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{v} - @|signed char| & @|signed-char|, @|schar| \\ \hlx{vhv} + @|unsigned char| & @|unsigned-char|, @|uchar| \\ \hlx{} + @|signed char| & @|signed-char|, @|schar| \\ \hlx{v} @|short| & @|short|, @|signed-short|, @|short-int|, - @|signed-short-int| @|sshort| \\ \hlx{v} + @|signed-short-int| @|sshort| \\ \hlx{} @|unsigned short| & @|unsigned-short|, @|unsigned-short-int|, - @|ushort| \\ \hlx{vhv} + @|ushort| \\ \hlx{v} @|int| & @|int|, @|signed|, @|signed-int|, - @|sint| \\ \hlx{v} - @|unsigned int| & @|unsigned|, @|unsigned-int|, @|uint| \\ \hlx{vhv} + @|sint| \\ \hlx{} + @|unsigned int| & @|unsigned|, @|unsigned-int|, @|uint| \\ \hlx{v} @|long| & @|long|, @|signed-long|, @|long-int|, - @|signed-long-int|, @|slong| \\ \hlx{v} + @|signed-long-int|, @|slong| \\ \hlx{} @|unsigned long| & @|unsigned-long|, @|unsigned-long-int|, - @|ulong| \\ \hlx{vhv} + @|ulong| \\ \hlx{v} @|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} + @|ullong| \\ \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} + @|ptrdiff_t| & @|ptrdiff-t| \\ \hlx*{vh} \end{tabular} \caption{Builtin symbolic type specifiers for simple C types} \label{tab:codegen.c-types.simple} @@ -513,7 +513,7 @@ to. 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 + The symbol @|string| is a type specifier for the type pointer to characters; the symbol @|const-string| is a type specifier for the type pointer to constant characters. \end{describe} @@ -521,15 +521,15 @@ to. \begin{describe}{fun} {make-pointer-type @ \&optional @ @> @} - Return an object describing the type of qualified pointers to @. + Return an object describing the type qualified pointer to @. If @ is interned, then the returned pointer type object is interned also. \end{describe} \subsection{Array types} \label{sec:clang.c-types.array} -Arrays implement the compound-type protocol. The subtype of an array is the -array element type. +Arrays implement the compound-type protocol. The subtype of an array type is +the array element type. \begin{describe}{cls}{c-array-type (c-type) \&key :subtype :dimensions} Represents a multidimensional C array type. The @ are a list @@ -569,44 +569,144 @@ array element type. \subsection{Function types} \label{sec:clang.c-types.fun} +Function types implement the compound-type protocol. The subtype of a +function type is the type of the function's return value. + \begin{describe}{cls}{argument} + Represents an ordinary function argument. \end{describe} \begin{describe}{fun}{argumentp @ @> @} + Decide whether @ is an @ object: if so, return non-nil; if + not return nil. \end{describe} \begin{describe}{fun}{make-argument @ @ @> @} + Construct and a return a new @ object. The argument has type + @, which must be a @|c-type| object, and is named @. + + The @ may be nil to indicate that the argument has no name: in this + case the argument will be formatted as an abstract declarator, which is not + suitable for function definitions. If @ is not nil, then the + @'s print representation, with @|*print-escape*| nil, is used as the + argument name. \end{describe} -\begin{describe}{fun}{argument-name @ @> @} +\begin{describe}{fun}{argument-name @ @> @} + Return the name of the @, as it was supplied to @|make-argument|. \end{describe} \begin{describe}{fun}{argument-type @ @> @} + Return the type of the @, as it was supplied to @|make-argument|. \end{describe} -\begin{describe}{fun} +\begin{describe}{gf} {commentify-argument-name @ @> @} -\end{describe} + Convert the argument name @ so that it's suitable to declare the + function in a header file. -\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 FIXME + Robust header files shouldn't include literal argument names in + declarations of functions or function types, since this restricts the + 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 (@ 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 (@ t) @> @} + Returns the print form of @ wrapped in a C comment, as + @`/*@*/'. + \end{describe} \end{describe} \begin{describe}{fun} - {c-function-arguments @ @> @} + {commentify-argument-names @ @> @} + Convert the @ list so that it's suitable for use in a header + file. + + The @ list should be a list whose items are @|argument| objects + or the keyword @|:ellipsis|. The return value is a list constructed as + follows. For each @|argument| object in the input list, there is a + corresponding @|argument| object in the returned list, with the same type, + and whose name is the result of @|commentify-argument-name| applied to the + input argument name; an @|:ellipsis| in the input list is passed through + unchanged. \end{describe} -\begin{describe}{fun} - {make-c-type @ @ @> @} +\begin{describe}{cls}{c-function-type (c-type) \&key :subtype :arguments} + Represents C function types. An instance denotes the type of a C + function which accepts the @ and returns @. + + The @ are a possibly empty list. All but the last element of + the list must be @|argument| objects; the final element may instead be the + keyword @|:ellipsis|, which denotes a variable argument list. + + An @ list consisting of a single argument with type @|void| is + converted into an empty list. On output as C code, an empty argument list + is written as @|void|. It is not possible to represent a pre-ANSI C + function without prototypes. + + Two function types are considered to be the same if their return types are + the same, and their argument lists consist of arguments with the same type, + in the same order, and either both or neither argument list ends with + @|:ellipsis|; argument names are not compared. + + The type specifier @|(fun @ @{ (@ @) @}^* + @[:ellipsis @! . @
@])| constructs a function type. The function has + the subtype @. 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 @/@ 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; + \item the keyword @|:ellipsis|, as the final item in the type-specifier + list, indicating a variable argument list may follow the explicit + 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 + arguments. + \end{itemize} + A tail expression may return a list of @|argument| objects, optionally + followed by an @|:ellipsis|. + + For example, + \begin{prog} + (c-type (fun \=(lisp (c-type-subtype other-func)) \+ \\ + ("first" int) . (c-function-arguments other-func)) + \end{prog} + evaluates to a function type like @|other-func|, only with an additional + argument of type @|int| added to the front of its argument list. This + could also have been written + \begin{prog} + (let (\=(args (c-function-arguments other-func)) \+ \\ + (ret (c-type-subtype other-func))) \- \\ \ind + (c-type (fun \=(lisp ret) ("first" int) . args) + \end{prog} \end{describe} \begin{describe}{fun} - {commentify-argument-names @ @> @} + {make-function-type @ @ @> @} + Construct and return a new function type, returning @ and + accepting the @. +\end{describe} + +\begin{describe}{gf} + {c-function-arguments @ @> @} + Return the arguments list of the @. \end{describe} \begin{describe}{fun} - {commentify-function-type @ @> @} + {commentify-function-type @ @> @} + Return a commentified version of the @. + + The returned type has the same subtype as the given type, and the argument + list of the returned type is the result of applying + @|commentify-argument-names| to the argument list of the given type. \end{describe} \subsection{Parsing C types} \label{sec:clang.c-types.parsing} @@ -614,6 +714,200 @@ array element type. %%%-------------------------------------------------------------------------- \section{Generating C code} \label{sec:clang.codegen} +This section deals with Sod's facilities for constructing and manipulating C +expressions, declarations, instructions and definitions. + +\subsection{Temporary names} \label{sec:clang.codegen.temporaries} + +Many C-level objects, especially ones with external linkage or inclusion in a +header file, are assigned names which are simple strings, perhaps fixed ones, +perhaps constructed. Other objects don't need meaningful names, and +suitably unique constructed names would be tedious and most likely rather +opaque. Therefore Sod has an ability to construct \emph{temporary names}. + +These aren't temporary in the sense that they name C objects which have +limited lifetimes at runtime. Rather, the idea is that the names be +significant only to small pieces of Lisp code, which will soon forget about +them. + +\subsubsection{The temporary name protocol} +Temporary names are represented by objects which implement a simple protocol. + +\begin{describe}{gf}{format-temporary-name @ @} +\end{describe} + +\begin{describe*} + {\dhead{gf}{var-in-use-p @ @> @} + \dhead[setf var-in-use-p] + {gf}{setf (var-in-use-p @) @}} +\end{describe*} + +\subsubsection{Temporary name objects} + +\begin{describe}{cls}{temporary-name () \&key :tag} + A temporary name object. This is the root of a small collection of + subclasses, but is also usable on its own. +\end{describe} + +\begin{describe}{meth} + {commentify-argument-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 & @ \\ + temporary-argument & sod__a@ \\ + temporary-function & sod__f@ \\ + temporary-variable & sod__v@ \\ \hlx*{vh} + \end{tabular} + \caption{Temporary name formats} + \label{tab:codegen.codegen.temps-format} +\end{table} + +\begin{describe}{cls}{temporary-argument (temporary-name) \&key :tag} +\end{describe} + +\begin{describe}{cls}{temporary-function (temporary-name) \&key :tag} +\end{describe} + +\begin{describe}{fun}{temporary-function @> @} +\end{describe} + +\begin{describe}{cls} + {temporary-variable (temporary-name) \&key :tag :in-use-p} +\end{describe} + +\subsubsection{Well-known `temporary' names} + +\begin{table} + \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} + \end{tabular} + \caption{Well-known temporary names} + \label{tab:codegen.codegen.well-known-temps} +\end{table} + +\subsection{Instructions} \label{sec:clang.codegen.insts} + +\begin{describe}{cls}{inst () \&key} +\end{describe} + +\begin{describe}{gf}{inst-metric @} +\end{describe} + +\begin{describe}{mac} + {definst @ (@ \&key @) (@^*) + @^*} +\end{describe} + +\begin{describe}{mac} + {format-compound-statement (@ @ \&optional @) + @^*} +\end{describe} + +\begin{table} + \begin{tabular}[C]{ll>{\codeface}l} \hlx*{hv} + \thd{Class name} & + \thd{Arguments} & + \thd{Output format} \\ \hlx{vhv} + @|var| & @ @ @ & @ @ @[= @@]; + \\ \hlx{v} + @|set| & @ @ & @ = @; \\ \hlx{v} + @|update| & @ @ @ & @ @= @; + \\ \hlx{v} + @|return| & @ & return @[@@]; + \\ \hlx{v} + @|break| & --- & break; \\ \hlx{v} + @|continue| & --- & continue; \\ \hlx{v} + @|expr| & @ & @; \\ \hlx{v} + @|call| & @ @ & @(@_1, + $\ldots$, + @_n) \\ \hlx{v} + @|va-start| & @ @ & va_start(@, @); + \\ \hlx{v} + @|va-copy| & @ @ & va_copy(@, @); + \\ \hlx{v} + @|va-end| & @ & va_end(@); \\ \hlx{vhv} + @|block| & @ @ & \{ @[@@] @ \} + \\ \hlx{v} + @|if| & @ @ @ & if (@) @ + @[else @@] \\ \hlx{v} + @|while| & @ @ & while (@) @ + \\ \hlx{v} + @|do-while| & @ @ & do @ while (@); + \\ \hlx{v} + @|function| & @ @ @ & + @_0 @(@_1 @_1, $\ldots$, + @_n @_n @[, \dots@]) + @ \\ \hlx*{vh} + \end{tabular} + \caption{Instruction classes} + \label{tab:codegen.codegen.insts} +\end{table} + +\subsection{Code generation} \label{sec:clang.codegen.codegen} + +\begin{describe}{gf}{codegen-functions @ @> @} +\end{describe} + +\begin{describe}{gf} + {ensure-var @ @ @ \&optional @} +\end{describe} + +\begin{describe}{gf}{emit-inst @ @} +\end{describe} + +\begin{describe}{gf}{emit-insts @ @} +\end{describe} + +\begin{describe}{gf}{emit-decl @ @} +\end{describe} + +\begin{describe}{gf}{emit-declss @ @} +\end{describe} + +\begin{describe}{gf}{codegen-push @} +\end{describe} + +\begin{describe}{gf}{codegen-pop @ @> @ @} +\end{describe} + +\begin{describe}{gf}{codegen-pop-block @ @> @} +\end{describe} + +\begin{describe}{gf} + {codegen-pop-function @ @ @ @> @} +\end{describe} + +\begin{describe}{gf}{codegen-add-function @ @} +\end{describe} + +\begin{describe}{fun} + {codegen-build-function @ @ @ @ @ + @> @} +\end{describe} + +\begin{describe}{gf}{temporary-var @ @ @> @} +\end{describe} + +\begin{describe}{mac} + {with-temporary-var (@ @ @) @^* + @> @^*} +\end{describe} + +\begin{describe}{fun}{deliver-expr @ @ @} +\end{describe} + +\begin{describe}{fun}{convert-stmts @ @ @ @} +\end{describe} + +\begin{describe}{cls}{codegen () \&key :vars :insts (:temp-index 0)} +\end{describe} + %%%----- That's all, folks -------------------------------------------------- %%% Local variables: diff --git a/doc/misc.tex b/doc/misc.tex new file mode 100644 index 0000000..a7ac722 --- /dev/null +++ b/doc/misc.tex @@ -0,0 +1,438 @@ +%%% -*-latex-*- +%%% +%%% Miscellaneous functionality +%%% +%%% (c) 2015 Straylight/Edgeware +%%% + +%%%----- Licensing notice --------------------------------------------------- +%%% +%%% This file is part of the Sensble 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 +%%% 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{Miscellaneous functionality} \label{ch:misc} + +%%%-------------------------------------------------------------------------- +\section{Utilities} \label{sec:misc.utilities} + +These symbols are defined in the @|sod-utilities| package. + +\begin{describe}{mac} + {with-gensyms (@{ @ @! (@ @[@@]) @}^*) \\ \ind + @^*} +\end{describe} + +\begin{describe}{mac} + {once-only (@[[ :environment @ @]] + @{ @ @! (@ @[@@]) @}^*) \\ \ind + @^*} +\end{describe} + +\begin{describe}{mac} + {parse-body @ @> @ @ @} +\end{describe} + +\begin{describe}{sym}{it} +\end{describe} + +\begin{describe}{mac}{aif @ @ @[@@]} +\end{describe} + +\begin{describe}{mac}{awhen @ @^*} +\end{describe} + +\begin{describe}{mac}{acond @{ (@ @^*) @}^*} +\end{describe} + +\begin{describe*} + {\dhead{mac} + {acase @ @{ (@{ @ @! (@^*) @} @^*) @}^*} + \dhead{mac} + {aecase @ @{ (@{ @ @! (@^*) @} @^*) @}^*} + \dhead{mac}{atypecase @ @{ (@ @^*) @}^*} + \dhead{mac}{aetypecase @ @{ (@ @^*) @}^*}} +\end{describe*} + +\begin{describe}{mac}{asetf @{ @ @ @}^*} +\end{describe} + +\begin{describe}{gf}{instance-initargs @} +\end{describe} + +\begin{describe*} + {\dhead{fun}{copy-instance @ \&rest @} + \dhead{gf}{copy-instance-using-class @ @ + \&rest @}} +\end{describe*} + +\begin{describe*} + {\dhead{gf}{generic-function-methods @ @> @} + \dhead{gf}{method-specializers @ @> @} + \dhead{cls}{eql-specializer} + \dhead{gf}{eql-specializer-object @ @> @}} +\end{describe*} + +\begin{describe}{fun}{make-list-builder \&optional @ @> @} +\end{describe} + +\begin{describe}{fun}{lbuild-add @ @ @> @} +\end{describe} + +\begin{describe}{fun}{lbuild-add-list @ @ @> @} +\end{describe} + +\begin{describe}{fun}{lbuild-list @ @> @} +\end{describe} + +\begin{describe}{fun} + {mappend @ @ \&rest @ @> @} +\end{describe} + +\begin{describe}{cls}{inconsistent-merge-error (error) \&key :candidates} +\end{describe} + +\begin{describe}{gf}{merge-error-candidates @ @> @} +\end{describe} + +\begin{describe}{fun} + {merge-lists @ \&key :pick (:test \#'eql) @> @} +\end{describe} + +\begin{describe}{mac} + {categorize (\=@ @ + @[[ :bind (@{ @ @! (@ @[@@]) @}^*) @]]) + \\ \ind\ind + (@{ @ @ @}^*) \- \\ + @^* \- + \nlret @^*} +\end{describe} + +\begin{describe}{fun} + {frob-identifier @ \&key :swap-case :swap-hyphen + @> @} +\end{describe} + +\begin{describe}{fun}{whitespace-char-p @ @> @} +\end{describe} + +\begin{describe}{fun} + {update-position @ @ @ + @> @ @} +\end{describe} + +\begin{describe}{fun} + {backtrack-position @ @ @ + @> @ @} +\end{describe} + +\begin{describe}{fun} + {compose @ \&rest @ @> @} +\end{describe} + +\begin{describe}{fun}{symbolicate \&rest @ @> @} +\end{describe} + +\begin{describe}{mac} + {maybe-print-unreadable-object (@ @ + @[[ :type @ @! + :identity @ @]]) \\ \ind + @^*} +\end{describe} + +\begin{describe}{mac} + {dosequence (@ @ + @[[ :start @ @! :end @ @! + :indexvar @ @]]) \\ \ind + @{ @ @! @ @}^*} +\end{describe} + +\begin{describe}{mac} + {define-access-wrapper @ @ + @[[ :read-only @ @]]} +\end{describe} + +\begin{describe}{mac} + {default-slot (@ @ @[@@]) \\ \ind + @^*} +\end{describe} + +\begin{describe}{mac} + {define-on-demand-slot @ @ (@) \\ \ind + @^*} +\end{describe} + +%%%-------------------------------------------------------------------------- +\section{Condition utilities} \label{sec:misc.condition} + +These symbols are defined in the @|sod-parser| package. + +\begin{describe}{cls}{enclosing-condition (condition) \&key :condition} +\end{describe} + +\begin{describe}{gf} + {enclosed-condition @ @> @} +\end{describe} + +\begin{describe}{fun}{cerror* @ \&rest @} +\end{describe} + +%%%-------------------------------------------------------------------------- +\section{Option parser} \label{sec:misc.optparse} + +These symbols are defined in the @!optparse| package. + +\begin{describe}{fun}{exit \&optional (@ 0) \&key :abrupt} +\end{describe} + +\begin{describe}{var}{*program-name*} +\end{describe} + +\begin{describe}{var}{*command-line*} +\end{describe} + +\begin{describe}{fun}{set-command-line-arguments} +\end{describe} + +\begin{describe}{cls}{loc} +\end{describe} + +\begin{describe}{fun}{locp @ @> @} +\end{describe} + +\begin{describe}{macro}{locf @ @> @} +\end{describe} + +\begin{describe*} + {\dhead{fun}{ref @ @> @} + \dhead{fun}{setf (ref @) @}} +\end{describe*} + +\begin{describe}{mac} + {with-locatives + @{ @ @! (@{ @ @! + (@ @[@@]) @}^*) @} \\ \ind + @^*} +\end{describe} + +\begin{describe}{fun}{moan @ \&rest @} +\end{describe} + +\begin{describe}{fun}{die @ \&rest @} +\end{describe} + +\begin{describe}{var}{*options*} +\end{describe} + +\begin{describe}{cls}{option} +\end{describe} + +\begin{describe}{fun}{optionp @ @> @} +\end{describe} + +\begin{describe}{fun} + {make-option \=@ @ \+ \\ + \&optional @ \\ + \&key :tag :negated-tag :arg-optional-p :documentation \- + \nlret @