Author: Maille Joran

GAA tutorial
GPL Argument Analyzer (c) Joran Maille 1998

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 !

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.

Typical GAA call :

gaa filename.gaa
2 files are created by GAA : gaa.h and gaaout.c

GAA's principle

GAA provides two functions :
int gaa(int argc, char *argv[ ], gaa info *gaaval) calls the argument analyser

argc is the number of arguments of your programme
argv is the argument list
gaaval is a pointer to a 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.
return value : -1 if success

void gaa_help() shows the help of your programme. This help is generated by GAA, according to your instructions

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 :
example :
#int number;
You can add to your gaa file as much declarations as you like.

How to declare options

Option declaration general syntax :

- for argless options :

option (short_name, long_name) { action } "option help"

- for options with one argument

option (short_name, long_name) ARG_TYPE "arg help" { action } "option help"

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 :

- the option doesn't need any argument
gaa() executes the assiociated 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'.
- 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.
Note :

- predefined ARG_TYPEs exist (cf. Quick Reference)
- the type of the argument value depends on the choosen ARG_TYPE. For instance, type for 'INT' is 'int'

For most programmes, the user must provide a filename (for instance) without an option. This is supported by GAA with the 'rest' instruction :

rest ARG_TYPE { action }

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 : sample file
Sample's options :

- -v or --verbose : activate verbose mode (default value : off)
- -n or --num integer : specifies an integer as parameter of the programme (default value : 0)
- -f or --file file1 file2 ... filex : specifies a list of files
- -h or --help : shows the help of the sample

The sample's GAA file : 'sample.gaa'

GAA generates the help of your programme. You can make him write something in the help with the instruction helpnode. So, we begin sample.gaa by the line :

helpnode "SAMPLE help\nUsage : sample [options] file_name"
When GAA generates the help, it follows the order in the gaa file. So, this line will be the first of the help.

Let's declare the sample's options

- Verbose

First, we should declare the gaainfo member that will store the state of the option, 'verbose'.
#int verbose;
then we must declare the option itself

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

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

- Num
First, we should declare the gaainfo member that will store the number specified by the user. Let's name it 'n'.
#int n;
then, the option :
option (n, num) INT "integer" { $n = $1 } "specifies the number of totoros"
- File
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**
#int size;
#char **input;
option (f, file) *STR "file1 file2...fileN" { $input = $1; $size = @1 } "specifies the output files"
'@1' is transformed by GAA into the number of filename given by the user. Note : it's always '@1'
- Help
This option nust show the help and quit. So, let's call gaa_help()
option (h, help) { gaa_help(); exit(0); } "shows this help text"

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.
#char *file;
rest STR { $file = $1 }
'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 {...}', an error will occur, because the program wants 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 gaaval data must be initialized. To do that we use the 'init' instruction
init { $n = 0; $verbose = 0; $file = NULL; $size = 0 }

That's all !

Finally, here is the text of sample.gaa :

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 }

The 'smain.c' file : the C program using GAA

#include <stdio.h>
#include "gaa.h"

int main(int argc, char **argv)
{
gaainfo info; // GAA output structure
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;
}

How to compile the sample

- Calling GAA :
gaa sample.gaa
- Calling GCC :
gcc gaaout.c smain.c -o sample

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...

If you have any question or remark please write me !
joran@writeme.com

to the official gaa page