\chapter{Exsym Tables: Separate Compilation Support}
\label{exsym-tables}

 {\em Exsym-Tables\/}, for EXternal SYMbol tables, are provided to support
separate compilation.  Exsym-tables map Lisp symbols to {\em exsym\/}s,
where an exsym is a structure that maps property indicators to values.
Functions are provided to create exsyms, exsym-tables, and to set and get
the property values of exsyms.  Exsym-tables also allow the compiler (or
some other program) to ensure that a consistent set of exsyms is being
used, by recording assumptions on an exsym.

\section{Creating Exsym Tables}

\begin{lispdocs}
\lispdoc make-exsym-table [Function]
\lispdoc exsym-table [Type]
\end{lispdocs}

 The function {\tt make-exsym-table} makes an empty exsym-table.  An exsym
maps keyword symbols to exsyms.

\lispdoc map-exsym-table fcn exsym-table [Function]

 Applies the function {\em fcn\/} to each entry in {\em exsym-table\/}.
The function is called for side-effect with argument {\em name\/} and {\em
exsym\/} for each exsym in {\em exsym-table\/}.  No value is returned.

\section{Exsyms}

\begin{lispdocs}
\lispdoc find-exsym symbol search-path [Function]
\lispdoc exsym-exists-p symbol exsym-table-or-search-path [Function]
\lispdoc install-exsym exsym exsym-table [Function]
\lispdoc copy-exsym exsym [Function]
\end{lispdocs}
 The function {\tt find-exsym} finds and returns the exsym named {\em
symbol\/} in {\em search-path\/}, which is a list of exsym-tables.  The
function {\tt exsym-exists-p} returns {\tt t} if an exsym for {\em
symbol\/} is present in {\em exsym-table-or-search-path\/}, which may be an
exsym-table or list of exsym-tables.  Precedence of exyms is by the order
in which the containing exsym-tables occur in the {\em
exsym-search-path\/}.  {\tt Install-exsym} store {\em exsym\/} in the
table {\em exsym-table\/} under the name of {\tt (exsym-name {\em
exsym\/})}.  {\tt Copy-exsym} returns a copy of {\em exsym\/}.


\lispdoc exsym-clear symbol exsym-table [Function]
 Clears all properties and assumptions on the exsym bound to {\em symbol\/}
in {\em exsym-table\/}.

\section{Exsym Properties}

\lispdoc define-exsym-property indicator \clauses 
        \list{{\tt :consistency-predicate} pred}
        \optgroup{\list{{\tt :consistency-encoder} encoder}}
        \optgroup{\list{{\tt :consistency-printer} printer}}
        [Macro]

The macro {\tt define-exsym-property} defines a property that may be used
in later calls to {\tt exsym-get}, {\tt exsym-put}, {\tt exsym-assume} and
{\tt exsym-assume-value}.  The consistency-predicate clause is required,
but the consistency-encoder and consistency-printer clauses are optional.

Note that all values stored in an exsym either as the value of a property
or as an encoding in an assumption must have CIOBL\footnote{CIOBL stands
for ``Compiler Input/Output Base Language'', and is discussed in
chapter~\ref{ciobl} in detail.} read/write methods if
exsym-tables or exsyms are to be written to CIOBL streams.

\lispdoc exsym-get symbol indicator search-path [Function]
 Finds the exsym for {\em symbol\/} in {\em search-path\/} and returns the
value of property {\em indicator\/} for that exsym.  Two values are
returned: the first is the value of the property or {\tt nil} if the
property is undefined or the exsym does not exist in {\em search-path\/},
the second is {\tt t} if the exsym exists and {\tt nil} otherwise.

\lispdoc exsym-put symbol indicator value exsym-table [Function]
 Finds the exsym for {\em symbol\/} in {\em exsym-table\/}, and sets the
value of {\em indicator\/} property to be {\em value\/}.  An error is
signaled if the exsym does not exist, or if {\em indicator\/} is not the
name of a valid exsym-property.  

 When a property of an exsym is set, then an encoding of the value is also
recorded.  The default encoder function is {\tt identity}, but other
encoders can be provided by supplying a {\tt :consistency-encoder} clause
to {\tt define-exsym-property}.

\section{Exsym Assumptions}

\begin{lispdocs}
\lispdoc exsym-assume assumer assumer-table assumee assumee-indicator
        assumee-search-path [Function]
\lispdoc exsym-assume-value assumer assumer-table assumee assumee-indicator
        assumee-search-path assumee-value [Function]
\end{lispdocs}
 The functions {\tt exsym-assume} and {\tt exsym-assume-value} record an
assumption on the exsym for {\em assumer\/} in the {\em assumer-table\/}
exsym-table.  The assumption consists of {\em assumee\/}, the name of the
exsym whose property is being used, {\em assumee-indicator\/}, the name of
the property being used, and the value of {\em assumee\/}'s {\em
indicator\/} exsym-property as found in {\em assumee-search-path\/}.  An
error is signaled if an exsym for {\em assumee\/} does not exist in {\em
assumee-search-path\/}.  {\tt Exsym-assume-value} is similar to {\tt
exsym-assume}, except that {\em assumee-value\/} is provided directly and
that an exsym for {\em assumee\/} need not exist in {\em
assumee-search-path\/}.

\section{Consistency Checking}

 Two functions are provided for checking the consistency of a set of
exsyms. 

\begin{lispdocs}
\lispdoc consistency-summary root-exsym-names search-path [Function]
\lispdoc describe-consistency root-exsym-names search-path [Function]
\end{lispdocs}

 These functions check the assumptions recorded on each of the exsyms
corresponding to {\em root-exsym-names\/} in {\em search-path\/}.  An
assumption about the value of property {\em indicator\/} on exsym {\em
assumee\/} is checked by applying the consistency-predicate for
exsym-property {\em indicator\/} to {\em actual-encoded-value\/} and {\em
assumed-encoded-value\/}, where {\em assumed-encoded-value\/} was stored in
the assumptions of {\em assumer\/} and {\em actual-encoded-value\/} was
found in the {\em search-path\/}.  

 The function {\tt describe-consistency} prints a detailed account of the
inconsistencies found using the consistency-printers for each
exsym-property to {\tt *standard-output*}.
