| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Command line options come in three flavors: options that do not take arguments, those that do and those that may. Without an "arg-type" attribute, AutoOpts will not process an argument to an option. If "arg-type" is specified and "arg-optional" is also specified, then the next command line token will be taken to be an argument, unless it looks like the name of another option.
If the argument type is specified to be anything other than "str[ing]", then
AutoOpts will specify a callback procedure to handle the argument. Some of
these procedures will be created and inserted into the generated .c
file, and others are already built into the `libopts' library.
Therefore, if you write your own callback procedure
(see section Option Argument Handling), then you must either not specify an
"arg-type" attribute, or else specify it to be of type "str[ing]". Your
callback function will be able to place its own restrictions on what that
string may contain or represent.
This specifies the type of argument the option will take. If not present, the option cannot take an argument. If present, it must be one of the following five. The bracketed part of each name is optional.
The argument may be any arbitrary string, though your program or option callback procedure may place additional constraints upon it.
The argument must be a correctly formed integer, without any trailing U's or
L's. AutoOpts contains a library procedure to convert the string to a
number. If you specify range checking with arg-range, then AutoOpts
produces a special purpose procedure for this option.
The argument will be interpreted and always yield either AG_TRUE or
AG_FALSE. False values are the empty string, the number zero, or a
string that starts with f, F, n or N
(representing False or No). Anything else will be interpreted as True.
The argument must match a specified list of strings.
Assuming you have named the option, optn-name,
the strings will be converted into an enumeration of type te_Optn_Name
with the values OPTN_NAME_KEYWORD. If you have not
specified a default value, the value OPTN_NAME_UNDEFINED will be
inserted with the value zero. The option will be initialized to that
value. You may now use this in your code as follows:
te_Optn_Name opt = OPT_VALUE_OPTN_NAME;
switch (opt) {
case OPTN_NAME_UNDEFINED: /* undefined things */ break;
case OPTN_NAME_KEYWORD: /* `keyword' things */ break;
default: /* utterly impossible */ ;
}
|
AutoOpts produces a special purpose procedure for this option.
If you have need for the string name of the selected keyword, you
may obtain this with the macro, OPT_OPTN_NAME_VAL2STR(val).
The value you pass would normally be OPT_VALUE_OPTN_NAME,
but anything with numeric value that is legal for te_Optn_Name
may be passed. Anything out of range will result in the string,
"*INVALID*" being returned. The strings are read only.
It may be used as in:
te_Optn_Name opt = OPT_VALUE_OPTN_NAME;
printf( "you selected the %s keyword\n",
OPT_OPTN_NAME_VAL2STR(opt) );
|
The argument must be a list of names each of which must match the
strings "all", "none" or one of the keywords specified
for this option. all will turn on all membership bits and
none will turn them all off. Specifying one of the keywords
will turn on the corresponding set membership bit. Literal numbers
may also be used and may, thereby, set or clear more than one bit.
Preceding a keyword or literal number with a bang (! -
exclamation point) will turn the bit(s) off. The number of keywords
allowed is constrained by the number of bits in a pointer, as the bit
set is kept in a void*.
If, for example, you specified first in your list of keywords,
then you can use the following code to test to see if either first
or all was specified:
uintptr_t opt = OPT_VALUE_OPTN_NAME;
if (opt & OPTN_NAME_FIRST)
/* OPTN_NAME_FIRST bit was set */ ;
|
AutoOpts produces a special purpose procedure for this option.
If the arg-type is keyword or set-membership,
then you must specify the list of keywords by a series of
keyword entries. The interface file will contain values for
<OPTN_NAME>_<KEYWORD> for each keyword entry.
keyword option types will have an enumeration and
set-membership option types will have a set of unsigned long bits
#define-d. If there are more than 32 bits defined, the #define
will set unsigned long long values and you best be running on a
64 bit platform.
This attribute indicates that the user does not have to supply an
argument for the option. This is only valid if the arg-type is
string or keyword. If it is keyword, then
this attribute may also specify the default keyword to assume when
the argument is not supplied. If left empty, arg-default or
the zero-valued keyword will be used.
This specifies the default value to be used when the option is not specified or preset.
If your program processes its arguments in named option mode (See
"long-opts" in Program Description Attributes), then you may select
one of your options to be the default option. Do so with this
attribute. The option so specified must have an arg-type
specified, but not the arg-optional attribute. That is to say,
the option argument must be required.
If you have done this, then any arguments that do not match an option
name and do not contain an equal sign (=) will be interpreted as
an option argument to the default option.
If the arg-type is number, then arg-ranges may be
specified, too. If you specify one or more of these option attributes,
then AutoOpts will create a callback procedure for handling it. The
argument value supplied for the option must match one of the range
entries. Each arg-range should consist of either an integer by itself
or an integer range. The integer range is specified by one or two
integers separated by the two character sequence, ->.
Be sure to quote the entire range string. The definitions parser will
not accept the range syntax as a single string token.
The generated procedure imposes the range constraints as follows:
INT_MIN, both for obvious
reasons and because that value is used to indicate a single-valued match.
| [ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This document was generated by Bruce Korb on September, 30 2006 using texi2html 1.76.