\chapter{Reference}

\section{GAA functions}
These functions are declared in the header file generated by GAA

\par int gaa(int argc, char *argv[], gaainfo *gaaval);
gaa() analyses arguments from the command line


 int gaa\_file(char *name, gaainfo *gaaval);
gaa\_file() analyses options from a configuration file

 void gaa\_help();
gaa\_help() prints the help of the program


\section{GAA file structure}

\begin{itemize}

\item The GAA-ng files consist of two parts:
\begin{enumerate}
 \item  (optional) C declarations that will be put at the begining of the
output. These declarations must be enclosed between '\#\{' and '\#\}'
brackets. 
 \item  GAA declarations
C file
\end{enumerate}

\item The traditional GAA file has the following format:
\begin{enumerate}
 \item  GAA declarations
 \item (optional) C declarations that will be put at the begining of the output
C file. This part is separated by the symbol '\#\#' .

\end{enumerate}
\end{itemize}

\section{GAA declarations}
 \begin{itemize}
  \item {\bf DATA data-name AS gaa-arg-type}
   Data declaration for the gaainfo structure.
   \underline{Example :}DATA a AS CHAR $\rightarrow$ 'a' can contain a character
   DATA textList AS *STR $\rightarrow$ 'textList' can contain a list of strings
   (C type : char**)
  \item {\bf \#C-variable-declaration} Data declaration for the gaainfo structure.
   \underline{Example} :
   {\it \#char a;}
  \item {\bf defitem ARGTYPE function-name \#C-ArgType}  Declaration of an user-defined named {\it ARGTYPE}.
    The {\it function-name} is the name of the function which will be called
    by gaa() to check if the argument is an {\it ARGTYPE} and to get its value.
    C-ArgType is the C type of {\it ARGTYPE}. The {\it function-name} function
   must declared (in the C-Declaration part) as follows :
    {\it C-ArgType function-name}(char*) \{ \}
    In this function, you must use the {\bf GAAERROR}
    macro when the argument is incorrect.
    \underline{Example} :
    defitem HEX findhex \#int
    \#\#
    int findhex(char*) \{...\}
  \item {\bf helpnode "help text"} Writes a line in the help.
  \item {\bf incomp shortnamelist} {\it  shortnamelist} is a list of options. This
    instruction makes the options in the list incompatibles.
    \underline{Example} :
    incomp vn $\rightarrow$ the option verbose and num (of the sample)
    become incompatible
  \item {\bf init \{ action \}}  Defines the intialization action. This action will
    be the first executed.
  \item {\bf obligat shortnamelist} {\it  shortnamelist} is a list of options. This
    instruction forces the user to give one option in of the list.
    \underline{Example} :
    obligat vn $\rightarrow$ the user must give the option verbose
    or/and the option num
  \item {\bf option (shortname, longname) $<$ARG\_DECL\_LIST$>$ \{
    action \} "option help"}
    An ARG\_DECL\_LIST is a list of argument declarations
    (surprising, isn't it ?)
     ARG\_DECL syntax : ARGTYPE
      or ARGTYPE "argument description"
     {\it \underline{Note}} : shortname 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\item  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.
          {\it \underline{example}} : if you have declared 'DATA pom AS CHAR' '\#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 one or more argument(s)  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,
	'\$n' represents the value of the nth argument.
     \end{enumerate}
 {bf Note}:
predefined ARGTYPEs exist (cf. Quick Reference)
the type of the argument value depends on the choosen ARGTYPE. For instance,
type for 'INT' is 'int' {\bf rest $<$ARG\_DECL\_LIST$>$ \{ action \}}  For most programs, the user must provide a filename
(for instance) without an option. This is supported by GAA with the 'rest'
instruction.
 '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.
 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
\ldots{}', an error will occur, because the program wants \underline{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.
\par  \underline{Example} :
 rest *STR \ldots{} $\rightarrow$ the rest is a list of name Predefined ARG\_TYPEs
{\bf ARG\_TYPE}{\bf C-type}{\bf Recognized arguments}STRchar*any argumentINTintintegersCHARcharsingle charactersFLOATfloatfloat number

{bf Important}: if in a declaration, you declare *ARG\_TYPE,
the user will have to give a list of ARG\_TYPE and not a single ARG\_TYPE.
In the attached action, you can get the number of found arguments with
the '@n' symbol.
\end{itemize}

\section{Configuration files}
GAA can analyse the content of a configuration file.
Syntax of a configuration file :
\par option-long-name arg1 arg2 arg3
...
option-long-name arg1 arg2 arg3

