Next: Library of Standard Options, Previous: Man and Info doc Attributes, Up: Option Definitions [Contents][Index]
AutoOpts provides automated support for several options. help
and
more-help
are always provided. The others are conditional upon
various global program attributes being defined See Program Description Attributes.
Below are the option names and default flag values. The flags are activated
if and only if at least one user-defined option also uses a flag value. The
long names are supported as option names if long-opts
has been
specified. These option flags may be deleted or changed to characters of your
choosing by specifying
xxx-value = "y";
, where xxx
is one of the option names below and
y
is either empty or the character of your choice. For example, to
change the help flag from ?
to h
, specify
help-value = "h";
; and to require that save-opts
be specified
only with its long option name, specify
save-opts-value = "";
.
Additionally, the procedure that prints out the program version may be
replaced by specifying version-proc
.
This procedure must be defined to be of external scope (non-static).
By default, the AutoOpts library provides optionPrintVersion
and it will be the specified callback function in the option
definition structure.
With the exception of the load-opts
option, none of these automatically
supported options will be recognized in configuration files or environment
variables.
This option will immediately invoke the USAGE()
procedure
and display the usage line, a description of each option with
its description and option usage information. This is followed
by the contents of the definition of the detail
text macro.
This option is identical to the help
option, except that the
output is passed through a pager program. (more
by default, or
the program identified by the PAGER
environment variable.)
This option must be requested by specifying, usage-opt
in the option
definition file. It will produce abbreviated help text to stdout and
exit with zero status (EXIT_SUCCESS
).
This will print the program name, title and version. If it is not
followed by anything or is followed by the letter v
, just the
program name and version will be printed. If followed by the letter
c
and a value for copyright
and owner
have been
provided, then the copyright will be printed, too. If it is followed by
the letter n
, then the full copyright notice (if available) will
be printed. The version
attribute must be specified in the
option definition file.
Because some target platforms discourage optional arguments to options,
the autoopts library can be compiled with NO_OPTIONAL_OPT_ARGS
defined. Alternatively, the version-type
attribute can be added
to the option definitions and it can specify which flavor is preferred.
In either case, an argument to the --version
option will then be
disallowed.
This option will load options from the named file. They will be treated exactly as if they were loaded from the normally found configuration files, but will not be loaded until the option is actually processed. This can also be used within another configuration file, causing them to nest. This is the only automatically supported option that can be activated inside of config files or with environment variables.
Specifying the negated form of the option (--no-load-opts) will suppress the processing of configuration files and environment variables.
This option is activated by specifying one or more homerc
attributes.
This option will cause the option state to be printed in the configuration file format when option processing is done but not yet verified for consistency. The program will terminate successfully without running when this has completed. Note that for most shells you will have to quote or escape the flag character to restrict special meanings to the shell.
The output file will be the configuration file name (default or provided by
rcfile
) in the last directory named in a homerc
definition.
This option may be set from within your program by invoking the
"SET_OPT_SAVE_OPTS(filename)
" macro (see SET_OPT_name - Force an option to be set).
Invoking this macro will set the file name for saving the option processing
state, but the state will not actually be saved. You must call
optionSaveFile
to do that (see optionSaveFile).
CAVEAT: if, after invoking this macro, you call
optionProcess
, the option processing state will be saved to this file
and optionProcess
will not return. You may wish to invoke
CLEAR_OPT( SAVE_OPTS )
(see CLEAR_OPT( <NAME> ) - Clear Option Markings) beforehand if you do need
to reinvoke optionProcess
.
This option is activated by specifying one or more homerc
attributes.
The method of saving the state may be altered by specifying flags before the output file name. “Flags” are specified by placing a list of them before the file name and separating them from the name with one or two greater-than characters (“>”). There are three flags currently supported:
If an option has a default value (has not been set), then the default value is inserted as a comment.
Every option that can be processed from the configuration file will have a
comment that contains the usage string that gets printed with the --help
text
Instead of removing the old file and writing a new one, the output file is kept,
but any pre-existing segment labeled with <?program prog-name>
is removed.
The new program segment is placed at the end of the file. This flag is implied if
the flags are separated from the file name with doubled greater-than characters.
In other words, update,usage > file-name
and usage >> file-name
are identical.
This option takes the name of an option for the current program and resets its state such that it is set back to its original, compile-time initialized value. If the option state is subsequently stored (via --save-opts), the named option will not appear in that file.
This option is activated by specifying the resettable
attribute.
BEWARE: If the resettable
attribute is specified, all
option callbacks must look for the OPTST_RESET
bit in the
fOptState
field of the option descriptor. If set, the optCookie
and optArg
fields will be unchanged from their last setting. When the
callback returns, these fields will be set to their original values. If you
use this feature and you have allocated data hanging off of the cookie, you
need to deallocate it.
Next: Library of Standard Options, Previous: Man and Info doc Attributes, Up: Option Definitions [Contents][Index]