AutoGen - The Automated Program Generator: 7.5.1 Program Description Attributes

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

### 7.5.1 Program Description Attributes

The following global definitions are used to define attributes of the entire program. These generally alter the configuration or global behavior of the AutoOpts option parser. The first two are required of every program. The third is required if there are to be any left over arguments (operands) after option processing. The rest have been alphabetized. Except as noted, there may be only one copy of each of these definitions:

‘`prog-name`’

  This attribute is required. Variable names derived from this name are derived using `string->c_name!` (see section ‘`string->c-name!`’ - map non-name chars to underscore).

‘`prog-title`’

  This attribute is required and may be any descriptive text.

‘`argument`’

  This attribute is required if your program uses operand arguments. It specifies the syntax of the arguments that follow the options. It may not be empty, but if it is not supplied, then option processing must consume all the arguments. If it is supplied and starts with an open bracket (`[`), then there is no requirement on the presence or absence of command line arguments following the options. Lastly, if it is supplied and does not start with an open bracket, then option processing must not consume all of the command line arguments.

‘`allow-errors`’

  The presence of this attribute indicates ignoring any command line option errors. This may also be turned on and off by invoking the macros `ERRSKIP_OPTERR` and `ERRSTOP_OPTERR` from the generated interface file.

‘`config-header`’

  The contents of this attribute should be just the name of the configuration file. A "#include" naming this file will be inserted at the top of the generated header.

‘`disable-load`’
‘`disable-save`’

  Indicates that the command line usage of `--load-opts` and/or `--save-opts` are disallowed.

‘`environrc`’

  Indicates looking in the environment for values of variables named, `PROGRAM_OPTNAME` or `PROGRAM`, where `PROGRAM` is the upper cased `C-name` of the program and `OPTNAME` is the upper cased `C-name` of a specific option.

‘`export`’

  This string is inserted into the .h interface file. Generally used for global variables or `#include` directives required by `flag-code` text and shared with other program text. Do not specify your configuration header (‘`config.h`’) in this attribute or the `include` attribute, however. Instead, use `config-header`, above.n.

‘`full-usage`’

  If this attribute is provided, it may specify the full length usage text, or a variable name assignable to a “char const *” pointer, or it may be empty. The meanings are determined by the length.

  - If not provided, the text will be computed as normal.
  - If the length is zero, then the usage text will be derived from the current settings and inserted as text into the generated .c file.
  - If the length is 1 to 32 bytes, then it is presumed to be a variable name that either points to or is an array of const chars.
  - If it is longer than that, it is presumed to be the help text itself. This text will be inserted into the generated .c file.

  This string should be readily translatable and provision will be made to translate it if this is provided and the source code is compiled with “ENABLE_NLS” defined.

‘`guard-option-names`’

  AutoOpts generates macros that presume that there are no `cpp` macros with the same name as the option name. For example, if you have an option named, `debug`, then you must not use `#ifdef DEBUG` in your code. If you specify this attribute, every option name will be guarded. If the name is `#define`-d, then a warning will be issued and the name undefined. If you do not specify this and there is a conflict, you will get strange error messages.

  This attribute may be set to any of four recognized states:

  - Not defined. AutoOpts will behave as described above.
  - Defined, but set to the empty string. Text will be emitted into the header to undefine (`#undef`) any conflicting preprocessor macros. The code will include compiler warnings (via `#warning`). Some compilers are not ANSI-C-99 compliant yet and will error out on those warnings. You may compile with `-DNO_OPTION_NAME_WARNINGS` to silence or mostly silence them.
  - Defined and set to the string, “`no-warning`”. All of the needed `#undef`s will be emitted, without any conflict checking `#warning` directives emitted.
  - Defined and set to the string, “`full-enum`”. The option manipulation preprocessor macros will not token paste the option names to the index enumeration prefix. e.g. you will need to use `HAVE_OPT(INDEX_OPT_DEBUG)` instead of `HAVE_OPT(DEBUG)`.
‘`homerc`’

  Specifies either a directory or a file using a specific path (like `.` or ‘`/usr/local/share/progname`’) or an environment variable (like ‘`$HOME/rc/`’ or ‘`$PREFIX/share/progname`’) or the directory where the executable was found (‘`$$[/...]`’) to use to try to find the rcfile. Use as many as you like. The presence of this attribute activates the `--save-opts` and `--load-opts` options. See section configuration file presets.

‘`include`’

  This string is inserted into the .c file. Generally used for global variables required only by `flag-code` program text.

‘`long-opts`’

  Presence indicates GNU-standard long option processing. If any options do not have an option value (flag character) specified, and least one does specify such a value, then you must specify `long-opts`. If none of your options specify an option value (flag character) and you do not specify `long-opts`, then command line arguments are processed in "named option mode". This means that:

  - Every command line argument must be a long option.
  - The flag markers `-` and `--` are completely optional.
  - The `argument` program attribute is disallowed.
  - One of the options may be specified as the default (as long as it has a required option argument).
‘`no-libopts`’

  If you are going to handle your option processing with the `getopt.tpl` template instead of using libopts, then specify this attribute. It will suppress mention of `--more-help` in the generated documentation.

‘`no-xlate`’

  Modifies when or whether option names get translated. If provided, it must be assigned one of two values:

  ‘`opt-cfg`’

    to suppress option name translation for configuration file and and environment variable processing.

  ‘`opt`’

    to suppress option name translation completely. The usage text will always be translated if `ENABLE_NLS` is defined and you have translations for that text.

  See also the various “`XLAT`” interface entries in the AutoOpts Programmatic Interface section (see section Programmatic Interface).

‘`prefix`’

  This value is inserted into all global names. This will disambiguate them if more than one set of options are to be compiled into a single program.

‘`prog-group`’

  The version text in the ‘`getopt.tpl`’ template will include this text in parentheses after the program name, when this attribute is specified. For example:

      mumble (stumble) 1.0

  says that the “`mumble`” program is version 1.0 and is part of the “`stumble`” group of programs.

‘`rcfile`’

  Specifies the configuration file name. This is only useful if you have provided at least one `homerc` attribute. default: .<prog-name>rc

‘`resettable`’

  Specifies that the `--reset-option` command line option is to be supported.

‘`short-usage`’

  If this attribute is provided, it is used to specify an abbreviated version of the usage text. This text is constructed in the same way as the “full-usage”, described above.

‘`version`’

  Specifies the program version and activates the VERSION option, See section Automatically Supported Options.

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

This document was generated by Bruce Korb on June 25, 2010 using texi2html 1.82.