8.4.2.6 Option Argument Specification

Several attributes relate to the handling of arguments to options. Each may appear only once, except for the arg-range attribute. It may appear as often as may be needed.

`arg-type'

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 four. The bracketed part of the name is optional.

`str[ing]'

The argument may be any arbitrary string.

`num[ber]'

The argument must be a correctly formed integer, without any trailing U's or L's. If you specify your own callback validation routine, read the arg-range section below for some considerations. 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.

`bool[ean]'

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.

`key[word]'

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.

`keyword'

If the arg-type is keyword, then you must specify the list of keywords by a series of keyword entries. The interface file will contain an enumeration of <OPTN_NAME>_<KEYWORD> for each keyword entry.

`arg-optional'

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. Without such a specification, the default keyword will be the zero-valued keyword.

`arg-default'

This specifies the default value to be used when the option is not specified or preset.

`default'

If your program processes its arguments in named option mode (See "long-opts" in 8.4.1 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.

`arg-range'

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, ->.

The generated procedure imposes some constraints:

• A number by itself will match that one value.
• The high end of the range may not be INT_MIN, both for obvious reasons and because that value is used to indicate a single-valued match.
• An omitted lower value implies a lower bound of INT_MIN.
• An omitted upper value implies a upper bound of INT_MAX.
• The argument value is required. It may not be optional.

The usage procedure displays these ranges by calling the callback with the pOptDesc pointer set to NULL. Therefore, all callback procedures designed to handle options with numeric arguments must be prepared to handle a call with that pointer set NULL.