AutoOpts Features

AutoOpts supports option processing; option state saving; and program documentation with innumerable features. Here, we list a few obvious ones and some important ones, but the full list is really defined by all the attributes defined in the Section 7.5 [Option Definitions], page 90 section.

1. POSIX-compliant short (flag) option processing.

2. GNU-style long options processing. Long options are recognized without case sensitiv-ity, and they may be abbreviated.

3. Environment variable initializations, SeeSection 7.10.4 [environrc], page 153.

4. Initialization from configuration files (aka RC or INI files), and saving the option state back into one, SeeSection 7.10.1 [loading rcfile], page 147.

5. Config files may be partitioned. One config file may be used by several programs by partitioning it with lines containing, [PROGRAM_NAME] or <?program-name>, See Section 7.10.1 [loading rcfile], page 147.

6. Config files may contain AutoOpts directives. <?auto-options [[option-text]]>

may be used to set AutoOpts option processing options. Viz., GNU usage layout ver-sus AutoOpts conventional layout, and miver-suse-usage verver-sus no-miver-suse-usage, See Section 7.5.1.1 [usage attributes], page 91.

7. Options may be marked as dis-abled with a disablement prefix. Such options may default to either an enabled or a disabled state. You may also provide an enablement prefix, too, e.g., --allow-mumble and --prevent-mumble (seeSection 7.5.5.2 [Common Attributes], page 106).

8. Verify that required options are present between the minimum and maximum number of times on the command line. Verify that conflicting options do not appear together.

Verify that options requiring the presence of other options are, in fact, used in the presence of other options. See SeeSection 7.5.5.2 [Common Attributes], page 106, and SeeSection 7.5.5.4 [Option Conflict Attributes], page 108.

9. There are several Section 7.5.10 [automatic options], page 121. They will have short flags if any options have option flags and the flags are not suppressed. The associated flag may be altered or suppressed by specifying no value or an alternate character for xxx-value; in the option definition file. xxx is the name of the option below:

‘--help’

‘--more-help’

These are always available. ‘--more-help’ will pass the full usage text through a pager.

‘--usage’ This is added to the option list if usage-opt is specified. It yields the abbreviated usage to stdout.

‘--version’

This is added to the option list if version = xxx; is specified.

‘--load-opts’

‘--save-opts’

These are added to the option list if homerc is specified. Mostly. If, disable-save is specified, then --save-opts is disabled.

10. Various forms of main procedures can be added to the output, SeeSection 7.5.4 [Gen-erated main], page 100. There are four basic forms:

a. A program that processes the arguments and writes to standard out portable shell commands containing the digested options.

b. A program that will generate portable shell commands to parse the defined options.

The expectation is that this result will be copied into a shell script and used there.

c. A for-each main that will invoke a named function once for either each non-option argument on the command line or, if there are none, then once for each non-blank, non-comment input line read from stdin.

d. A main procedure of your own design. Its code can be supplied in the option description template or by incorporating another template.

11. There are several methods for handling option arguments.

• nothing (see Section 7.6.13 [OPT ARG], page 128) option argument strings are globally available.

• user supplied (seeSection 7.5.7 [Option Argument Handling], page 115)

• stack option arguments (seeSection 7.5.7 [Option Argument Handling], page 115)

• integer numbers (seeSection 7.5.6.2 [arg-type number], page 111)

• true or false valued (see Section 7.5.6.3 [arg-type boolean], page 111)

• enumerated list of names (seeSection 7.5.6.4 [arg-type keyword], page 112)

• an enumeration (membership) set (see Section 7.5.6.5 [arg-type set membership], page 112)

• a list of name/value pairs (option subopts) (see Section 7.5.6.6 [arg-type hierar-chy], page 113)

• a time duration or a specific time and date

• validated file name (seeSection 7.5.6.7 [arg-type file name], page 113)

• optional option argument (seeSection 7.5.6.11 [arg-optional], page 115)

12. The generated usage text can be emitted in either AutoOpts standard format (max-imizing the information about each option), or GNU-ish normal form. The default form is selected by either specifying or not specifying the gnu-usage attribute (see Section 7.5.3 [information attributes], page 98). This can be overridden by the user himself with the AUTOOPTS_USAGE environment variable. If it exists and is set to the string ‘gnu’, it will force GNU-ish style format; if it is set to the string ‘autoopts’, it will force AutoOpts standard format; otherwise, it will have no effect.

13. The usage text and many other strings are stored in a single character array (see Section 3.5.56 [SCM string-table-new], page 52). This reduces fixup costs when loading the program or library. The downside is that if GCC detects that any of these strings are used in a printf format, you may get the warning, embedded ’\0’ in format. To eliminate the warning, you must provide GCC with the -Wno-format-contains-nul option.

14. If you compile with ENABLE_NLS defined and _() defined to a localization function (e.g.

gettext(3GNU)), then the option processing code will be localizable (see Section 7.16 [i18n], page 180). Provided also that you do not define the no-xlate attribute to anything (see Section 7.5.1.4 [presentation attributes], page 96).

You should also ensure that the ATTRIBUTE_FORMAT_ARG() gets #define-ed to some-thing useful. There is an autoconf macro named AG_COMPILE_FORMAT_ARG in ag_

macros.m4 that will set it appropriately for you. If you do not do this, then translated formatting strings may trigger GCC compiler warnings.

15. Provides a callable routine to parse a text string as if it were from one of the rc/ini/config files, hereafter referred to as a configuration file.

16. By adding a ‘doc’ and ‘arg-name’ attributes to each option, AutoGen will also be able to produce a man page and the ‘invoking’ section of a texinfo document.

17. Intermingled option processing. AutoOpts options may be intermingled with command line operands and options processed with other parsing techniques. This is accomplished by setting the allow-errors (see Section 7.5.1 [program attributes], page 90) attribute. When processing reaches a point where optionProcess (see Section 7.6.32.14 [libopts-optionProcess], page 139) needs to be called again, the current option can be set with RESTART_OPT(n) (seeSection 7.6.19 [RESTART OPT], page 129) before calling optionProcess.

See: See Section 7.5.2 [library attributes], page 97.

18. Library suppliers can specify command line options that their client programs will accept. They specify option definitions that get #include-d into the client option

definitions and they specify an "anchor" option that has a callback and must be invoked.

That will give the library access to the option state for their options.

19. library options. An ed library may export its options for use in an AutoOpt-ed program. This is done by providing an option definition file that client programs

#include into their own option definitions. See “AutoOpt-ed Library for AutoOpt-ed Program” (see Section 7.5.2.1 [lib and program], page 97) for more details.