AutoGen: Option Arguments

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

#### 7.3.4.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 five. 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.

  ``set[-membership]'`
    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.

``keyword'`
  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.

``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. If left empty, arg-default or the zero-valued keyword will be used.

``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 7.3.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-range`s 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`. When that argument is set `NULL`, you may wish to emit a line of usage information. Do something like this:

          if (pOptDesc == NULL) {
              fprintf( option_usage_fp, "\t\t\t  something\n" );
              return;
          }

  Note the `option_usage_fp`. Usage text is sometimes redirected to pipes or stdout in addition to stderr. If your validation fails, you should set `option_usage_fp` to `stderr`. See the function, `doOptTimeout()` in ``autogen/agen5/opts.c'` for a complete example.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Bruce Korb on October 24, 2004 using texi2html