[sod] / doc / output.tex

%%% -*-latex-*-
%%%
%%% Output machinery
%%%
%%% (c) 2015 Straylight/Edgeware
%%%

%%%----- Licensing notice ---------------------------------------------------
%%%
%%% 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
%%% 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{The output system} \label{ch:output}

This chapter deals with actually generating output files.  It will be of
interest to programmers introducing new layout object classes, or new kinds
of output files.  An understanding of the material in
\xref{sec:structures.layout} will prove valuable.

%%%--------------------------------------------------------------------------
\section{Output sequencing} \label{sec:output.sequencer}

C compilers are picky about the order in which things are presented to them
in their input; but information about the structure of our classes is
scattered among a variety of different layout objects.  It's not the case
that a layout object only contributes to a single localized portion of the
output: for example, a @|vtmsgs| layout object is responsible for declaring
both the appropriate @|struct $C$__vtmsgs_$a$| structure in the header file,
populated with method entry pointers, but also declaring its member in the
enclosing @|struct $C$__vt_$i$| structure.

One approach would be to have the various layout objects just know how to
call each other in the right order so as to have everything come out
properly.  That would make extending the translator, e.g., to add new kinds
of layout objects, rather difficult.  And it doesn't let users insert custom
C fragments in flexible ways.

Instead, there's a clear separation between which things need to be output,
and the order in which they're produced.

Ordering is handled by a \emph{sequencer} object.  A sequencer doesn't know
anything particular about output: its job is simply to do things in a
particular order.  It's described here because Sod only uses it for output
scheduling.

A sequencer maintains a collection of named \emph{items}, each of which has a
name and a list of functions associated with it.  A name can be any Lisp
object.  Names are compared using @|equal|, so lists can be used to construct
a hierarchical namespace.

The sequencer also maintains a collection of \emph{constraints}, which take
the form of lists of item names.  A constraint of the form @|($N_1$, $N_2$,
$\ldots$, $N_k$)| requires that the item named $N_1$ must be scheduled before
the item named $N_2$, and so on, all of which must be scheduled before the
item named $N_k$.  Items with these names do not need to exist or be known to
the sequencer.  An item name may appear in any number of constraints, all of
which apply.

It might be that a collection of constraints is impossible to satisfy: for
example, the set
\begin{center} \codeface
  (alice bob) \qquad (bob carol) \qquad (carol alice)
\end{center}
can't be satisfied, since the first constraint requires that @|alice|
precedes @|bob|, but the third says that @|alice| must come after @|carol|,
and the second that @|carol| comes after @|bob|: it's not possible that
@|alice| comes before @|bob| and after @|bob|.  In this case, the sequencer
fails and signals an error of type @|inconsistent-merge-error|.

It is possible, but tedious, to explicitly order an entire collection of
items by adding constraints.  In the absence of explicit constraints to order
them, items are ordered according to the order in which constraints naming
them were first added to the sequencer.  Items not named in any constraint
are not processed at all.

For example, suppose we have the following constraints.
\begin{center} \codeface
  (perl java) \qquad
  (lisp java) \qquad
  (python icon) \qquad
  (icon perl)
\end{center}
The constraints give us that $@|python| < @|icon| < @|perl| < @|java|$, and
also $@|lisp| < @|java|$.  In this case, @|lisp| precedes @|python| because
@|lisp| is mentioned in the second constraint while @|python| isn't mentioned
until the third.  So the final processing order is
\begin{center}
  @|lisp|, \quad
  @|python|, \quad
  @|icon|, \quad
  @|perl|, \quad
  @|java|
\end{center}


\begin{describe}{cls}{sequencer-item}
  An object of class @|sequencer-item| represents a sequencer item.
  Sequencer items maintain a \emph{name} and a list of \emph{functions}.
  Names are compared using @|equal|.

  The functions are maintained in \emph{reverse order}, because it's
  convenient to be able to add new functions using @|push|.
\end{describe}

\begin{describe}{fun}{sequencer-item-p @<object> @> @<generalized-boolean>}
  Return non-nil if and only if @<object> is a @|sequencer-item|.
