\chapter{Installation and Usage}
\label{ch:system}

This chapter describes how to install and use the \agfl\ system. The
installation is platform specific, the usage is the same for all
installations.

\section{Installation}\label{install}
\YY{installing}{agfl}
The \agfl\ system can be installed in several ways. For a number of
platforms, binary packages with pre-compiled executables are available.
These packages can be found at {\tt ftp://ftp.cs.kun.nl/pub/agfl/}. If
there are no binary packages available for a platform, or if (re-)
compilation if preferred, the source package can also be retrieved from
the URL mentioned above.

A compiled version of \agfl\ expects to be able to run some programs to
generate an executable. The C compiler is used for this step. As such,
the \agfl\ system requires the presence of a C compiler during
compilation.

\subsection{Unix flavours}
\YY{installing}{cdl3}

Compiling and installing \agfl\ on Unix and alike systems is quite
straight forward. Required are:
\begin{itemize}
\item a recent C and C++ compiler, preferably GCC;
\item a standard shell (usually {\tt /bin/sh} suffices);
\item the GNU make program;
\item tar and GNU's gzip;
\end{itemize}

The compiler part of the \agfl\ system is written in CDL3. As first
step, the CDL3 compiler should be built and installed. The source package
for this compiler can be found at the same place as the \agfl\ source
packages.

To compile and install CDL3 and \agfl, please read the {\tt README} and
{\tt INSTALL} contained in the source packages.

The usage section below expects the programs, as installed by the
{\tt make install} step, to be in the user's path.

\subsection{MS Windows}
Compiling \agfl\ for MS Windows is harder than compiling \agfl\ for a
Unix flavor. Required are:
\begin{itemize}
\item MingW32, downloadable from several places on the Internet;
\item a program to extract the source tarball (the MingW32 port contains
a tar and a gzip port).
\end{itemize}

The Cygwin suite might also be used instead of MingW32, but this is not
tested. To compile \agfl, special makefiles are included. These files
are called {\tt Makefile.cygwin} for historical reasons. These makefiles
need modifications in order to find various programs.

The compiler part of the \agfl\ system is written in CDL3. As first
step, the CDL3 compiler should be built and installed. The source package
for this compiler can be found at the same place as the \agfl\ source
packages.

The \agfl\ parser generator uses the C preprocessor, the assembler and
linker/loader to generate an executable. For MS Windows platforms, it is
recommended to download the binary package, which includes the
appropriate programs to do this.\footnote{The binary package contains a
stripped-down version of the MingW32 suite: enough to be used by the
\agfl parser generator, but not enough to compile the whole \agfl\
package.} Copying the contents of the {\tt agfl-binary} directory filled
during compilation, to the {\tt agfl} directory from the binary package
is sufficient.

The binary package for MS Windows also contains a script called
{\tt setagfl.bat}. This script might need modifications to reflect the
actual place where the \agfl\ package is installed. These modifications
can be done using any text editor. To use \agfl, start a command prompt
and run the {\tt setagfl.bat} script once for each session, or put the
contents in the {\tt autoexec.bat} file.

\section{Usage}\label{usage}
\subsection{Commandline Options}
Both the parser generator \agfl\ and generated parsers have various
commandline options. When invoking \agfl\ or a generated parser with the
{\tt -h} option, all possible commandline options will be shown.

\subsection{A Simple Grammar}
For the examples to work, \agfl\ should be installed and the programs
should be in the search path. To verify this, the {\tt agfl} command can
be invoked:
\begin{verbatim}
$ agfl
agfl: compiler driver for agfl version 2.5
\end{verbatim}

The dollar sign (``{\tt \$}'') is used as command prompt in the examples
below. For MS Windows systems, this will be \verb+C:\\agfl+ or something
similair.

Writing the various text files can be done by using any text editor
which can write plain ASCII text files. 

To show the behaviour of the \agfl\ system and generated parsers, we
will use a toy grammar that consists of two files. The grammar file
{\tt example.gra} looks as follows:
\begin{grammar}
GRAMMAR example.

LEXICON simplelex DEFINES verb(NUMBER, PERSON).

ROOT toy.

NUMBER :: singular | plural.
PERSON :: first | second | third.

toy:
  subject (NUMBER, PERSON),
    verb (NUMBER, PERSON).

subject (singular, frist): "I".
subject (NUMBER, second): "you".
subject (singular, third):
  "he";
  "she";
  "it".
subject (plural, first): "we".
subject (plural, third): "they".
\end{grammar}

\noindent {\bf Important:} there is an intentional error in this file.
The second parameter of the first {\sf subject} rule should be
{\sf first}. This error is put in to show errors generated by the parser
generator.

The {\tt simplelex.dat} file looks like this:
\begin{grammar}
"walk"          verb (singular, first | second)
"walks"         verb (singular, third)
"walk"          verb (plural, PERSON)
\end{grammar}

After making these two files in the current directory, \agfl\ can be
invoked:
\begin{verbatim}
$ agfl example
example.gra:12:25: error: affix terminal "frist" does not occur in any domain
stopping: 1 error found...
\end{verbatim}
As expected, an error has been found in the file {\tt example.gra},
line 12 at character position 25.
Correcting this error and restarting \agfl\ should
give no more error messages and will build an executable named
{\tt example} (or {\tt example.exe} for MS Windows).

Parsing text with the generated parser is straight-forward. When the
{\tt example} program is started, it shows {\tt >>}, the prompt:
\begin{verbatim}
$ example
>>
\end{verbatim}
On this prompt, a text can be entered. When the enter-key is pressed,
the text will be parsed and one or more parse trees will be shown:
\begin{verbatim}
$ example
>> I walk
toy
  subject(singular, first)
    "I"
  verb(singular, first)
    "walk"

>> 
\end{verbatim}
The sentence ``I walk'' has just one parse tree. The sentence ``you
walk'' results in two parse trees.

