7.5.7 Option Argument Handling

AutoOpts will either specify or automatically generate callback procedures for options that take specialized arguments. The only option argument types that are not specialized are plain string arguments and no argument at all. For options that fall into one of those two categories, you may specify your own callback function, as specified below. If you do this and if you specify that options are resettable (see section Automatically Supported Options), then your option handling code must look for the ‘OPTST_RESET’ bit in the fOptState field of the option descriptor.

If the option takes a string argument, then the stack-arg attribute can be used to specify that the option is to be handled by the libopts stackOptArg() and unstackOptArg() library procedures (see below). In this case, you may not provide option handling code.

Finally, ‘documentation’ options (see section Option Sectioning Comment) may also be marked as ‘settable’ (see section Program may set option) and have special callback functions (either ‘flag-code’, ‘extract-code’, or ‘call-proc’).

‘flag-code’

statements to execute when the option is encountered. This may be used in conjunction with option argument types that cause AutoOpts to emit handler code. If you do this, the ‘flag-code’ with index zero (0) is emitted into the handler code before the argument is handled, and the entry with index one (1) is handled afterward.

The generated procedure will be laid out something like this:

static void doOpt<name>(tOptions* pOptions, tOptDesc* pOptDesc) { <flag-code[0]> <AutoOpts defined handler code> <flag-code[1]> }

Only certain fields within the tOptions and tOptDesc structures may be accessed. See section Data for Option Processing. When writing this code, you must be very careful with the pOptions pointer. The handler code is called with this pointer set to special values for handling special situations. Your code must handle them. As an example, look at optionEnumerationVal in ‘enum.c’.

‘extract-code’

This is effectively identical to flag-code, except that the source is kept in the output file instead of the definitions file and you cannot use this in conjunction with options with arguments, other than string arguments.

A long comment is used to demarcate the code. You must not modify that marker. Before regenerating the option code file, the old file is renamed from MUMBLE.c to MUMBLE.c.save. The template will be looking there for the text to copy into the new output file.

‘call-proc’

external procedure to call when option is encountered. The calling sequence must conform to the sequence defined above for the generated procedure, doOpt<name>. It has the same restrictions regarding the fields within the structures passed in as arguments. See section Data for Option Processing.

‘flag-proc’

Name of another option whose flag-code can be executed when this option is encountered.

‘stack-arg’

Call a special library routine to stack the option’s arguments. Special macros in the interface file are provided for determining how many of the options were found (STACKCT_OPT(NAME)) and to obtain a pointer to a list of pointers to the argument values (STACKLST_OPT(NAME)). Obviously, for a stackable argument, the max attribute (see section Common Option Attributes) needs to be set higher than 1.

If this stacked argument option has a disablement prefix, then the entire stack of arguments will be cleared by specifying the option with that disablement prefix.

‘unstack-arg’

Call a special library routine to remove (unstack) strings from a stack-arg option stack. This attribute must name the option that is to be unstacked. Neither this option nor the stacked argument option it references may be equivalenced to another option.

This document was generated by Bruce Korb on August 21, 2015 using texi2html 1.82.