ALL_OPT (3)
general purpose command-line options parsing (LAM)
SYNOPSIS
.75i 1.75i 2.5i
#include <all_opt.h>
OPT *ao_init (void);
char *ao_chosen (OPT *od, const char *opt);
char *ao_param (OPT *od, const char *opt,
int inst, int idx);
int ao_intparam (OPT *od, const char *opt,
int inst, int idx, int *inum);
int ao_ninsts (OPT *od, const char *opt);
int ao_nparams (OPT *od, const char *opt, int inst);
int ao_ntaken (OPT *od);
int ao_parse (OPT *od, int *argc, char **argv);
int ao_setopt (OPT *od, const char *opt,
const char *mutex, int nparams, int flags);
int ao_setopt1 (OPT *od, const char *opt,
const char *mutex, int nparams, int flags);
int ao_tail (OPT *od, int *tailc, char ***tailv);
int ao_taken (OPT *od, const char *opt);
void ao_free (OPT *od);
DESCRIPTION
The
all_opt
package provides
general purpose command-line option parsing.
It parses multi-letter option strings with varying numbers of
parameters and invocations.
Options can be made mandatory as well as grouped into mutually
exclusive sets.
all_opt
can handle multiple command-line parsing invocations by
maintaining a separate option descriptor for each one.
An option descriptor is created and initialized by the
ao_init()
function.
It returns a pointer to a new descriptor, typedef
OPT
(defined in <all_opt.h>).
This descriptor pointer is used as the first argument to all
the other functions.
When no longer needed, a descriptor can be destroyed by calling
ao_free() .
Once a descriptor is created, the user declares each valid
command-line option string by calling
ao_setopt() .
The function's arguments are:
ad ,
the option descriptor;
opt ,
the option string being declared;
mutex ,
an option string in the set of mutually exclusive options (or NULL
if not used);
nparams ,
the number of parameters expected to follow this option (or AOVARNUM
if variable); and
flags ,
a bit-mapped field of flags controlling other characteristics of
the option.
The
flags
value is constructed by ORing flags from the following list:
AOINT
All arguments following the option are integers.
AOMUST
The option is mandatory and must be taken.
If the option is part of a mutually exclusive set, all options
in the set must also have this flag set.
ao_setopt1()
is a convenience function that interprets the
opt
argument as a string of single letter options and calls
ao_setopt()
for each letter with the other arguments given.
The option string "#" is reserved to represent the special case of
the "-#" option (i.e. a dash followed by an integer).
The integer can be either decimal, octal, or hexadecimal.
This option implies that the
AOINT
flag is set and that the
nparams
argument is 1.
After all valid options are declared, the command-line arguments
are parsed by calling
ao_parse() .
The
argc
and
argv
parameters are those passed to main().
Note that
argc
is passed by reference.
Option strings in the command-line (prefixed with the dash character '-')
and any parameters following them, are parsed and deleted from the
argc ,
argv
structure, leaving in it any additional strings that are neither
options nor parameters.
Options can be invoked multiple times,
ao_parse()
maintains a count of these instances as well as potential parameters
for each option.
A "--" argument notifies
ao_parse()
to avoid processing the arguments that follow it.
These unprocessed arguments at the tail end of the command-line
can be retrieved by calling
ao_tail() .
ao_parse()
checks the command-line for invalid options and parameters, and
verifies that mutual exclusion is satisfied and mandatory options
are taken.
Once the command-line options are parsed, the user can make queries
to check which options were actually taken and what parameters were
supplied.
The function
ao_ntaken()
returns the number of options taken, i.e. that appeared on the command-line.
ao_taken()
checks if the given option
opt
was taken, returning 1 (true) or 0 (false).
The
ao_chosen()
function simplifies the task of locating the single option taken in
a mutually exclusive set.
The set is identified by setting
opt
to any of member options in it.
ao_chosen()
returns the option taken or NULL if none was chosen.
ao_ninsts()
returns the number of times (instances) an option was invoked
on the command-line.
This number can be helpful if an option accepts parameters.
It allows the user to request the different parameters of each instance.
Instances are numbered sequentially starting with 0.
If the option accepts a variable number of parameters,
ao_nparams()
returns the number of parameters provided for an option's given
instance number
inst .
Parameters are identified by sequential index values starting with 0.
If the option takes integer parameters,
ao_intparam()
can be used to retrieve a specific parameter given its instance number
inst
and its index value
idx .
The parameter is returned by reference in the
inum
variable.
If the option parameters are strings,
ao_param()
is used to return a specific parameter given its instance and index values.
The tail end of the command-line, formed by all arguments to the right
of the "--" special option, can be retrieved by calling
IR ao_tail() .
The tail is returned in the standard
argc ,
argv
format through the
tailc
and
tailv
parameters passed by reference.
EXAMPLE
The following example code demonstrates how
all_opt
can be used to parse command-lines.
The hypothetical tool accepts two mutually exclusive options: "foo", "bar".
The "foo" option requires 2 string parameters and can only be invoked once.
For simplicity, error checking is not done.
.75i 1.5i 2.25i 3i
#include <all_opt.h>
main(argc, argv)
int argc;
char *argv[];
{
OPT *ad;
char *opt;
ad = ao_init();
ao_setopt(ad, "foo", NULL, 2, 0);
ao_setopt(ad, "bar", "foo", 0, 0);
ao_parse(ad, &argc, argv);
opt = ao_chosen(ad, "foo");
if (strcmp(opt, "foo") == 0) {
if (ao_ninsts(ad, "foo") > 1) { /* error */ }
printf("foo chosen: %s %s\\n",
ao_param(ad, "foo", 0, 0),
ao_param(ad, "foo", 0, 1));
} else {
printf("bar taken %d times\\n",
ao_ninsts(ad, "bar"));
}
ao_free(ad);
}
RETURN VALUES
In case of an error,
ao_init()
returns a NULL descriptor,
ao_chosen()
and
ao_param()
return NULL strings,
and
ao_intparam() ,
ao_parse() ,
ao_setopt() ,
ao_setopt1() ,
and
ao_tail()
return -1.
In addition, the global variable
errno
is set to indicate the error.
ERRORS
EUSAGE
The command-line violates the option rules.
EBADASCIINUMB
A string representing an integer has an invalid format.
|