%!TEX root = manual.tex
%
\chapter{Invocation}
\label{chap:invocation}

\begin{quote}
  \texttt{asdlGen --\textit{command} [ \textit{command options} ] \textit{files} ...}
\end{quote}%

Where \texttt{\textit{command}} is one of
\begin{quote}
  \begin{tabular}{ll}
    \texttt{c}
      & Generate ANSI C \\
    \texttt{sml}
      & Generate Standard ML \\
    \texttt{haskell}
      & Generate Haskell \\
    \texttt{java}
      & Generate Java \\
    \texttt{cxx}
      & Generate C++ \\
    \texttt{doc}
      & Generate \texttt{doc} directory with HTML descriptions \\
    \texttt{typ}
      & Generate a machine readable type description of the inputs \\
    \texttt{check}
      & Check correctness of inputs \\
    \texttt{all}
      & Do all of the above \\
    \texttt{pp\char`\_pkl}
      & Pretty Print an \asdl{} pickle (see \secref{sec:pickles}).\\
  \end{tabular}
\end{quote}%

The \textit{command options} are specific to each command. For a complete
list of options examine the output files produced by a given command.
Each file should include a comment of all the available options and
the values used to produce the output.

\asdlgen{} reads the set of \texttt{\textit{files}}, which contain ASDL module
declarations and view declarations. The module declarations must be
complete and not refer to any other modules or types not defined in
one of the input files. The order of the input files is
unimportant. This closed set of files is referred to as a \emph{type environment}.

\section{Common Options}

Options common to all the commands include
\begin{description}
  \item[\normalfont\texttt{--no\char`\_action=}\{\texttt{true} $|$ \texttt{false}\} or \texttt{-n}] \mbox{}\\
      Do not write any output files. Instead output the list of files that would
      have been written to standard out.
  \item[\normalfont\texttt{--line\char`\_width=}\textit{width}] \mbox{}\\
    Set the maximum line width for pretty printing code. The default value
    is 72 characters.
  \item[\normalfont\texttt{--output\char`\_directory=}\textit{dir} or \texttt{-d} \textit{dir}] \mbox{}\\
    By default the output will be placed in the same directory as the
    input file from which it was produced.
    Some commands like \texttt{--java} will create their own subdirectory to
    place their output.
    The \texttt{--output\char`\_directory} option overrides the default output directory.
  \item[\normalfont\texttt{--view=}\textit{name} or \texttt{-V} \textit{name}] \mbox{}\\
    Sets the default view to \textit{name}. The default view name is by convention
    the command name with the first character capitalized. See \chapref{chap:views}
    for a more detailed description.
\end{description}%

\section{Language Specific Options}
\label{sec:language-specific-options}

All the commands that produce source code as output offer a different
command option to select the default base environment.
The base environment is the set of the initial definitions available to the code.
It defines the set of primitive types and functions used by the generated code.
For example using the option \texttt{--base\char`\_include=my-base.h}
when generating C code will insert the directive
\begin{quote}\begin{lstlisting}[language=c]
#include "my-base.h"
\end{lstlisting}\end{quote}%
in the appropriate place so the resulting code will use the definitions found in
\texttt{my-base.h} rather than the default set of primitive types.
Unless there is a need to globally redefine
the primitive types changing the base environment should be avoided.
The actual option names vary depending on the output language.

See \chapref{chap:support-code} for a more detailed description about the interfaces
to the default set of primitive types and functions provided with the current release.

\subsection{Options for C}
 \begin{description}
   \item[\normalfont\texttt{--base\char`\_include=}\textit{file}\texttt{.h}] \mbox{}\\
     The default value is \texttt{cii\char`\_base.h}. Name of the C header file to
     include that define the primitive types and functions for all the generated
     code.

   \item[\normalfont\texttt{--mono\char`\_types=}\{\texttt{true} $|$ \texttt{false}\}] \mbox{}\\
     The default value is \texttt{false}. If true expand sequence and option types into
     new distinct types for each different qualified type.

   \item[\normalfont\texttt{--attribs\char`\_default=}\{\texttt{true} $|$ \texttt{false}\}] \mbox{}\\
     The default value is \texttt{true}. Controls whether attributes fields are included in
     the argument to the default constructor generated by \asdlgen{} for sum
     types. If true then attributes are include as argument to the default
     constructors. If false the attributes are not included in the argument for
     the constructors.

   \item[\normalfont\texttt{--default\char`\_only=}\{\texttt{true} $|$ \texttt{false}\}] \mbox{}\\
     The default value is true. Controls whether or not to generate two
     constructors for sum types that have attributes. One constructor includes
     attributes as arguments the other does not. If this value is false then
     the \texttt{attribs\char`\_default} argument toggles between whether the default
     constructor contains attributes in the argument or the non-default
     constructor does. The default constructor is a function whose name is the
     same as the constructor in the sum type declaration. The non-default
     constructor is a function whose name is prefixed with either
     \texttt{with\char`\_attribs} or \texttt{no\char`\_attribs} depending on the value of
     \texttt{--attribs\char`\_default}.
     \textit{This mechanism will probably get moved
     into the view framework rather than being a command line switch.}
\end{description}%

\subsection{Options for C++}

\begin{description}
  \item[\normalfont\texttt{--base\char`\_include=}\textit{file}\texttt{.hxx}] \mbox{}\\
    The default value is \texttt{asdl\char`\_base.hxx}. Name of the C++ header file to
    include that defines the primitive types and functions for all the generated
    code.
  \item[\normalfont\texttt{--simple\char`\_sequences=}\{\texttt{true} $|$ \texttt{false}\}] \mbox{}\\
    The default value is true. Use a simple linked list representation
    for sequences. Set to false to use a template based sequence
    representation. See \texttt{asdl\char`\_base.hxx} for a default sequence template
    example.
\end{description}%

\subsection{Options for Java}
\begin{description}
  \item[\normalfont\texttt{--base\char`\_import=}\textit{package\char`\_spec}] \mbox{}\\
    The default value is \texttt{asdl\char`\_base.*}. The package import specification
    to define the primitive types and functions for all the generated
    code.
  \item[\normalfont\texttt{--simple\char`\_sequences=}\{\texttt{true}\textit{|}\texttt{false}\}] \mbox{}\\
    The default value is true. Use a simple linked list representation
    for sequences. Set to false to use  \texttt{java.util.Vector} instead.
\end{description}%

\subsection{Options for Standard ML}
\begin{description}
  \item[\normalfont\texttt{--base\char`\_signature=}\textit{signature-name}] \mbox{}\\
    The default value is \texttt{BASE}. The signature to \lstinline[language=SML]!include! in
    all signatures generated that define the primitive types.
  \item[\normalfont\texttt{--base\char`\_structure=}\textit{structure-name}] \mbox{}\\
    The default value is \texttt{Base}. The structure to \lstinline[language=SML]!open! in
    all structures generated that define the primitive types and functions.
\end{description}%

\subsection{Options for Haskell}
\begin{description}
  \item[\normalfont\texttt{--base\char`\_import=}\textit{module}] \mbox{}\\
    The default value is \texttt{HaskellBase}. The module to import unqualified
    that define the primitive types and functions for all the generated
    code.
\end{description}%