\end{describe}

\begin{describe}{fun}
    {make-sequencer-item @<name> \&optional @<functions> @> @<item>}
  Create and return a new sequencer item with the given @<name> and list of
  @<functions>; the list of functions defaults to nil if omitted.
\end{describe}

\begin{describe*}
    {\dhead{fun}{sequencer-item-name @<item> @> @<name>}
     \dhead{fun}{sequencer-item-functions @<item> @> @<list>}
     \dhead{fun}{setf (sequencer-item-functions @<item>) @<list>}}
   These functions read or modify the state of a sequencer @<item>, as
   originally established by @|make-sequencer-item|.

   It is an error to modify an item's list of functions during a call to
   @|invoke-sequencer-items| on the item's owning sequencer.
\end{describe*}

\begin{describe}{cls}{sequencer () \&key :constraints}
\end{describe}

\begin{describe*}
    {\dhead{fun}{sequencer-constraints @<sequencer> @> @<list>}
     \dhead{fun}{setf (sequencer-constraints @<sequencer>) @<list>}
     \dhead{fun}{sequencer-table @<sequencer> @> @<hash-table>}}
\end{describe*}

\begin{describe}{fun}{ensure-sequencer-item @<sequencer> @<name> @> @<item>}
\end{describe}

\begin{describe}{fun}{add-sequencer-constraint @<sequencer> @<constraint>}
\end{describe}

\begin{describe}{fun}
    {add-sequencer-item-function @<sequencer> @<name> @<function>}
\end{describe}

\begin{describe}{fun}
    {invoke-sequencer-items @<sequencer> \&rest @<arguments>}
\end{describe}

\begin{describe}{gf}{hook-output @<object> @<reason> @<sequencer>}
  \begin{describe}{meth}{t,t}
    {hook-output (@<object> t) (@<reason> t) @<sequencer>}
  \end{describe}
\end{describe}

\begin{describe}{mac}
    {sequence-output (@<stream-var> @<sequencer>)               \\ \ind
      @[ :constraint (@<item-name>^*) @]                        \\
      @{ (@<item-name> @<form>^*) @}^*}
\end{describe}

%%%--------------------------------------------------------------------------
\section{Output structure} \label{output.structure}

The structures of the header and implementation files produced by the
translator are detailed in tables~\ref{tab:output.structure.header}
and~\ref{tab:output.structure.impl}, respectively.

The following notes may be helpful.
\begin{itemize}
\item The `specializers' shown in the tables identify the method of the
  @|hook-output| function responsible for producing the corresponding
  `contents'.  Subclasses can extend or override the listed methods (with
  appropriate care).
\item A row showing an `item' but no `specializers' indicate that the
  translator does not prodice output for that item.  It may be present for
  ordering purposes, or as a place for user output.
\item A row showing `specializers' but (apparently) no `contents' indicates
  that a blank line is emitted at that point.
\end{itemize}

\begingroup
\LTleft=-\leftindent plus 1fil minus 1fil
\LTright=0pt plus 1fil minus 1fil
\small
\def\banner#1{\hbox to\hsize{/*@-@-@-@-@- #1
  \rlap{@-}\leaders\hbox{@-}\hfil\llap{@-}*/}}
\def\fmtspecs#1, #2 {@|#1|, @|(eql #2)|}
\def\slotlabel#1#2{\leavevmode\hbox to30mm{\kern#1em/* #2\hfil= */}}

