8.4.1 Program Description Attributes

The following global option definitions are used to define attributes of the entire program. 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.46 `string->c-name!' - map non-name chars to underscore).

`prog-title'

This attribute is required and may be any descriptive text.

`prog-desc and'

`opts-ptr'

These define global pointer variables that point to the program descriptor and the first option descriptor for a library option. This is intended for use by certain libraries that need command line and/or initialization file option processing. These definitions have no effect on the option template output, but are used for creating a library interface file. Normally, the first "option" for a library will be a documentation option that cannot be specified on the command line, but is marked as settable. The library client program will invoke the SET_OPTION macro which will invoke a handler function that will finally set these global variables.

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

`before-guile-boot'

If guile-main has been specified and if this is specified as well, then this code will be inserted into the actual main() procedure before gh_enter() is called.

`copyright'

The copyright is a structured value containing three to five values. If copyright is used, then the first three are required.

1. `date' - the list of applicable dates for the copyright.
2. `owner' - the name of the copyright holder.
3. `type' - specifies the type of distribution license. AutoOpts/AutoGen will automatically support the text of the GNU Public License (`GPL'), the GNU General Public License with Library extensions (`LGPL'), the Free BSD license (`BSD'), and a write-it-yourself copyright notice (`NOTE'). Only these values are recognized.
4. `text' - the text of the copyright notice. It is only needed if `type' is set to `NOTE'.
5. `author' - in case the author name is to appear in the documentation and is different from the copyright owner.
6. `eaddr' - email address of the author or copyright holder.

An example of this might be:

copyright = { date = "1992-2001"; owner = "Bruce Korb"; eaddr = '[email protected]'; type = GPL; };

`detail'

This string is added to the usage output when the HELP option is selected.

`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 8.4.2.2 Common Option Attributes.

`explain'

Gives additional information whenever the usage routine is invoked..

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

`guile-main'

Creates a guile-style main and inner-main procedures. The inner main procedure will call optionProcess() and will invoke any code specified by this attribute. If this attribute does not specify any code, then calls to the AutoOpts library procedure export_options_to_guile() and then scm_shell() will be inserted into inner_main().

`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

`preserve-case'

This attribute will not change anything except appearance. Normally, the option names are all documented in lower case. However, if you specify this attribute, then they will display in the case used in their specification. Command line options will still be matched without case sensitivity.

`rcsection'

If you have a collection of option descriptions that are intended to use the same RC/ini files, then you will likely want to partition that file. That will be possible by specifying this attribute with AutoOpts version 9.2 and later.

Every RC file will be considered partitioned by lines that commence with the square open bracket ([). All text before such a line is always processed. Once such a line is found, the upper-cased c-variable-syntax program name will be compared against the text following that bracket. If there is a match and the next character after that is a square close bracket (]), then the section is processed and the file closed. Otherwise, the section is ignored and a matching section is searched for.

For exampe, if the foo-bar options had a sectioned RC file, then a line containing [FOO_BAR] would be searched for.

`test-main'

Creates a test main procedure for testing option processing. The resulting program may also be used for several purposes.

1. If the text of test-main is short (3 or fewer characters), the generated main() will call putBourneShell. That routine will emit Bourne shell commands that can be eval-ed by a Bourne-derived shell to incorporate the digested options into the shell's environment, See section 8.8 AutoOpts for Shell Scripts. You would use it thus:

   eval `./programopts $@` if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi shift ${OPTION_CT}

2. If the text of test-main contains putShellParse, the program will generate portable Bourne shell commands that will parse the command line options. The expectation is that this result will be copied into a shell script and used there, See section 8.8 AutoOpts for Shell Scripts.

3. Any other text must be the name of a routine that you will write yourself. That routine will be called after processing the command line options and it will be passed the option processing descriptor pointer as its sole argument.

`usage'

Optionally names the usage procedure, if the library routine optionUsage() does not work for you. If you specify gnu_usage as the value of this attribute, for example, you will use a procedure by that name for displaying usage. Of course, you will need to provide that procedure.

`version'

Specifies the program version and activates the VERSION option.