7.1 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 Option Definitions
section.
-
POSIX-compliant short (flag) option processing.
-
GNU-style long options processing. Long options
are recognized without case sensitivity, and they may be abbreviated.
-
Environment variable initializations, See section environment variable presets.
-
Initialization from configuration files (aka RC or INI files), and
saving the option state back into one, See section configuration file presets.
-
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 configuration file presets.
-
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
(see section Common Option Attributes).
-
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 See section Common Option Attributes, and See section Option Conflict Attributes.
-
There are several automatically supported options.
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.
-
Various forms of main procedures can be added to the output,
See section Generating main procedures. There are four basic forms:
-
A program that processes the arguments and writes to standard out
portable shell commands containing the digested options.
-
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.
-
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.
-
A main procedure of your own design. Its code can be supplied in the
option description template or by incorporating another template.
-
There are several methods for handling option arguments.
-
The generated usage text can be emitted in either AutoOpts standard
format (maximizing 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 Program Information Attributes).
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.
-
If you compile with
ENABLE_NLS
defined and _()
defined to
a localization function such as gettext(3GNU)
, then the option
processing code will be localizable (see section Internationalizing AutoOpts).
-
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.
-
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.
-
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 Program Description Attributes) attribute. When processing reaches a point
where optionProcess
(see section optionProcess) needs to be called
again, the current option can be set with RESTART_OPT(n)
(see section RESTART_OPT( n ) - Resume Option Processing) before calling optionProcess
.
See: See section Options for Library Code.
-
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.
-
library options. An AutoOpt-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 AutoOpt-ed Library for AutoOpt-ed Program)
for more details.
-
Insert the option processing state into Scheme-defined variables.
Thus, Guile based applications that are linked with private
main()
routines can take advantage of all of AutoOpts’ functionality.
This document was generated by Bruce Korb on November 18, 2010 using texi2html 1.82.