7.5.5.3 Special Option Handling

These option attributes do not fit well with other categories.

`no-preset'

If presetting this option is not allowed. (Thus, environment variables and values set in configuration files will be ignored.)

`settable'

If the option can be set outside of option processing. If this attribute is defined, special macros for setting this particular option will be inserted into the interface file. For example, TEMPL_DIRS is a settable option for AutoGen, so a macro named SET_OPT_TEMPL_DIRS(a) appears in the interface file. This attribute interacts with the documentation attribute.

`equivalence'

Generally, when several options are mutually exclusive and basically serve the purpose of selecting one of several processing modes, these options can be considered an equivalence class. Sometimes, it is just easier to deal with them as such. All members of the equivalence class must contain the same equivalenced-to option, including the equivalenced-to option itself. Thus, it must be a class member.

For an option equivalence class, there is a single occurrence counter for the class. It can be referenced with the interface macro, COUNT_OPT(BASE_OPTION), where "BASE_OPTION" is the equivalenced-to option name.

Also, please take careful note: since the options are mapped to the equivalenced-to option descriptor, any option argument values are mapped to that descriptor also. Be sure you know which "equivalent option" was selected before getting an option argument value!

During the presetting phase of option processing (see section Configuring your program), equivalenced options may be specified. However, if different equivalenced members are specified, only the last instance will be recognized and the others will be discarded. A conflict error is indicated only when multiple different members appear on the command line itself.

As an example of where equivalenced options might be useful, cpio(1) has three options -o, -i, and -p that define the operational mode of the program (create, extract and pass-through, respectively). They form an equivalence class from which one and only one member must appear on the command line. If cpio were an AutoOpt-ed program, then each of these option definitions would contain:

equivalence = create;

and the program would be able to determine the operating mode with code that worked something like this:

switch (WHICH_IDX_CREATE) { case INDEX_OPT_CREATE: ... case INDEX_OPT_EXTRACT: ... case INDEX_OPT_PASS_THROUGH: ... default: /* cannot happen */ }

`documentation'

This attribute means the option exists for the purpose of separating option description text in the usage output. Libraries may choose to make it settable so that the library can determine which command line option is the first one that pertains to the library.

If present, this option disables all other attributes except settable, call-proc and flag_-ode. settable must be and is only specified if call-proc, extract-code or flag-code has been specified. When present, the descrip attribute will be displayed only when the --help option has been specified. It will be displayed flush to the left hand margin and may consist of one or more lines of text. The name of the option will not be printed.

Documentation options are for clarifying the usage text and will not appear in generated man pages or in the generated invoking texinfo doc.

This document was generated by Bruce Korb on September, 30 2006 using texi2html 1.76.