GAA Manual
GAA Argument Analyzer


© Joran Maille 1998,1999
© Nikos Mavroyanopoulos 2002


Contents

Tutorial

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
two files are created by GAA: filename_gaa.h and filename_gaa.c

GAA's principle

GAA provides two functions:
  1. int gaa(int argc, char *argv[ ], gaa info *gaaval) calls the argument analyser
  2. 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:

  1. 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'.
  2. 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:

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:

The 'sample.gaa' file

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

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.

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"

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'

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 !

sample.gaa

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' the C program using GAA

#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;
}

How to compile the sample file

Calling GAA:

$ gaa sample.gaa

Calling GCC:

$ gcc sample_gaa.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...

Reference

GAA functions

These functions are declared in the header file generated by GAA

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

GAA file structure

GAA declarations

Configuration files

GAA can analyse the content of a configuration file. Syntax of a configuration file :

option-long-name arg1 arg2 arg3 ... option-long-name arg1 arg2 arg3



Nikos Mavroyanopoulos 2002-05-28