\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>, \\*
+ \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}
\>@<in-names> @<out-names> @<stream>}}
\end{describe*}
-%% output for `h' files
-%%
-%% prologue
-%% guard start
-%% typedefs start
-%% typedefs
-%% typedefs end
-%% includes start
-%% includes
-%% includes end
-%% classes start
-%% early-user start
-%% early-user
-%% early-user end
-%% CLASS banner
-%% CLASS islots start
-%% CLASS islots slots
-%% CLASS islots end
-%% CLASS vtmsgs start
-%% CLASS vtmsgs CLASS start
-%% CLASS vtmsgs CLASS slots
-%% CLASS vtmsgs CLASS end
-%% CLASS vtmsgs end
-%% CLASS vtables start
-%% CLASS vtables CHAIN-HEAD start
-%% CLASS vtables CHAIN-HEAD slots
-%% CLASS vtables CHAIN-HEAD end
-%% CLASS vtables end
-%% CLASS vtable-externs
-%% CLASS vtable-externs-after
-%% CLASS methods start
-%% CLASS methods
-%% CLASS methods end
-%% CLASS ichains start
-%% CLASS ichains CHAIN-HEAD start
-%% CLASS ichains CHAIN-HEAD slots
-%% CLASS ichains CHAIN-HEAD end
-%% CLASS ichains end
-%% CLASS ilayout start
-%% CLASS ilayout slots
-%% CLASS ilayout end
-%% CLASS conversions
-%% CLASS object
-%% classes end
-%% user start
-%% user
-%% user end
-%% guard end
-%% epilogue
-
-%% output for `c' files
-%%
-%% prologue
-%% includes start
-%% includes
-%% includes end
-%% early-user start
-%% early-user
-%% early-user end
-%% classes start
-%% CLASS banner
-%% CLASS direct-methods start
-%% CLASS direct-methods METHOD start
-%% CLASS direct-methods METHOD body
-%% CLASS direct-methods METHOD end
-%% CLASS direct-methods end
-%% CLASS effective-methods
-%% CLASS vtables start
-%% CLASS vtables CHAIN-HEAD start
-%% CLASS vtables CHAIN-HEAD class-pointer METACLASS
-%% CLASS vtables CHAIN-HEAD base-offset
-%% CLASS vtables CHAIN-HEAD chain-offset TARGET-HEAD
-%% CLASS vtables CHAIN-HEAD vtmsgs CLASS start
-%% CLASS vtables CHAIN-HEAD vtmsgs CLASS slots
-%% CLASS vtables CHAIN-HEAD vtmsgs CLASS end
-%% CLASS vtables CHAIN-HEAD end
-%% CLASS vtables end
-%% CLASS object prepare
-%% CLASS object start
-%% CLASS object CHAIN-HEAD ichain start
-%% CLASS object SUPER slots start
-%% CLASS object SUPER slots
-%% CLASS object SUPER vtable
-%% CLASS object SUPER slots end
-%% CLASS object CHAIN-HEAD ichain end
-%% CLASS object end
-%% classes end
-%% user start
-%% user
-%% user end
-%% epilogue
-
%%%----- That's all, folks --------------------------------------------------
%%% Local variables:
~mdw / sod / commitdiff