getargs - command line processor for C programs

A command line switch is an argument preceded by a '-' that modifies
the way in which a program works.  This command line processor is a package of
subroutines.  Access to the routines is through one call to the procedure
getargs().  The routines are table driven.  Getargs() removes switches from the
command line as it works and leaves other arguments (the ones not preceded by
'-') alone.

When getargs() finds an error, it prints an error message to stderr listing all
the legal switches, descriptions of each, and their default values.  It
then terminates with exit(1), which should close any open files.

To use getargs() you must: (1) Set up a table to tell the routine what switches
to expect, (2) Declare the associated variables and initialize them to their
default values, and (3) call the routine itself somewhere early in the main()
routine.  The file getargs.h contains the #defines and typedefs needed to
create the command switch descriptor table.  This table is an array of
structures:

	typedef struct
	{	unsigned	arg			; /* command line switch */
		unsigned	type		; /* variable type (of those #defined above) */
		int			*variable	; /* pointer to variable */
		char		*errmsg		; /* pointer to error message */
	} ARG;

The arg field is a character that identifies the switch on the command line. 
In the following descriptions this character is represented by <switch>.  The
type field may take any one of five values, all #defined in getargs.h.

INTEGER switches take the form
	-<switch><number>
Numbers preceded by 0x are hex, by 0 without the x, octal.  All others are
decimal.  The number is terminated by any character not legal in the indicated
radix.  The int pointed to by the variable field of the ARG structure will be
set to the value of the <number>.  If the <number> isn't typed on the command
line, *variable is set to 0.

BOOLEAN switches will cause *variable to be set to 1 if present.  If the switch
is absent, *variable is not modified.

CHARACTER switches take the form
	-<switch><character>
When the switch is found on the command line, *variable is set to the character
immediately following the <switch> character.

STRING switches take the form
	-<switch><string>
When the switch is found on the command line, the character pointer pointed to
by the variable field is set to point at a string consisting of all characters
following (but not including) the <switch> character up to the end of the
current argument (not to the end of the command line).

PROC switches take the form
	-<switch><anything>
Here, the variable field is a pointer to a subroutine that is called indirectly
as soon as the switch is encountered on the command line.  A pointer to <anything>
is passed to this subroutine as a single argument.  It is the responsibility
of the called subroutine to parse <anything> as appropriate.

The errmsg field in the table is used to print an error message if an undefined
switch is found.

Switches may be combined into a single argument, but string switches must be
last one because all following characters will be considered part of the
<string>.  When defining a STRING switch in the table, be sure to cast the
variable into an integer pointer.  See argtest.c for an example.

EXAMPLES

Argtest is an example of how to use getargs().  Argtab is the table which
defines the legal switches.  Main() prints the command line before
and after calling getargs(), and prints the values of the associated
variables after the call.  Similarly, proc() displays its argument when called.

The following execution illustrates all five of the legal switches:

	A>argtest -b -pFISH alpha -shello_world -p&CHIPS -n0xff beta
	argc=8.  command line before processing: 
	    "argtest -b -pFISH alpha -shello_world -p&CHIPS -n0xff beta "

	procedure called as follows: proc("FISH") 
	procedure called as follows: proc("&CHIPS") 

	variable values after processing:
	    boolarg = TRUE 
	    chararg = & 
	    intarg  = 255 
	    strarg  = hello_world 

	argc=3.  command line after processing: 
	    "argtest alpha beta "

Arguments may be combined as follows:

	A>argtest alpha -bcYn98sapple_pie
	argc=3.  command line before processing: 
	    "argtest alpha -bcYn98sapple_pie "


	variable values after processing:
	    boolarg = TRUE 
	    chararg = Y 
	    intarg  = 98 
	    strarg  = apple_pie 

	argc=2.  command line after processing: 
	    "argtest alpha "

This execution illustrates the error message:

	A>argtest -y
	argc=2.  command line before processing: 
	    "argtest -y "

	Illegal argument 'y'.  Legal arguments are:

	-b      boolean argument                         (value is FALSE)
	-c<c>   character argument                       (value is &    )
	-n<num> integer argument                         (value is 0    )
	-s<str> string argument                          (value is "do wha")
	-p<str> procedure argument                      

This documentation is a condensation of the article by Allen Holub in Dr. 
Dobb's Journal #103 (May 1985).