\chapter{Tutorial}

\par
This tutorial is based on an example : an imaginary programme named
'sample' . GAA includes instructions that are not described in this tutorial.
Please read the GAA Quick reference !


\section{GAA's input and output}
 When you call GAA, you give him a file written in
GAA language which describes the arguments of your programme. GAA
creates a C file that you'll have to add to your Makefile and a header
file that you'll need to include in your C/C++ source.

\par
Typical GAA call:
{\bf gaa filename.gaa} \\
two files are created by GAA: {\it filename\_gaa.h} and {\it filename\_gaa.c}

\section{GAA's principle}
GAA provides two functions:
\begin{enumerate}
 \item {\bf int gaa(int argc, char *argv[ ], gaa info *gaaval)} calls
 the argument analyser
 \begin{itemize}
  \item {\it argc} is the number of arguments of your programme
  \item {\it argv} is the argument list
  \item {\it gaaval} is a pointer to a {\it gaainfo} instance. It will be
filled by the analyser. The gaainfo structure is defined in the
GAA language file. The structure pointed by gaaval is the result
of the analysis.
  \item {\it return value}: -1 if success
 \end{itemize}
 \item {\bf void gaa\_help()} shows the help of your programme. This help is
generated by GAA, according to your instructions
\end{enumerate}

\section{How to declare the members of the gaainfo structure}

Anywhere, between two instructions, you write after a '\#' a structure-member
declaration exactly like in C: 
\par
example: 
\begin{verbatim}
#int number;
\end{verbatim}

You can add to your gaa file as much declarations as you like.

\section{ How to declare options}
Option declaration general syntax:
\par
for argless options:

\begin{verbatim}
option (short_name, long_name) { action } "option help"
\end{verbatim}

\par
for options with one argument

\begin{verbatim}
option (short_name, long_name) ARG_TYPE "arg help" { action } "option help"
\end{verbatim}

{\bf Note}: short\_name must be a single character \\
When gaa() finds an argument begining with '-', it considers that this
argument is an option. If an option with the same name has been declared,
there are two possibilities:

\begin{enumerate}
\item the option doesn't need any argument
 gaa() executes the assiociated {\it action}. In
this action, you can refer to a data contained in gaaval : you only have
to put a '\$' character before the name of the variable.
example : if you have declared '\#char pom', to refer
to 'pom' in an action, you must write '\$pom'; otherwise, if you write 'pom',
it will be considered as a general variable named 'pom'.
\item the option requires an argument
gaa() checks if the next argument has the right
type, and calculates its value. Then, it executes the action associated
with the option in the same way as if there was no argument. In the action,
'\$1' represents the value of the argument.

\end{enumerate}
{\bf Note}:
\begin{itemize}
\item predefined ARG\_TYPEs exist (cf. Quick Reference)

\item the type of the argument value depends on the choosen ARG\_TYPE. For instance,
type for 'INT' is 'int'
\end{itemize}

\par
For most programmes, the user must provide a filename
(for instance) without an option. This is supported by GAA with the 'rest'
instruction :
\begin{verbatim}
rest ARG_TYPE { action }
\end{verbatim}

\section{ Description of our sample progamme}
Our sample does nothing: he only analyses his arguments and shows
the selected options and parameters. \\
Typical call of the sample : {\bf sample file}

\par
Sample's options:
\begin{itemize}
\item {\bf -v} or {\bf --verbose }: activate verbose mode ({\it default value: off})

\item {\bf -n} or {\bf --num integer} : specifies an integer as parameter of
the programme ({\it default value : 0})

\item {\bf -f} or {\bf --file file1 file2 ... filex} : specifies a list of
files

\item {\bf -h} or {\bf --help} : shows the help of the sample
\end{itemize}

\section{The '{\it sample.gaa'} file}
GAA generates the help of your programme. You can make him write something
in the help with the instruction {\it helpnode}. So, we begin sample.gaa
by the line:

\begin{verbatim}
helpnode "SAMPLE help\nUsage : sample [options] file_name"
\end{verbatim}

When GAA generates the help, it follows the order in the gaa file.
So, this line will be the first of the help.

\par
Let's declare the sample's options
\begin{itemize}
\item Verbose
\end{itemize}

First, we should declare the gaainfo member that will store the state
of the option, 'verbose'.

\begin{verbatim}
#int verbose;
\end{verbatim}
then we must declare the option itself

\begin{verbatim}
option (v, verbose) { $verbose = 1 } "verbose mode on"
\end{verbatim}

GAA changes '\$verbose' into the 'verbose'
member of gaaval. When GAA returns, gaaval->verbose will be equal to 1.

\begin{itemize}
\item Num
\end{itemize}

First, we should declare the gaainfo member that will store the number
specified by the user. Let's name it 'n'.

\begin{verbatim}
#int n;
\end{verbatim}

then, the option:

\begin{verbatim}
option (n, num) INT "integer" { $n = $1 } "specifies the number of totoros"
\end{verbatim}

\begin{itemize}
\item File
\end{itemize}

This option needs a list of filenames as argument.
So we need two datas : the number of files and a list of filenames. For
that, we have the STR predefined type whose C-type is char*. To have a
list of STR, the ARG\_TYPE must be *STR. The C-type of *STR is of course
char**

\begin{verbatim}
#int size;
#char **input;
option (f, file) *STR "file1 file2...fileN" { $input = $1; $size = @1 } "specifies"
" the output files"
\end{verbatim}

'@1' is transformed by GAA into the number of filename
given by the user. Note : it's always '@1'

\begin{itemize}
\item Help
\end{itemize}

This option nust show the help and quit. So, let's
call gaa\_help()

\begin{verbatim}
option (h, help) { gaa_help(); exit(0); } "shows this help text"
\end{verbatim}
Sample must be called with a filename as argument. So
we must use the 'rest' instruction, and create a data that will store the
filename.

\begin{verbatim}
#char *file;
rest STR { $file = $1 }
\end{verbatim}

'rest' represents the argument(s) which remain when
you remove all the options (with their private argument(s)) from the line
given by the user.

\par For example, in the command 'tar -xv zorglub.gif -f toto.tar kiem.jpg bobby.c', 
the arguments managed by rest are zorglub.gif,
kiem.jpg and bobby.c. In this case, if the GAA file specifies 'rest STR
{...}', an error will occur, because the program wants {\bf one} rest
argument only. If the GAA files specifies 'rest *STR', it's OK, because
it means that the program needs a list of arguments as rest.
Each {\it gaaval} data must be initialized. To
do that we use the 'init' instruction

\begin{verbatim}
init { $n = 0; $verbose = 0; $file = NULL; $size = 0 }
\end{verbatim}

\par That's all !

\subsection{sample.gaa}
Finally, here is the text of {\bf sample.gaa :}

\begin{verbatim}
helpnode "SAMPLE help\nUsage : sample [options] file_name"

#int verbose;
option (v, verbose) { $verbose = 1 } "verbose mode on"

#int n;
option (n, num) INT "integer" { $n = $1 } "specifies the number of" 
 "totoros"

#int size;
#char **input;
option (f, file) *STR "file1 file2...fileN" { $input = $1; $size = @1 } "specifies"
 " the output files"

option (h, help) { gaa_help(); exit(0); } "shows this help text"

#char *file;
rest STR { $file = $1 }

init { $n = 0; $verbose = 0; $file = NULL; $size = 0 }
\end{verbatim}

\subsection{The 'smain.c' the C program using GAA}
\begin{verbatim}
#include <stdio.h>
#include "gaa.h"

int main(int argc, char **argv)
{
gaainfo info;
int i, v;

 if((v = gaa(argc, argv, info)) != -1) 
 // calls GAA. The user gived bag args if it returns -1
 {
    return 0;
 }
 
 printf("n : %d\nfile : %s\nverbose : %d\n", info.n,
  info.file, info.verbose); // shows the given arguments

 if(info.size > 0)
 for(i = 0; i < info.size; i++)
   printf("%s\n", info.input[i]);

 return 0;
}

\end{verbatim}


\section{ How to compile the sample file}
\par 
Calling GAA:

\begin{verbatim}
$ gaa sample.gaa
\end{verbatim}

\par Calling GCC:

\begin{verbatim}
$ gcc sample_gaa.c smain.c -o sample
\end{verbatim}

\par Please read the GAA Reference \\
In the reference, you will find how to make an option
obligatory, or two (or more) options incompatible. You will learn how to
define your own argument types...

