The Option Parsing Library
0.2.0
|
represents an element of an option description table. More...
#include <opt.h>
Data Fields | |
char * | lopt |
int | sopt |
int * | flag |
int | arg |
represents an element of an option description table.
opt_t
represents an element of an option description table that is used for a user program to specify options and their properties. A option description table is an array of opt_t
, each element of which is consisted of four members, two of which have overloaded meanings:
lopt:
long-named option that can be invoked by two precedeeing hypens; optional if a short-named option given; however, encouraged to always provide a long-named optionsopt:
short-named option that can be invoked by a precedeeing hypens; optional if both a long-named option and a flag variable providedflag:
if an option does not take an additional argument, flag
can point to an object (called "flag variable") that is set to the value of arg
when lopt
or sopt
option encountered; if an option can take an additional argument, flag
specifies whether the option-argument is mandatory (with OPT_ARG_REQ
) or optional (with OPT_ARG_OPT
)arg:
if an option does not take an additional argument, arg
has the value to be stored into a flag variable when lopt
or sopt
option encountered; if an option can take an additional argument, arg
specifies the type of the option-argument using OPT_TYPE_BOOL
(option-arguments starting with 't', 'T', 'y', 'Y' and '1' means true and others false, int), OPT_TYPE_INT
(signed integer, long), OPT_TYPE_UINT
(unsigned integer, unsigned long), OPT_TYPE_REAL
(floating-point number, double) and OPT_TYPE_STR
(string, char *)To mark an end of the table, the lopt
member of the last element has to be set to a null pointer. If the flag
member points to a flag variable, the pointed integer object is initalized to be 0 by opt_init().
For OPT_TYPE_INT
and OPT_TYPE_UINT
, the conversion of a given option-argument recognizes the C-style prefixes; numbers starting with 0 are treated as octal, and those with 0x or 0X are treated as hexadecimal.
Some examples follow:
opt_t options[] = { { "verbose", 'v', &option_verbose, 1 }, { "brief", 'b', &option_verbose, 0 }, { NULL, } };
This example says that two options ("--verbose" or "-v" and "--brief" or "-b") are recognized and option_verbose
is set to 1 when "--verbose" or "-v" given, and set to 0 when "--brief" or "-b" given.
opt_t options[] = { "version", 'v', OPT_ARG_NO, OPT_TYPE_NO, "help", UCHAR_MAX+1, OPT_ARG_NO, OPT_TYPE_NO, "morehelp", UCHAR_MAX+2, OPT_ARG_NO, OPT_TYPE_NO, NULL, };
This example shows options that do not take any additional arguments. Setting the flag
member to a null pointer also says the option takes no argument in which case the value of the arg
member ignored. Thus, the above example can be written as follows without any change on the behavior:
opt_t options[] = { "version", 'v', NULL, 0, "help", UCHAR_MAX+1, NULL, 0, "morehelp", UCHAR_MAX+2, NULL, 0, NULL, };
where you can put any integer in the place of 0. The former is preferred, however, since it shows more explicitly the fact that no additional arguments consumed after each of the options.
When only long-named options need to be provided without introducing flag variables, values from UCHAR_MAX+1
to INT_MAX
(inclusive) can be used for the sopt
member; both are defined in <limits.h>. (Even if the C standard does not require UCHAR_MAX
less than INT_MAX
, many parts of C, especially, of the standard library cannot work correctly without such a relationship on a hosted implementation.)
opt_t options[] = { "", 'x', OPT_ARG_NO, OPT_TYPE_NO, NULL, };
On the other hand, providing an empty string for the lopt
member as in this example can specify that an option is only short-named. Note that, however, this is discouraged; long-named options are much more user-friendly especially for novices.
opt_t options[] = { "input", 'i', OPT_ARG_REQ, OPT_TYPE_STR, "port", 'p', OPT_ARG_REQ, OPT_TYPE_UINT, "start", 's', OPT_ARG_REQ, OPT_TYPE_REAL, "end", 'e', OPT_ARG_REQ, OPT_TYPE_REAL, NULL, };
This example shows options that take additional arguments. OPT_ARG_REQ
for the flag
member specifies that the option requires an option-argument and that the type of the argument is given in the arg
member. For OPT_TYPE_INT
, OPT_TYPE_UINT
and OPT_TYPE_REAL
, strtol(), strtoul() and strtod() are respectively used to convert option-arguments.
opt_t options[] = { "negative", 'n', OPT_ARG_OPT, OPT_TYPE_REAL, NULL, };
This table specifies the option "--negative" or "-n" takes an optionally given argument. If an option-argument with the expected form (which is determined by strtod() in this case) follows the option, it is taken. If there is no argument, or is an argument but has no expected form, the option works as if OPT_ARG_OPT
and OPT_TYPE_REAL
are replaced by OPT_ARG_NO
and OPT_TYPE_NO
.
The following examples show how to control the ordering mode.
opt_t options[] = { "+", 0, OPT_ARG_NO, OPT_TYPE_NO, ... NULL, };
Setting the first long-named option to "+" or setting the environment variable named POSIXLY_CORRECT
says option processing performed by opt_parse() immediately stops whenever an operand encountered (which POSIX requires).
opt_t options[] = { "-", 0, OPT_ARG_NO, OPT_TYPE_NO, ... NULL, };
In addition, setting the first long-named option to "-" makes opt_parse() returns the character valued 1 when encounters an operand as if the operand is an option-argument for the option whose short name has the value 1.
int opt_t::arg |
value for flag variable or type of additional argument
int* opt_t::flag |
pointer to flag varible or information about additional argument
char* opt_t::lopt |
long-named option (optional for some cases)
int opt_t::sopt |
short-named option (optional for some cases)