7.3.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 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 3.5.47 `string->c-name!' - map non-name chars to underscore).

`prog-title'

This attribute is required and may be any descriptive text.

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

`argument'

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 argument 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.

`environrc'

Indicates looking in the environment for values of variables named, PROGRAM_OPTNAME, where PROGRAM is the upper cased C-name of the program and OPTNAME is the upper cased C-name of the option. The C-names are the regular names with all special characters converted to underscores (_).

If a particular option may be disabled, then its disabled state is indicated by setting the value to the disablement prefix. So, for example, if the disablement prefix were dont, then you can disable the optname option by setting the PROGRAM_OPTNAME' environment variable to `dont'. See section 7.3.4.2 Common Option Attributes.

`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, below.

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

`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 loading rc files.

`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).

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

`rcfile'

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

`version'

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