GNU AutoGen - The Automated Program Generator: 7.5.10 Automatically Supported Options

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

### 7.5.10 Automatically Supported Options

AutoOpts provides automated support for several options. `help` and `more-help` are always provided. The others are conditional upon various global program attributes being defined See section Program Description Attributes.

Below are the option names and default flag values. The flags are activated if and only if at least one user-defined option also uses a flag value. The long names are supported as option names if `long-opts` has been specified. These option flags may be deleted or changed to characters of your choosing by specifying `xxx-value = "y";`, where `xxx` is one of the option names below and `y` is either empty or the character of your choice. For example, to change the help flag from `?` to `h`, specify `help-value = "h";`; and to require that `save-opts` be specified only with its long option name, specify `save-opts-value = "";`.

With the exception of the `load-opts` option, none of these automatically supported options will be recognized in configuration files or environment variables.

‘`help -?`’

  This option will immediately invoke the `USAGE()` procedure and display the usage line, a description of each option with its description and option usage information. This is followed by the contents of the definition of the `detail` text macro.

‘`more-help -!`’

  This option is identical to the `help` option, except that the output is passed through a pager program. (`more` by default, or the program identified by the `PAGER` environment variable.)

‘`usage -u`’

  This option must be requested by specifying, `usage-opt` in the option definition file. It will produce abbreviated help text to ‘`stdout`’ and exit with zero status (`EXIT_SUCCESS`).

‘`version -v`’

  This will print the program name, title and version. If it is followed by the letter `c` and a value for `copyright` and `owner` have been provided, then the copyright will be printed, too. If it is followed by the letter `n`, then the full copyright notice (if available) will be printed. The `version` attribute must be specified in the option definition file.

‘`load-opts -<`’

  This option will load options from the named file. They will be treated exactly as if they were loaded from the normally found configuration files, but will not be loaded until the option is actually processed. This can also be used within another configuration file, causing them to nest. This is the only automatically supported option that can be activated inside of config files or with environment variables.

  Specifying the negated form of the option (`--no-load-opts`) will suppress the processing of configuration files and environment variables.

  This option is activated by specifying one or more `homerc` attributes.

‘`save-opts ->`’

  This option will cause the option state to be printed in the configuration file format when option processing is done but not yet verified for consistency. The program will terminate successfully without running when this has completed. Note that for most shells you will have to quote or escape the flag character to restrict special meanings to the shell.

  The output file will be the configuration file name (default or provided by `rcfile`) in the last directory named in a `homerc` definition.

  This option may be set from within your program by invoking the "`SET_OPT_SAVE_OPTS(filename)`" macro (see section SET_OPT_name - Force an option to be set). Invoking this macro will set the file name for saving the option processing state, but the state will not actually be saved. You must call `optionSaveFile` to do that (see section optionSaveFile). CAVEAT: if, after invoking this macro, you call `optionProcess`, the option processing state will be saved to this file and `optionProcess` will not return. You may wish to invoke `CLEAR_OPT( SAVE_OPTS )` (see section CLEAR_OPT( <NAME> ) - Clear Option Markings) beforehand if you do need to reinvoke `optionProcess`.

  This option is activated by specifying one or more `homerc` attributes.

‘`reset-option -R`’

  This option takes the name of an option for the current program and resets its state such that it is set back to its original, compile-time initialized value. If the option state is subsequently stored (via `--save-opts`), the named option will not appear in that file.

  This option is activated by specifying the `resettable` attribute.

  BEWARE: If the `resettable` attribute is specified, all option callbacks must look for the `OPTST_RESET` bit in the `fOptState` field of the option descriptor. If set, the `optCookie` and `optArg` fields will be unchanged from their last setting. When the callback returns, these fields will be set to their original values. If you use this feature and you have allocated data hanging off of the cookie, you need to deallocate it.

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

This document was generated by Bruce Korb on March 7, 2011 using texi2html 1.82.