NAME
ParseArgv - process command-line options
SYNOPSIS
#include <ParseArgv.h>
int
ParseArgv(argcPtr, argv, argTable, flags)
ARGUMENTS
int argcPtr (in/out) Pointer to number of arguments in
argv; gets modified to hold number of
unprocessed arguments that remain
after the call.
char **argv (in/out) Command line arguments passed to main
program. Modified to hold unprocessed
arguments that remain after the call.
ArgvInfo *argTable (in) Array of argument descriptors,
terminated by element with type
ARGV_END.
int flags (in) If non-zero, then it specifies one or
more flags that control the parsing of
arguments. Different flags may be
OR’ed together. The flags currently
defined are ARGV_DONT_SKIP_FIRST_ARG,
ARGV_NO_ABBREV, ARGV_NO_LEFTOVERS,
ARGV_NO_DEFAULTS and ARGV_NO_PRINT.
______________________________________________________________________________
DESCRIPTION
ParseArgv processes an array of command-line arguments according to a
table describing the kinds of arguments that are expected. Each of the
arguments in argv is processed in turn: if it matches one of the
entries in argTable, the argument is processed according to that entry
and discarded. The arguments that do not match anything in argTable
are copied down to the beginning of argv (retaining their original
order) and returned to the caller. At the end of the call ParseArgv
sets *argcPtr to hold the number of arguments that are left in argv,
and argv[*argcPtr] will hold the value NULL. Normally, ParseArgv
assumes that argv[0] is a command name, so it is treated like an
argument that doesn’t match argTable and returned to the caller;
however, if the ARGV_DONT_SKIP_FIRST_ARG bit is set in flags then
argv[0] will be processed just like the other elements of argv.
ParseArgv normally returns the value FALSE (0). If an error occurs
while parsing the arguments, then TRUE (1) is returned and ParseArgv
will print an error message on stderr. In the event of an error return,
*argvPtr will not have been modified, but argv could have been
partially modified. The possible causes of errors are explained below.
The argTable array specifies the kinds of arguments that are expected;
each of its entries has the following structure:
typedef struct {
char*key;
int type;
char*src;
char*dst;
char*help;
} ArgvInfo;
The key field is a string such as ‘‘-display’’ or ‘‘-bg’’ that is
compared with the values in argv. Type indicates how to process an
argument that matches key (more on this below). Src and dst are
additional values used in processing the argument. Their exact usage
depends on type, but typically src indicates a value and dst indicates
where to store the value. The char * declarations for src and dst are
placeholders: the actual types may be different. Lastly, help is a
string giving a brief description of this option; this string is
printed when users ask for help about command-line options.
When processing an argument in argv, ParseArgv compares the argument to
each of the key’s in argTable. ParseArgv selects the first specifier
whose key matches the argument exactly, if such a specifier exists.
Otherwise ParseArgv selects a specifier for which the argument is a
unique abbreviation. If the argument is a unique abbreviation for more
than one specifier, then an error is returned. If there is no matching
entry in argTable, then the argument is skipped and returned to the
caller.
Once a matching argument specifier is found, ParseArgv processes the
argument according to the type field of the specifier. The argument
that matched key is called ‘‘the matching argument’’ in the
descriptions below. As part of the processing, ParseArgv may also use
the next argument in argv after the matching argument, which is called
‘‘the following argument’’. The legal values for type, and the
processing that they cause, are as follows:
ARGV_END
Marks the end of the table. The last entry in argTable must
have this type; all of its other fields are ignored and it will
never match any arguments.
ARGV_CONSTANT
Src is treated as an integer and dst is treated as a pointer to
an integer. Src is stored at *dst. The matching argument is
discarded.
ARGV_INT
The following argument must contain an integer string in the
format accepted by strtol (e.g. ‘‘0’’ and ‘‘0x’’ prefixes may be
used to specify octal or hexadecimal numbers, respectively).
Dst is treated as a pointer to an integer; the following
argument is converted to an integer value and stored at *dst.
Src is treated as an integer count: if its value is greater than
1, then that many arguments are processed and Dst is treated as
an array pointer. The matching and following arguments are
discarded from argv.
ARGV_FLOAT
The following argument must contain a floating-point number in
the format accepted by strtol. Dst is treated as the address of
an double-precision floating point value; the following
argument is converted to a double-precision value and stored at
*dst. Src is treated as an integer count: if its value is
greater than 1, then that many arguments are processed and Dst
is treated as an array pointer. The matching and following
arguments are discarded from argv.
ARGV_STRING
In this form, dst is treated as a pointer to a (char *);
ParseArgv stores at *dst a pointer to the following argument,
and discards the matching and following arguments from argv.
Src is treated as an integer count: if its value is greater than
1, then that many arguments are processed and Dst is treated as
an array pointer.
ARGV_HELP
When this kind of option is encountered, ParseArgv uses the help
fields of argTable to format a message describing all the valid
arguments. The message is written on stderr and ParseArgv
returns TRUE. When this happens, the caller normally aborts.
If the key field of a ARGV_HELP specifier is NULL, then the
specifier will never match any arguments; in this case the
specifier simply provides extra documentation, which will be
included when some other ARGV_HELP entry causes help information
to be returned.
ARGV_REST
This option is used by programs or commands that allow the last
several of their options to be the name and/or options for some
other program. If a ARGV_REST argument is found, then ParseArgv
doesn’t process any of the remaining arguments; it returns them
all at the beginning of argv (along with any other unprocessed
arguments). In addition, ParseArgv treats dst as the address of
an integer value, and stores at *dst the index of the first of
the ARGV_REST options in the returned argv. This allows the
program to distinguish the ARGV_REST options from other
unprocessed options that preceeded the ARGV_REST.
ARGV_FUNC
For this kind of argument, src is treated as the address of a
procedure, which is invoked to process the following argument.
The procedure should have the following structure:
int
func(dst, key, nextArg)
char *dst;
char *key;
char *nextArg;
{
}
The dst and key parameters will contain the corresponding fields
from the argTable entry, and nextArg will point to the following
argument from argv (or NULL if there aren’t any more arguments
left in argv). If func uses nextArg (so that ParseArgv should
discard it), then it should return 1. Otherwise it should
return 0 and TkParseArgv will process the following argument in
the normal fashion. In either event the matching argument is
discarded.
ARGV_GENFUNC
This form provides a more general procedural escape. It treats
src as the address of a procedure, and passes that procedure all
of the remaining arguments. The procedure should have the
following form:
int
genfunc(dst, key, argc, argv)
char *dst;
char *key;
int argc;
char **argv;
{
}
The dst and key parameters will contain the corresponding fields
from the argTable entry. Argc and argv refer to all of the
options after the matching one. Genfunc should behave in a
fashion similar to ParseArgv: parse as many of the remaining
arguments as it can, then return any that are left by compacting
them to the beginning of argv (starting at argv[0]). Genfunc
should return a count of how many arguments are left in argv;
ParseArgv will process them. If genfunc encounters an error
then it should print an error message on stderr, and return -1;
when this happens ParseArgv will abort its processing and return
TRUE.
FLAGS
ARGV_DONT_SKIP_FIRST_ARG
ParseArgv normally treats argv[0] as a program or command name,
and returns it to the caller just as if it hadn’t matched
argTable. If this flag is given, then argv[0] is not given
special treatment.
ARGV_NO_ABBREV
Normally, ParseArgv accepts unique abbreviations for key values
in argTable. If this flag is given then only exact matches will
be acceptable.
ARGV_NO_LEFTOVERS
Normally, ParseArgv returns unrecognized arguments to the
caller. If this bit is set in flags then ParseArgv will return
an error if it encounters any argument that doesn’t match
argTable. The only exception to this rule is argv[0], which
will be returned to the caller with no errors as long as
ARGV_DONT_SKIP_FIRST_ARG isn’t specified.
ARGV_NO_DEFAULTS
Normally, ParseArgv searches an internal table of standard
argument specifiers in addition to argTable. If this bit is set
in flags, then ParseArgv will use only argTable and not its
default table.
ARGV_NO_PRINT
Normally, ParseArgv prints error message on stderr. If this bit
is set in flags, then ParseArgv will not print any error
messages.
EXAMPLE
Here is an example definition of an argTable and some sample command
lines that use the options. Note the effect on argc and argv;
arguments processed by ParseArgv are eliminated from argv, and argc is
updated to reflect reduced number of arguments.
/*
* Define and set default values for globals.
*/
int debugFlag = 0;
int numReps = 100;
char defaultFileName[] = "out";
char *fileName = defaultFileName;
Boolean exec = FALSE;
/*
* Define option descriptions.
*/
ArgvInfo argTable[] = {
{"-X", ARGV_CONSTANT, (char *) 1, (char *) &debugFlag,
"Turn on debugging printfs"},
{"-N", ARGV_INT, (char *) NULL, (char *) &numReps,
"Number of repetitions"},
{"-of", ARGV_STRING, (char *) NULL, (char *) &fileName,
"Name of file for output"},
{"x", ARGV_REST, (char *) NULL, (char *) &exec,
"File to exec, followed by any arguments (must be last argument)."},
{(char *) NULL, ARGV_END, (char *) NULL, (char *) NULL,
(char *) NULL}
};
main(argc, argv)
int argc;
char *argv[];
{
...
if (ParseArgv(&argc, argv, argTable, 0)) {
exit(1);
}
/*
* Remainder of the program.
*/
}
Note that default values can be assigned to variables named in
argTable: the variables will only be overwritten if the particular
arguments are present in argv. Here are some example command lines and
their effects.
prog -N 200 infile # just sets the numReps variable to 200
prog -of out200 infile # sets fileName to reference "out200"
prog -XN 10 infile # sets the debug flag, also sets numReps
In all of the above examples, argc will be set by ParseArgv to 2,
argv[0] will be ‘‘prog’’, argv[1] will be ‘‘infile’’, and argv[2] will
be NULL.
KEYWORDS
arguments, command line, options
ParseArgv(3)