GNU/Linux man pages
Livre :
Expressions régulières,
Syntaxe et mise en oeuvre :
GNU/Linux |
RedHat 6.2(Zoot) |
|
 |
all_opt(3) |
 |
all_opt − general purpose command−line options parsing (LAM)
#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); |
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.
Option
Queries
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.
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.
#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); |
}
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.
|
EUSAGE |
The command−line violates the option rules. | ||
|
EBADASCIINUMB |
A string representing an integer has an invalid format. |
|
all_opt(3) | |