%!TEX root = manual.tex
%
\chapter{Support Code}
\label{chap:support-code}

\textbf{Needs some more fleshing out}

This section lists the primitive functions and types that are required for
the code produced by \asdlgen{} to correctly compile.
Note that this presentation is language independent. 

\section{Required for All Languages}
All languages require the following
\newcommand{\ITEM}[1]{\item[\normalfont\color{\cdColor}\texttt{#1}]}
\begin{description}
  \ITEM{instream outstream} \mbox{}\\
    The types of input and output streams that the reader and writer functions expect.
  \ITEM{int} \mbox{}\\
    The type of integers, possibly a ``bignum'' type.
  \ITEM{string} \mbox{}\\
    The type of strings.
  \ITEM{identifier} \mbox{}\\
    The type of identifiers.
  \ITEM{read\char`\_tag write\char`\_tag} \mbox{}\\
    Read and write a constructor and length tags out in \asdl{} integer format.
    Both should use the languages standard integer types rather than a ``bignum'' types.
  \ITEM{read\char`\_int write\char`\_int} \mbox{}\\
    Read and write the \lstinline!int! type out in \asdl{} integer format.
  \ITEM{read\char`\_string write\char`\_string} \mbox{}\\
    Read and write the \lstinline!string! type out in the \asdl{} string format.
  \ITEM{read\char`\_identifier write\char`\_identifier} \mbox{}\\
    Read and write the \lstinline!identifier! type out in the \asdl{} identifier format.
  \ITEM{die} \mbox{}\\
    Signal a fatal error.
\end{description}%

\section{BigNums}
C and SML have libraries that use a bignum type
rather than the a fixnum for the \asdl{} int type. To have the int type
be a bignum in C use the flag \texttt{--base\char`\_include cii\char`\_big\char`\_base.h}. In
SML the flags are \texttt{--base\char`\_signature BIG\char`\_BASE} and
\texttt{--base\char`\_structure BigBase}.

\section{Lists and Options}
For code that does not use polymorphic list and option the following extra
types are needed along with the corresponding read and write functions
\begin{description}
  \ITEM{int\char`\_list int\char`\_option} \mbox{}\\
    The list and option types for integers.
  \ITEM{string\char`\_list string\char`\_option} \mbox{}\\
    The list an option types for strings.
  \ITEM{identifier\char`\_list identifier\char`\_option} \mbox{}\\
    The list an option types for identifiers.
\end{description}%

For code that supports polymorphic list and options the following extra
functions are required

\begin{description}
  \ITEM{read\char`\_list write\char`\_list} \mbox{}\\
    Functions whose first argument is a read or write
    function for a specific type that reads or writes a list of that type.
  \ITEM{read\char`\_option write\char`\_option} \mbox{}\\
    Functions whose first argument is a read or write
    function for a specific type that reads or writes a option of that type.
\end{description}%

\section{Note about \texttt{--mono\char`\_types=false} for C}
For the \texttt{--mono\char`\_types false} option in C these function expect functions
pointers that correspond to the following C \lstinline[language=c]!typedef!s
%
\begin{quote}\begin{lstlisting}[language=c]
typedef void *(*generic_reader_ty)(instream_ty s);
typedef void (*generic_writer_ty)(void *x,outstream_ty s);
\end{lstlisting}\end{quote}%

Function pointer with different argument types are distinct types in C that
can not be safely cast between because they may differ in calling
conventions. \asdlgen{} solves this problem by automatically generating
function stubs that internally cast the \lstinline[language=c]!void*! pointers for each option
and list type. These reader and writer functions are prefixed
\lstinline[language=c]!generic_!. There also should be \lstinline[language=c]!list_ty!
and \lstinline[language=c]!opt_ty! typedefs.