\clearpage
\begin{longtable}{>{\codeface}p{41mm}>{\fmtspecs}l>{\codeface}p{65mm}}
  \caption{Header file output structure}
  \label{tab:output.structure.header}                           \\ \hlx{hv}
  \thd{Sequencer item}          & \thd{@|hook-output| specializers}
        & \thd{Output}                                          \\ \hlx{vhv}
  \endfirsthead
  \caption[]{Header file output structure \emph{(cont.)}}       \\ \hlx{hv}
  \thd{Sequencer item}          & \thd{@|hook-output| specializers}
        & \thd{Contents}                                        \\ \hlx{vhv}
  \endhead
                                                                   \hlx{vh}
  \endfoot
  x & sod-class-effective-slot, 'class & x \kill
  %
  :prologue                     & module, :h
        & \begin{nprog}
            /\=* @-*@- mode: c; indent-tabs-mode: nil @-*@-     \\
             \>*                                                \\
             \>* Header file generated by SOD for @<module>     \\
             \>*/                                               \\
           \end{nprog}                                          \\ \hlx{v/}
  (:guard :start)               & module, :h
        & \begin{nprog}
            \#ifndef @<MODULE>{}_H                              \\
            \#define @<MODULE>{}_H                              \\+
            \#ifdef __cplusplus                                 \\ \ind
              extern "C" \{                                   \-\\
            \#endif                                             \\
          \end{nprog}                                           \\ \hlx{v/}
  %
  (:typedefs :start)            & module, :h
        & \begin{nprog} \banner{Forward type declarations} \\ \end{nprog}
                                                                \\*\hlx{v}
  :typedefs                     & sod-class, :h
        & typedef struct @<class>{}__ichain_@<cls> @<class>;    \\*\hlx{v}
  (:typedefs :end)              & module, :h                    \\ \hlx{v/}
  %
  (:includes :start)            & module, :h
        & \begin{nprog} \banner{External header files} \\ \end{nprog}
                                                                \\*\hlx{v}
  :includes                                                     \\*\hlx{v}
  :early-decls                  & sod-class, :h
        & SOD__VARARGS_MACRO_PREAMBLE                           \\*\hlx{v}
  (:includes :end)              & module, :h                    \\*\hlx{v}
  %
  (:early-user :start)                                          \\*
  :early                                                        \\*
  (:early-user :end)                                            \\ \hlx{v/}
  %
  (:classes :start)                                             \\*\hlx{v}
  %
  (@<class> :banner)            & sod-class, :h
        & \begin{nprog} \banner{Class @<class>} \\ \end{nprog}  \\*\hlx{v}
  %
  (@<class> :islots :start)     & sod-class, :h
        & \begin{nprog}
            /* Instance slots. */                               \\
            struct @<class>{}__islots \{
          \end{nprog}                                           \\*\hlx{v}
  (@<class> :islots :slots)     & sod-slot, 'islots
        & \quad @<type> @<slot-name>;                           \\*\hlx{v}
  (@<class> :islots :end)       & sod-class, :h
        & \begin{nprog} \}; \\ \end{nprog}                      \\ \hlx{v/}
  %
  (@<class> :vtmsgs :start)                                     \\*
  (@<class> :vtmsgs @<super> :start) & vtmsgs, 'vtmsgs
        & \begin{nprog}
            /* Messages protocol from class @<super>. */        \\*
            struct @<class>{}__vtmsgs_@<s> \{
          \end{nprog}                                           \\*\hlx{v}
  (@<class> :vtmsgs @<super> :slots) & method-entry, 'vtmsgs
        & \quad @<type> (*msg)(@<class> *, \dots);              \\*\hlx{v}
  (@<class> :vtmsgs @<super> :end) & vtmsgs, 'vtmsgs
        & \begin{nprog} \}; \\ \end{nprog}                      \\*
  (@<class> :vtmsgs :end)                                       \\ \hlx{v/}
  %
  (@<class> :vtables :start)                                    \\*
  \begin{nprog}
    (@<class> \=:vtable                                         \\
              \>@<chain-head> :start)
  \end{nprog}                   & vtable, :h
        & \begin{nprog}
            /* Vtable structure. */                             \\*
            struct @<class>{}__vt_@<h> \{
          \end{nprog}                                           \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:vtable                                         \\
              \>@<chain-head> :slots)
  \end{nprog}                   & class-pointer, :h
        & \quad const @<meta> *_class;                          \\*
  \begin{nprog}
    (@<class> \=:vtable                                         \\
              \>@<chain-head> :slots)
  \end{nprog}                   & class-pointer, :h
        & \quad const @<meta> *_cls_@<n>;                       \\*
  \begin{nprog}
    (@<class> \=:vtable                                         \\
              \>@<chain-head> :slots)
  \end{nprog}                   & base-offset, :h
        & \quad size_t _base;                                   \\*
  \begin{nprog}
    (@<class> \=:vtable                                         \\
              \>@<chain-head> :slots)
  \end{nprog}                   & chain-offset, :h
        & \quad ptrdiff_t _off_@<h>;                            \\*
  \begin{nprog}
    (@<class> \=:vtable                                         \\
              \>@<chain-head> :slots)
  \end{nprog}                   & vmsgs, :h
        & \quad struct @<class>{}__vtmsgs_@<s> @<s>;            \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:vtable                                         \\
              \>@<chain-head> :end)
  \end{nprog}                   & vtable, :h
        & \begin{nprog}
            \};                                                 \\+
            /* Union of equivalent superclass vtables. */       \\
            union @<class>{}__vtu_@<h> \{                       \\ \ind
              struct @<super>{}__vt_@<h> @<s>;                  \\
              \quad $\vdots$                                  \-\\
            \};                                                 \\
          \end{nprog}                                           \\*
  (@<class> :vtables :end)                                      \\
  %
  (@<class> :vtable-externs)    & sod-class, :h
        & /* Vtable structures. */                              \\*
  (@<class> :vtable-externs)    & vtable, :h
        & extern const union @<class>{}__vtu_@<h> @<class>{}__vtable_@<h>;
                                                                \\*
  (@<class> :vtable-externs-after) & sod-class, :h              \\ \hlx{v/}
  %
  (@<class> :methods :start)    & sod-class, :h
        & /* Direct methods. */                                 \\*
  (@<class> :methods :defs)     & sod-method, :h
        & \begin{nprog}
            struct @<class>{}__@<role>{}_suppliedp_@<s>{}__@<msg> \{ \\ \ind
              unsigned @<arg>: 1;                               \\
              \quad $\vdots$                                  \-\\
            \};                                                 \\
          \end{nprog}                                           \\*\hlx{v}
  (@<class> :methods)           & sod-method, :h
        & struct @<class>{}__@<role>{}_method_@<s>{}__@<msg>(\dots);
                                                                \\*\hlx{v}
  (@<class> :methods :end)      & sod-class, :h                 \\ \hlx{v/}
  %
  (@<class> :ichains :start)                                    \\*
  \begin{nprog}
    (@<class> \=:ichains                                        \\
              \>@<chain-head> :start)
  \end{nprog}                   & ichain, :h
        & \begin{nprog}
            /* Instance chain structure. */                     \\
            struct @<class>{}__ichain_@<h> \{
          \end{nprog}                                           \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:ichains                                        \\
              \>@<chain-head> :slots)
  \end{nprog}                   & vtable-pointer, :h
        & \quad const struct @<class>{}__vt_@<h> *_vt;          \\*
  \begin{nprog}
    (@<class> \=:ichains                                        \\
              \>@<chain-head> :slots)
  \end{nprog}                   & islots, :h
        & \quad struct @<class>{}__islots @<c>;                 \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:ichains                                        \\
              \>@<chain-head> :end)
  \end{nprog}                   & vtable, :h
        & \begin{nprog}
            \};                                                 \\+
            /* Union of equivalent superclass chains. */        \\
            union @<class>{}__ichainu_@<h> \{                   \\ \ind
              struct @<super>{}__ichain_@<h> @<s>;              \\
              \quad $\vdots$                                  \-\\
            \};                                                 \\
          \end{nprog}                                           \\*
  (@<class> :ichains :end)                                      \\ \hlx{v/}
  %
  (@<class> :ilayout :start)    & ilayout, :h
        & \begin{nprog}
            /* Instance layout. */                              \\
            struct @<class>{}__ilayout \{
          \end{nprog}                                           \\*\hlx{v}
  (@<class> :ilayout :slots)    & ichain, 'ilayout
        & \quad union @<class>{}__ichainu_@<h>;                 \\*\hlx{v}
  (@<class> :ilayout :end)      & ilayout, :h
        & \begin{nprog} \}; \\ \end{nprog}                      \\ \hlx{v/}
  %
  (@<class> :conversions)       & sod-class, :h
        & \begin{nprog}
            /* Conversion macros. */                            \\
            \#define @<CLASS>{}__CONV_@<S>(_obj) \dots          \\
            \quad $\vdots$                                      \\
          \end{nprog}                                           \\ \hlx{v/}
  %
  (@<class> :message-macros)    & sod-class, :h
        & \begin{nprog}
            /* Message invocation macros. */                    \\
            \#define @<class>{}_@<msg>(me, \dots) \dots         \\
            \quad $\vdots$                                      \\
          \end{nprog}                                           \\ \hlx{v/}
  %
  (@<class> :object)            & sod-class, :h
        & \begin{nprog}
            /* The class object. */                             \\
            extern const struct @<meta>{}__ilayout @<class>{}__classobj; \\
            \#define @<class>{}__class (\&\dots)                \\
            \#define @<class>{}__cls_@<n> (\&\dots)             \\
            \quad $\vdots$                                      \\
          \end{nprog}                                           \\*\hlx{v}
  %
  (:classes :end)                                               \\ \hlx{v/}
  %
  (:user :start)                                                \\*
  :user                                                         \\*
  (:user :end)                                                  \\ \hlx{v/}
  %
  (:guard :end)                 & module, :h
        & \begin{nprog}
            \banner{That's all, folks}                          \\+
            \#ifdef __cplusplus                                 \\ \ind
              \}                                              \-\\
            \#endif                                             \\+
            \#endif
          \end{nprog}                                           \\*\hlx{v}
  %
  :epilogue                                                     \\
