
1) Overview

The supergetopt library makes it very easy to handle all kinds
of command-line arguments in a printf() sort of way. All styles
of command-line args are supported and all arguments are checked
for type validity.

If you have been searching for an easy-to-use, flexible, portable
command-line and general-use parser, this is it!

Example:

int main( int argc, char *argv[] )
{
	long n;
	n = supergetopt( argc, argv, "-YourFlag:%f%s%d", yourFlagFunction, NULL );
	return(n);
}

will call yourFlagFunction( float *f, char *s, int *i ) with pointers to the
correct arguments.

It's that easy. No header files to create, no argument order to worry about.
Read the testSuperGet.c example and you'll understand.

2) Function usage:

There is only one function you need for argc/argv handling, and
that is supergetopt(). A number of functions exist in superString.c
to convert strings to argc/argv format so supergetopt() can be used
a a general parser. The make_args() function provides this support.

2.1: The supergetopt() function:

There is one function: supergetopt(), typically in main(),
which has the following syntax:

     supergetopt( int argc, char *argv[],
                  "flagA:[*][formatA]", functionToBeCalledA,
                  "flagB:[*][formatB]", functionToBeCalledB,
                  ...	/* arbitrarily long list of flag/function pairs */
                  NULL);

where "flagX" is an arbitrary keyword like "--help" or "+debug" or "display",
the "format" is a concatenation of printf()-like % formats, and
the optional '*' implies an arbitrarily long list of values
of the specified format are expected (see below). The corresponding function 
will be called only if the flag is on the commandline. In all cases,
the ":" is required as a separator.

NOTE!!! Supergetopt's string memory is not static,
so you must make a copy of the string if you wish to use it later
on in your program. The strdup() function is a good choice.

2.1.1: Fixed number of arguments to a flag

If '*' is not specified, the number arguments to a given flag
is the number of "%X"s in the format (fixed). The specified function will be
called with pointers to the arguments (not the arguments themselves).
In the special case of strings, which are already char pointers,
they will get passed as a 'char *' (not 'char **'). 


2.1.2: Arbitrary number of arguments to a given flag

If '*' is specified, then only one '%' may appear in the format.
In this case, your function will be called with 2 arguments, as in:

    yourFunction( type x[], int numArgs )

where "type" is one of char, int, long, short, float, double, char, char *.
Again, in the special case of strings, note that this means char *x[].

2.1.3: Flags without arguments

If the format is not specified, no arguments are expected to your
flag (e.g. "--help"), and your function will be called with no arguments to it.

2.1.4: Arguments without flags

If you wish to specify arguments without flags, just use an empty flag,
as in ":%f%d". This entry should be last on the list or arg pairs
to supergetopt() and only one can exist, for obvious reasons.

2.1.5) Flags without corresponding function calls

Sorry, every flag must have a corresponding function.

2.1.6) Return values

Supergetopt() return values are 0 (no problem with commandline)
or <0 (problem with commandline).


2.2: The make_args() function

To parse a string pointed to by "line",  allocate argv array 
and call the make_args() function as follows:

      make_args( line, argv );

The line will be separated into arguments with the following delimiters:
tab, spaces, equals sign, comma, semicolon. Then call supergetopt()
as follows:

      supergetopt( argc+1, argv-1 , ... )

If the line includes $ before a keyword, that keyword is taken to
be a shell variable and is expanded accordingly. This is very useful
for configuration files that need not contain hardcoded constants.

3) Portability:

This library conforms to ANSI C specs and should be completely portable.
It has been tested on Unix systems (Linux 2.0.x, SunOS, Solaris) and
Windows 3.1, Windows 95, and Windows NT 4.0.

4) History:

I've been using it for years! :}

SuperGetOpt-1.0: Release February 3, 1999.


5) Y2K Issues:

None known or expected.

6) BUGS:

None known. Please report bugs to the author (apr@planet.net).
The author appreciates useful feedback on this library.
