misc_lib/getarg.c:198 int GAGetArgs(int va_alist, ...)
Format of CtrlStr format:
The control string passed to GAGetArgs controls the way argv (argc) are
parsed. Each entry in this string must have no spaces in it.
The First Entry is the name of the program which is usually ignored
except when GAPrintHowTo is called. All the other entries (except the
last one which will be discussed shortly) must have the following format:
1. One letter which sets the option letter (i.e. 'x' for option '-x').
2. '!' or '%' to determines if this option is really optional ('%') or
it must be provided by the user ('!').
3. '-' always.
4. Alpha numeric string, usually ignored, but used by GAPrintHowTo to
describe the meaning of this option.
5. Sequences that start with either '!' or '%'.
Again if '!' then this sequence must exists (only if its option flag
is given), and if '%' it is optional.
Each sequence will be followed by one or two characters which
defines the kind of the input:
5.1. d, x, o, u - integer is expected (decimal, hex, octal base or
unsigned).
5.2. D, X, O, U - long integer is expected (same as above).
5.3. f - float number is expected.
5.4. F - double number is expected.
5.5. s - string is expected.
5.6. *? - any number of '?' kind (d, x, o, u, D, X, O, U, f, F, s)
will match this one. If '?' is numeric, it scans until
none numeric input is given. If '?' is 's' then it scans
up to the next option or end of argv.
If the last parameter given in the CtrlStr, is not an option (i.e. the second char is not in ['!', '%'] and the third one is not '-'), all what remained from argv is hooked to it.
The variables passed to GAGetArgs (starting from 4th parameter) MUST
match the order of options in the CtrlStr.
For each option, an address of an integer must be passed. This integer
must initialized by 0. If that option is given in the command line, it
will be set to one. Otherwise, this integer will not be affected.
In addition, the sequences that might follow an option require the
following parameter(s) to be passed
1. d, x, o, u - pointer to an integer (int *).
2. D, X, O, U - pointer to a long (long *).
3. f - pointer to a float (float *).
4. F - pointer to a double (double *).
5. s - pointer to a char * (char **). NO pre-allocation is required.
6. *? - TWO variables are passed for each such wild character
request. The first variable is an address of an integer, and
it will return the number of parameters actually hooked to
this sequence. The second variable is a pointer to a pointer
to type ? (? **). It will return an address of a vector of
pointers of type ?, terminated with a NULL pointer.
NO pre-allocation is required.
These two variables behaves very much like the argv/argc
pair and are used the "trap" unused command line options.
Examples:
"Example1 i%-OneInteger!d s%-Strings!*s j%- k!-Float!f Files!*s"
Will match: Example1 -i 77 -s String1 String2 String3 -k 88.2 File1 File2
or match: Example1 -s String1 -k 88.3 -i 999 -j
but not: Example1 -i 77 78 (i expects one integer, k must be specified).
The option k must exists in the above example and if '-i' is prescribed
one integer argument must follow it.
In the first example, File1 & File2, will match Files in the control
string.
The order of the options in the command line is irrelevant.
A call to GAPrintHowTo with this CtrlStr will print to stderr:
Example1 [-i OneIngeter] [-s Strings...] [-j] -k Float Files...
The parameters below are stdarg style and in fact are expecting the following:
GAGetArgs(argc, argv, CtrlStr, ...);
1. argc, argv: The usual C interface from the main routine of the program.
2. CtrlStr: Defining the types/options to expect in the command line.
3. ...: list of addreses of variables to initialize according to
parsed command line.
va_alist: Do "man stdarg".