\end{longtable}

\clearpage
\begin{longtable}{>{\codeface}p{41mm}>{\fmtspecs}l>{\codeface}p{65mm}}
  \caption{Implementation file output structure}
  \label{tab:output.structure.impl}                             \\ \hlx{hv}
  \thd{Sequencer item}          & \thd{@|hook-output| specializers}
        & \thd{Contents}                                        \\ \hlx{vhv}
  \endfirsthead
  \caption[]{Implementation file output structure \emph{(cont.)}}
                                                                \\ \hlx{hv}
  \thd{Sequencer item}          & \thd{@|hook-output| specializers}
        & \thd{Contents}                                        \\ \hlx{vhv}
  \endhead
                                                                   \hlx{vh}
  \endfoot
  %
  :prologue                     & module, :c
        & \begin{nprog}
            /\=* @-*@- mode: c; indent-tabs-mode: nil @-*@-     \\
             \>*                                                \\
             \>* Implementation file generated by SOD for @<module> \\
             \>*/                                               \\
           \end{nprog}                                          \\ \hlx{v/}
  %
  (:includes :start)            & module, :c
        & \begin{nprog}
            \banner{External header files}                      \\
          \end{nprog}                                           \\*\hlx{v}
  :includes                                                     \\*\hlx{v}
  (:includes :end)              & module, :c                    \\*\hlx{v}
  %
  (:early-user :start)                                          \\*
  :early                                                        \\*
  (:early-user :end)                                            \\ \hlx{v/}
  %
  (:classes :start)                                             \\*\hlx{v}
  %
  (@<class> :banner)            & sod-class, :c
        & \begin{nprog} \banner{Class @<class>} \\ \end{nprog}  \\*\hlx{v}
  %
  (@<class> :direct-methods :start)                             \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:direct-method                                  \\
              \>@<method> :banner)
  \end{nprog}                   & sod-method, :c
        & /* Direct @<role> method on `@<s>.@<msg>' defined by @<class>. */
                                                                \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:direct-method                                  \\
              \>@<method> :start)
  \end{nprog}                   & delegating-direct-method, :c
        & \#define CALL_NEXT_METHOD (next_method(\dots))        \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:direct-method                                  \\
              \>@<method> :body)
  \end{nprog}                   & sod-method, :c
        & \begin{nprog}
            @<type> @<class>{}__@<role>{}_method_@<s>{}__@<msg>(\dots) \\
            \{                                                  \\ \ind
              $\vdots$                                        \-\\
            \}
          \end{nprog}                                           \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:direct-method                                  \\
              \>@<method> :end)
  \end{nprog}                   & delegating-direct-method, :c
        & \#undef CALL_NEXT_METHOD                              \\*
  \begin{nprog}
    (@<class> \=:direct-method                                  \\
              \>@<method> :end)
  \end{nprog}                   & sod-method, :c                \\*\hlx{v}
  (@<class> :direct-methods :end)                               \\ \hlx{v/}
  %
  (@<class> :effective-methods) & basic-effective-method, :c
        & \begin{nprog}
            /\=* Keyword argument structure for `@<s>.@<msg>' defined \\
             \>* on class @<class>.                             \\
             \>*/                                               \\
            struct @<class>{}__keywords_@<s>{}__@<msg> \{       \\ \ind
              unsigned @<arg>{}__suppliedp: 1;                  \\
              \quad $\vdots$                                    \\
              @<type> @<arg>;                                   \\
              \quad $\vdots$                                  \-\\
            \};                                                 \\+
            @<effective-method-functions>                       \\
          \end{nprog}                                           \\ \hlx{v/}
  %
  (@<class> :vtables :start)                                    \\*\hlx{v}
  (@<class> :vtable @<chain-head> :start) & vtable, :c
        & \begin{nprog}
            /* Vtable for @<chain-head> chain. */               \\
            const union @<class>{}__vtu_@<h> @<class>{}__vtable_@<h> = \{
          \end{nprog}                                           \\*\hlx{v}
  \begin{nprog}
    (@<class> \=:vtable @<chain-head>                           \\
              \>:class-pointer @<meta>)
  \end{nprog}                   & class-pointer, :c
        & \slotlabel{1}{_class} \&@<cls>{}__classobj.@<n>.@<n>, \\*
  \begin{nprog}
    (@<class> \=:vtable @<chain-head>                           \\
              \>:class-pointer @<meta>)
  \end{nprog}                   & class-pointer, :c
        & \slotlabel{1}{_cls_@<n>} \&@<cls>{}__classobj.@<n>.@<n>, \\*
  \begin{nprog}
    (@<class> \=:vtable @<chain-head>                           \\
              \>:base-offset)
  \end{nprog}                   & base-offset, :c
        & \slotlabel{1}{_base} offsetof(\dots),                 \\*
  \begin{nprog}
    (@<class> \=:vtable @<chain-head>                           \\
              \>:chain-offset @<target-chain>)
  \end{nprog}                   & chain-offset, :c
        & \slotlabel{1}{_off_@<i>} SOD_OFFSETDIFF(\dots),       \\*
  \begin{nprog}
    (@<class> \=:vtable @<chain-head>                           \\
              \>:vtmsgs @<super> :start)
  \end{nprog}                   & vtmsgs, :c
        & \quad \{ /* Method entries for @<super> messags. */   \\*
  \begin{nprog}
    (@<class> \=:vtable @<chain-head>                           \\
              \>:vtmsgs @<super> :slots)
  \end{nprog}                   & method-entry, :c
        & \slotlabel{2}{@<mentry>} @<mentry-func>,              \\
  \begin{nprog}
    (@<class> \=:vtable @<chain-head>                           \\
              \>:vtmsgs @<super> :end)
  \end{nprog}                   & vtmsgs, :c
        & \quad \},                                             \\*
  (@<class> :vtable @<chain-head> :end) & vtable, :c
        & \};                                                   \\*\hlx{v}
  (@<class> :vtables :end)                                      \\ \hlx{v/}
  %
  (@<class> :object :prepare)   & sod-class-effective-slot, 'class
        & @<definitions>                                        \\*\hlx{v}
  %
  (@<class> :object :start)     & sod-class, :c
        & \begin{nprog}
            /* The class object. */                             \\
            const struct @<meta>{}__ilayout @<class>{}__classobj = \{
          \end{nprog}                                           \\*\hlx{v}
  %
  \begin{nprog}
    (@<class> \=:object                                         \\
              \>@<meta-head> :ichain :start)
  \end{nprog}                   & ichain, 'class
        & \quad \{ \{ /* @<n> ichain */                         \\*
  \begin{nprog}
    (@<class> \=:object                                         \\
              \>@<meta-head> :ichain :start)
  \end{nprog}                   & vtable-pointer, 'class
        & \slotlabel{3}{_vt} \&@<meta>{}__vtable_@<n>.@<m>,     \\*
  \begin{nprog}
    (@<class> \=:object                                         \\
              \>@<meta> :slots :start)
  \end{nprog}                   & islots, 'class
        & \quad\quad\quad \{ /* Class @<meta> */                \\*
  \begin{nprog}
    (@<class> \=:object                                         \\
              \>@<meta> :slots)
  \end{nprog}                   & effective-slot, 'class
        & \slotlabel{4}{@<slot>} @<value>                       \\*
  \begin{nprog}
    (@<class> \=:object                                         \\
              \>@<meta> :slots :end)
  \end{nprog}                   & islots, 'class
        & \quad\quad\quad \}                                    \\*
  \begin{nprog}
    (@<class> \=:object                                         \\
              \>@<meta-head> :ichain :end)
  \end{nprog}                   & ichain, 'class
        & \quad \} \},                                          \\*
  (@<class> :object :end)       & sod-class, :c
        & \};                                                   \\*\hlx{v}
  %
  (:classes :end)                                               \\ \hlx{v/}
  %
  (:user :start)                                                \\*
  :user                                                         \\*
  (:user :end)                                                  \\ \hlx{v/}
  %
  :epilogue                     & module, :c
        & \banner{That's all, folks}                            \\
\end{longtable}
\endgroup

%%%--------------------------------------------------------------------------
\section{Module output} \label{output.module}

\subsection{Producing output}

\begin{describe}{gf}
    {module-output-file @<module> @<output-type> @<output-dir>
      @> @<pathname>}
  \begin{describe*}
      {\dhead{meth}{module,symbol}
          {module-output-file \=(@<module> module)              \\
                              \>(@<output-type> symbol)         \\
                              \>@<output-dir>
           \nlret @<pathname>}
       \dhead{meth}{module,pathname}
          {module-output-file \=(@<module> module)              \\
                              \>(@<output-type> pathname)       \\
                              \>@<output-dir>
           \nlret @<pathname>}}
  \end{describe*}
\end{describe}

\begin{describe}{gf}{write-dependency-file @<module> @<reason> @<output-dir>}
\end{describe}

\begin{describe}{fun}{output-module @<module> @<reason> @<stream>}
\end{describe}


\subsection{Managing output types} \label{output.module.manage}

\begin{describe}{fun}{declare-output-type @<reason> @<pathname>}
\end{describe}

\begin{describe}{fun}{output-type-pathname @<reason> @> @<pathname>}
\end{describe}


\subsection{Utilities} \label{output.module.utilities}

\begin{describe}{fun}{banner @<title> @<output> \&key :blank-line-p}
\end{describe}

\begin{describe}{fun}{guard-name @<filename> @> @<string>}
\end{describe}

\begin{describe}{fun}
    {one-off-output @<token> @<sequencer> @<item-name> @<function>}
\end{describe}

%%%--------------------------------------------------------------------------
\section{Class output} \label{output.class}

\begin{describe}{var}{*instance-class*}
\end{describe}

\begin{describe}{gf}{emit-class-typedef @<class> @<stream>}
\end{describe}

\begin{describe}{gf}{emit-class-object-decl @<class> @<stream>}
\end{describe}

\begin{describe}{gf}{emit-class-conversion-macro @<class> @<super> @<stream>}
\end{describe}

\begin{describe*}
    {\dhead{gf}{emit-message-macro @<class> @<entry> @<stream>}
     \dhead{gf}{emit-message-macro-defn
                  \=@<class> @<entry> @<varargsp> @<me> \\
                  \>@<in-names> @<out-names> @<stream>}}
\end{describe*}

%%%----- That's all, folks --------------------------------------------------

%%% Local variables:
%%% mode: LaTeX
%%% TeX-master: "sod.tex"
%%% TeX-PDF-mode: t
%%% End: