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