This is autogen.info, produced by makeinfo version 6.5 from
autogen.texi.
This manual is for GNU AutoGen version 5.18, updated August 2018.
Copyright (C) 1992-2018 by Bruce Korb.
Permission is granted to copy, distribute and/or modify this
document under the terms of the GNU Free Documentation License,
Version 1.2 or any later version published by the Free Software
Foundation; with no Invariant Sections, no Front-Cover Texts, and
no Back-Cover Texts.
INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* AutoGen: (autogen). The Automated Program Generator
END-INFO-DIR-ENTRY
This file documents GNU AutoGen Version 5.18.
AutoGen copyright (C) 1992-2018 Bruce Korb AutoOpts copyright (C)
1992-2018 Bruce Korb snprintfv copyright (C) 1999-2000 Gary V. Vaughan
AutoGen is free software: you can redistribute it and/or modify it
under the terms of the GNU General Public License as published by the
Free Software Foundation, either version 3 of the License, or (at your
option) any later version.
AutoGen is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
File: autogen.info, Node: Common Attributes, Next: Immediate Action, Prev: Required Attributes, Up: option attributes
7.5.5.2 Common Option Attributes
................................
These option attributes are optional. Any that do appear in the
definition of a flag, may appear only once.
'value'
The flag character to specify for traditional option flags, e.g.,
'-L'.
'max'
Maximum occurrence count (invalid if DISABLE present). The default
maximum is 1. 'NOLIMIT' can be used for the value, otherwise it
must be a number or a '#define' that evaluates to a number.
'min'
Minimum occurrence count. If present, then the option *must*
appear on the command line. Do not define it with the value zero
(0).
'must-set'
If an option must be specified, but it need not be specified on the
command line, then specify this attribute for the option.
'deprecated'
There are two effects to this attribute: the usage text will not
show the option, and the generated documentation will mark it with:
_NOTE: THIS OPTION IS DEPRECATED_.
'disable'
Prefix for disabling (inverting sense of) the option. Only useful
if long option names are being processed. When an option has this
attribute, the test 'ENABLED_OPT(OPTNAME)' is false when either of
the following is true:
* The option has not been specified and the 'enable' attribute
has not been specified.
* The option has been specified with this disabling prefix.
To detect that the option has been specified with the disabling
prefix, you must use:
HAVE_OPT(OPTNAME) && ! ENABLED_OPT(OPTNAME)
'enable'
Long-name prefix for enabling the option (invalid if DISABLE *not*
present). Only useful if long option names are being processed.
'enabled'
If default is for option being enabled. (Otherwise, the
OPTST_DISABLED bit is set at compile time.) Only useful if the
option can be disabled.
'ifdef'
'ifndef'
'omitted-usage'
If an option is relevant on certain platforms or when certain
features are enabled or disabled, you can specify the compile time
flag used to indicate when the option should be compiled in or out.
For example, if you have a configurable feature, 'mumble' that is
indicated with the compile time define, 'WITH_MUMBLING', then add:
ifdef = WITH_MUMBLING;
Take care when using these. There are several caveats:
* The case and spelling must match whatever is specified.
* Do not confuse these attributes with the AutoGen directives of
the same names, *Note Directives::. These cause C
preprocessing directives to be inserted into the generated C
text.
* Only one of 'ifdef' and 'ifndef' may apply to any one option.
* The 'VALUE_OPT_' values are '#define'-d. If 'WITH_MUMBLING'
is not defined, then the associated 'VALUE_OPT_' value will
not be '#define'-d either. So, if you have an option named,
'MUMBLING' that is active only if 'WITH_MUMBLING' is
'#define'-d, then 'VALUE_OPT_MUMBLING' will be '#define'-d iff
'WITH_MUMBLING' is '#define'-d. Watch those switch
statements.
* If you specify 'omitted-usage', then the option will be
recognized as disabled when it is configured out of the build,
but will yield the message, "This option has been disabled."
You may specify an alternate message by giving 'omitted-usage'
a string value. e.g.:
omitted-usage = 'you cannot do this';
'no-command'
This option specifies that the option is not allowed on the command
line. Such an option may not take a 'value' (flag character)
attribute. The program must have the 'homerc' (*note program
attributes::) option set.
File: autogen.info, Node: Immediate Action, Next: Option Conflict Attributes, Prev: Common Attributes, Up: option attributes
7.5.5.3 Immediate Action Attributes
...................................
Certain options may need to be processed early. For example, in order
to suppress the processing of configuration files, it is necessary to
process the command line option '--no-load-opts' *before* the config
files are processed. To accommodate this, certain options may have
their enabled or disabled forms marked for immediate processing. The
consequence of this is that they are processed ahead of all other
options in the reverse of normal order.
Normally, the first options processed are the options specified in
the first 'homerc' file, followed by then next 'homerc' file through to
the end of config file processing. Next, environment variables are
processed and finally, the command line options. The later options
override settings processed earlier. That actually gives them higher
priority. Command line immediate action options actually have the
lowest priority of all. They would be used only if they are to have an
effect on the processing of subsequent options.
'immediate'
Use this option attribute to specify that the enabled form of the
option is to be processed immediately. The 'help' and 'more-help'
options are so specified. They will also call 'exit()' upon
completion, so they *do* have an effect on the processing of the
remaining options :-).
'immed-disable'
Use this option attribute to specify that the disabled form of the
option is to be processed immediately. The 'load-opts' option is
so specified. The '--no-load-opts' command line option will
suppress the processing of config files and environment variables.
Contrariwise, the '--load-opts' command line option is processed
normally. That means that the options specified in that file will
be processed after all the 'homerc' files and, in fact, after
options that precede it on the command line.
'also'
If either the 'immediate' or the 'immed-disable' attributes are set
to the string, 'also', then the option will actually be processed
twice: first at the immediate processing phase and again at the
normal time.
File: autogen.info, Node: Option Conflict Attributes, Next: opt-attr settable, Prev: Immediate Action, Up: option attributes
7.5.5.4 Option Conflict Attributes
..................................
These attributes may be used as many times as you need. They are used
at the end of the option processing to verify that the context within
which each option is found does not conflict with the presence or
absence of other options.
This is not a complete cover of all possible conflicts and
requirements, but it simple to implement and covers the more common
situations.
'flags-must'
one entry for every option that *must* be present when this option
is present
'flags-cant'
one entry for every option that *cannot* be present when this
option is present
File: autogen.info, Node: opt-attr settable, Next: opt-attr no-preset, Prev: Option Conflict Attributes, Up: option attributes
7.5.5.5 Program may set option
..............................
If the option can be set outside of option processing, specify
'settable'. If this attribute is defined, special macros for setting
this particular option will be inserted into the interface file. For
example, 'TEMPL_DIRS' is a settable option for AutoGen, so a macro named
'SET_OPT_TEMPL_DIRS(a)' appears in the interface file. This attribute
interacts with the DOCUMENTATION attribute.
File: autogen.info, Node: opt-attr no-preset, Next: opt-attr equivalence, Prev: opt-attr settable, Up: option attributes
7.5.5.6 Option cannot be pre-configured
.......................................
If presetting this option is not allowed, specify 'no-preset'. (Thus,
environment variables and values set in configuration files will be
ignored.)
File: autogen.info, Node: opt-attr equivalence, Next: opt-attr aliases, Prev: opt-attr no-preset, Up: option attributes
7.5.5.7 Option Equivalence Class
................................
Generally, when several options are mutually exclusive and basically
serve the purpose of selecting one of several processing modes, specify
the 'equivalence' attribute. These options will be considered an
equivalence class. Sometimes, it is just easier to deal with them as
such. All members of the equivalence class must contain the same
equivalenced-to option, including the equivalenced-to option itself.
Thus, it must be a class member.
For an option equivalence class, there is a single occurrence counter
for the class. It can be referenced with the interface macro,
'COUNT_OPT(BASE_OPTION)', where BASE_OPTION is the equivalenced-to
option name.
Also, please take careful note: since the options are mapped to the
equivalenced-to option descriptor, any option argument values are mapped
to that descriptor also. Be sure you know which "equivalent option" was
selected before getting an option argument value!
During the presetting phase of option processing (*note Presetting
Options::), equivalenced options may be specified. However, if
different equivalenced members are specified, only the last instance
will be recognized and the others will be discarded. A conflict error
is indicated only when multiple different members appear on the command
line itself.
As an example of where equivalenced options might be useful,
'cpio(1)' has three options '-o', '-i', and '-p' that define the
operational mode of the program ('create', 'extract' and 'pass-through',
respectively). They form an equivalence class from which one and only
one member must appear on the command line. If 'cpio' were an
AutoOpt-ed program, then each of these option definitions would contain:
equivalence = create;
and the program would be able to determine the operating mode with
code that worked something like this:
switch (WHICH_IDX_CREATE) {
case INDEX_OPT_CREATE: ...
case INDEX_OPT_EXTRACT: ...
case INDEX_OPT_PASS_THROUGH: ...
default: /* cannot happen */
}
File: autogen.info, Node: opt-attr aliases, Next: opt-attr default option, Prev: opt-attr equivalence, Up: option attributes
7.5.5.8 Option Aliasing
.......................
Sometimes, for backwards compatibility or tradition or just plain
convenience, it works better to define one option as a pure alias for
another option. For such situations, provide the following pieces of
information:
flag = {
name = aliasing-option-name;
value = aliasing-flag-char; // optional !
aliases = aliased-to-option;
};
Do not provide anything else. The usage text for such an option will
be:
This is an alias for aliased-to-option
File: autogen.info, Node: opt-attr default option, Next: opt-attr documentation, Prev: opt-attr aliases, Up: option attributes
7.5.5.9 Default Option
......................
If your program processes its arguments in named option mode (See
'long-opts' in *note program attributes::), then you may select *one* of
your options to be the default option. Do so by using attribute
'default' with one of the options. The option so specified must have an
'arg-type' (*note Option Arguments::) specified, but not the
'arg-optional' (*note arg-optional::) attribute. That is to say, the
option argument must be required.
If you have done this, then any arguments that do not match an option
name and do not contain an equal sign ('=') will be interpreted as an
option argument to the default option.
File: autogen.info, Node: opt-attr documentation, Next: opt-attr translators, Prev: opt-attr default option, Up: option attributes
7.5.5.10 Option Sectioning Comment
..................................
This attribute means the option exists for the purpose of separating
option description text in the usage output and texi documentation.
Without this attribute, every option is a separate node in the texi
docs. With this attribute, the documentation options become texi doc
nodes and the options are collected under them. Choose the name
attribute carefully because it will appear in the texi documentation.
Libraries may also choose to make it settable so that the library can
determine which command line option is the first one that pertains to
the library.
If the 'documentation' attribute is present, then all other
attributes are disabled except 'settable', 'call-proc' and 'flag-code'.
'settable' must be and is only specified if 'call-proc', 'extract-code'
or 'flag-code' has been specified. When present, the 'descrip'
attribute will be displayed only when the '--help' option has been
specified. It will be displayed flush to the left hand margin and may
consist of one or more lines of text, filled to 72 columns.
The name of the option will not be printed in the help text. It
will, however, be printed as section headers in the texi documentation.
If the attribute is given a non-empty value, this text will be
reproduced in the man page and texi doc immediately after the 'descrip'
text.
File: autogen.info, Node: opt-attr translators, Prev: opt-attr documentation, Up: option attributes
7.5.5.11 Translator Notes
.........................
If you need to give the translators a special note about a particular
option, please use the 'translators' attribute. The attribute text will
be emitted into the generated '.c' text where the option related strings
get defined. To make a general comment about all of the option code,
add comments to an 'include' attribute (*note program attributes::). Do
*not* use this attribute globally, or it will get emitted into every
option definition block.
File: autogen.info, Node: Option Arguments, Next: Option Argument Handling, Prev: option attributes, Up: Option Definitions
7.5.6 Option Argument Specification
-----------------------------------
Command line options come in three flavors: options that do not take
arguments, those that do and those that may. Without an "arg-type"
attribute, AutoOpts will not process an argument to an option. If
"arg-type" is specified and "arg-optional" is also specified, then the
next command line token will be taken to be an argument, unless it looks
like the name of another option.
If the argument type is specified to be anything other than
"str[ing]", then AutoOpts will specify a callback procedure to handle
the argument. Some of these procedures will be created and inserted
into the generated '.c' file, and others are already built into the
'libopts' library. Therefore, if you write your own callback procedure
(*note Option Argument Handling::), then you must either not specify an
"arg-type" attribute, or else specify it to be of type "str[ing]". Your
callback function will be able to place its own restrictions on what
that string may contain or represent.
Option argument handling attributes depend upon the value set for the
'arg-type' attribute. It specifies the type of argument the option will
take. If not present, the option cannot take an argument. If present,
it must be an entry in the following table. The first three letters is
sufficient.
* Menu:
* arg-type string:: Arg Type String
* arg-type number:: Arg Type Number
* arg-type boolean:: Arg Type Boolean
* arg-type keyword:: Arg Type Keyword
* arg-type set membership:: Arg Type Set Membership
* arg-type hierarchy:: Arg Type Hierarchical
* arg-type file name:: Arg Type File Name
* arg-type time-duration:: Arg Type Time Duration
* arg-type time-date:: Arg Type Time and Date
Supporting attributes for particular argument types:
* arg-keyword:: Keyword list
* arg-optional:: Option Argument Optional
* arg-default:: Default Option Argument Value
File: autogen.info, Node: arg-type string, Next: arg-type number, Up: Option Arguments
7.5.6.1 Arg Type String
.......................
'arg-type = string;'
The argument may be any arbitrary string, though your program or
option callback procedure may place additional constraints upon it.
File: autogen.info, Node: arg-type number, Next: arg-type boolean, Prev: arg-type string, Up: Option Arguments
7.5.6.2 Arg Type Number
.......................
'arg-type = number;'
The argument must be a correctly formed integer, without any trailing
U's or L's. AutoOpts contains a library procedure to convert the string
to a number. If you specify range checking with 'arg-range' (see
below), then AutoOpts produces a special purpose procedure for this
option.
'scaled'
'scaled' marks the option so that suffixes of 'k', 'K', 'm', 'M',
'g', 'G', 't', and 'T' will multiply the given number by a power of
1000 or 1024. Lower case letters scale by a power of 1000 and
upper case scale by a power of 1024.
'arg-range'
'arg-range' is used to create a callback procedure for validating
the range of the option argument. It must match one of the range
entries. Each 'arg-range' should consist of either an integer by
itself or an integer range. The integer range is specified by one
or two integers separated by the two character sequence, '->'. Be
sure to quote the entire range string. The definitions parser will
not accept the range syntax as a single string token.
The generated procedure imposes the range constraints as follows:
* A number by itself will match that one value.
* The high end of the range may not be 'INT_MIN', both for
obvious reasons and because that value is used to indicate a
single-valued match.
* An omitted lower value implies a lower bound of INT_MIN.
* An omitted upper value implies a upper bound of INT_MAX.
* The argument value is required. It may not be optional.
* The value must match one of the entries. If it can match more
than one, then you have redundancies, but no harm will come of
it.
File: autogen.info, Node: arg-type boolean, Next: arg-type keyword, Prev: arg-type number, Up: Option Arguments
7.5.6.3 Arg Type Boolean
........................
'arg-type = boolean;'
The argument will be interpreted and always yield either AG_TRUE or
AG_FALSE. False values are the empty string, the number zero, or a
string that starts with 'f', 'F', 'n' or 'N' (representing False or No).
Anything else will be interpreted as True.
File: autogen.info, Node: arg-type keyword, Next: arg-type set membership, Prev: arg-type boolean, Up: Option Arguments
7.5.6.4 Arg Type Keyword
........................
'arg-type = keyword;'
The argument must match a specified list of strings (*note
arg-keyword::). Assuming you have named the option, 'optn-name', the
strings will be converted into an enumeration of type 'te_Optn_Name'
with the values 'OPTN_NAME_KEYWORD'.* If you have *not* specified a
default value, the value 'OPTN_NAME_UNDEFINED' will be inserted with the
value zero. The option will be initialized to that value. You may now
use this in your code as follows:
te_Optn_Name opt = OPT_VALUE_OPTN_NAME;
switch (opt) {
case OPTN_NAME_UNDEFINED: /* undefined things */ break;
case OPTN_NAME_KEYWORD: /* `keyword' things */ break;
default: /* utterly impossible */ ;
}
AutoOpts produces a special purpose procedure for this option. You
may not specify an alternate handling procedure.
If you have need for the string name of the selected keyword, you may
obtain this with the macro, 'OPT_OPTN_NAME_VAL2STR(val)'. The value you
pass would normally be 'OPT_VALUE_OPTN_NAME', but anything with numeric
value that is legal for 'te_Optn_Name' may be passed. Anything out of
range will result in the string, '"*INVALID*"' being returned. The
strings are read only. It may be used as in:
te_Optn_Name opt = OPT_VALUE_OPTN_NAME;
printf( "you selected the %s keyword\n",
OPT_OPTN_NAME_VAL2STR(opt) );
* Note: you may replace the 'OPTN_NAME' enumeration prefix with
another prefix by specifying a 'prefix-enum' attribute.
Finally, users may specify the argument either by name or by number.
Since the numeric equivalents change by having new entries inserted into
the keyword list, this would not be a recommended practice. However,
either '-1' or '~0' will always be equivalent to specifying the last
keyword.
File: autogen.info, Node: arg-type set membership, Next: arg-type hierarchy, Prev: arg-type keyword, Up: Option Arguments
7.5.6.5 Arg Type Set Membership
...............................
'arg-type = set;'
The argument must be a list of names each of which must match the
strings "'all'", "'none'" or one of the keywords (*note arg-keyword::)
specified for this option. 'all' will turn on all membership bits and
'none' will turn them all off. Specifying one of the keywords will set
the corresponding set membership bit on (or off, if negated) . Literal
numbers may also be used and may, thereby, set or clear more than one
bit.
The membership result starts with the previous (or initialized)
result. To clear previous results, either start the membership string
with 'none +' or with the equals character ('='). To invert (bit flip)
the final result (regardless of whether the previous result is carried
over or not), start the string with a carat character ('^'). If you
wish to invert the result and start without a carried over value, use
one of the following: '=^' or '^none+'. These are equivalent.
The list of names or numbers must be separated by one of the
following characters: '+-|!,' or whitespace. The comma is equivalent to
whitespace, except that only one may appear between two entries and it
may not appear in conjunction with the OR bar ('|'). The '+|' leading
characters or unadorned name signify adding the next named bit to the
mask, and the '-!' leading characters indicate removing it.
The number of keywords allowed is constrained by the number of bits
in a pointer, as the bit set is kept in a 'void *' pointer.
If, for example, you specified 'first' in your list of keywords, then
you can use the following code to test to see if either 'first' or 'all'
was specified:
uintptr_t opt = OPT_VALUE_OPTN_NAME;
if (opt & OPTN_NAME_FIRST)
/* OPTN_NAME_FIRST bit was set */ ;
AutoOpts produces a special purpose procedure for this option. To
set multiple bits as the default (initial) value, you must specify an
initial numeric value (which might become inaccurate over time), or else
specify 'arg-default' multiple times. Do not specify a series of names
conjoined with '+' symbols as the value for any of the 'arg-default'
attributes. That works for option parsing, but not for the option code
generation.
File: autogen.info, Node: arg-type hierarchy, Next: arg-type file name, Prev: arg-type set membership, Up: Option Arguments
7.5.6.6 Arg Type Hierarchical
.............................
'arg-type = hierarchy;'
'arg-type = nested;'
This denotes an option with a structure-valued argument, a.k.a.
'subopts' in 'getopts' terminology. The argument is parsed and the
values made available to the program via the find and find next calls
(*Note libopts-optionFindValue::, *Note libopts-optionGetValue::, and
*note libopts-optionFindNextValue::).
tOptionValue * val = optionGetValue(VALUE_OPT_OPTN_NAME, "name");
while (val != NULL) {
process(val);
val = optionNextValue(VALUE_OPT_OPTN_NAME, val);
if (wrong_name(val, "name"))
break;
}
File: autogen.info, Node: arg-type file name, Next: arg-type time-duration, Prev: arg-type hierarchy, Up: Option Arguments
7.5.6.7 Arg Type File Name
..........................
'arg-type = file;'
This argument type will have some validations on the argument and,
optionally, actually open the file. You must specify several additonal
attributes for the option:
'file-exists'
If not specified or empty, then the directory portion of the name
is checked. The directory must exist or the argument is rejected
and the usage procedure is invoked.
Otherwise, both the directory as above and the full name is tested
for existence. If the value begins with the two letters 'no', then
the file must not pre-exist. Otherwise, the file is expected to
exist.
'open-file'
If not specified or empty, the file is left alone. If the value
begins with the four letters 'desc'[riptor], then 'open(2)' is used
and 'optArg.argFd' is set. Otherwise, the file is opened with
'fopen' and 'optArg.argFp' is set.
'file-mode'
If 'open-file' is set and not empty, then you must specify the open
mode. Set the value to the flag bits or mode string as appropriate
for the open type.
File: autogen.info, Node: arg-type time-duration, Next: arg-type time-date, Prev: arg-type file name, Up: Option Arguments
7.5.6.8 Arg Type Time Duration
..............................
'arg-type = time-duration;'
The argument will be converted into a number of seconds. It may be a
multi-part number with different parts being multiplied into a seconds
value and added into the final result. Valid forms are in the table
below. Upper cased letters represent numbers that must be used in the
expressions.
'[[HH:]MM:]SS'
'HH' is multiplied by '3600' and 'MM' multiplied by '60' before
they are added to 'SS'. This time specification may not be
followed by any other time specs. 'HH' and 'MM' are both optional,
though 'HH' cannot be specified without 'MM'.
'DAYS d'
'DAYS' is multiplied by the number of seconds in a day. This value
may be followed by (and added to) values specified by 'HH:MM:SS' or
the suffixed values below. If present, it must always be first.
'HRS h'
'HRS' is multiplied by the number of seconds in an hour. This
value may be followed by (and added to) values specified by 'MM:SS'
or the suffixed values below.
'MINS m'
'MINS' is multiplied by the number of seconds in a minute. This
value may be followed by (and added to) a count of seconds.
'SECS s'
This value can only be the last value in a time specification. The
's' suffix is optional.
5 d 1:10:05 ==> 5 days + 1 hour 10 minutes and 5 seconds
5 d 1 h 10 m 5 ==> yields: 436205 seconds
5d1h10m5s ==> same result -- spaces are optional.
When saved into a config file, the value will be stored as a simple
count of seconds. There are actually more (many) accepted time duration
strings. The full documentation can be found with ISO-8601
documentation and the more extedded documentation when
'parse_duration()' becomes more widely available.
File: autogen.info, Node: arg-type time-date, Next: arg-keyword, Prev: arg-type time-duration, Up: Option Arguments
7.5.6.9 Arg Type Time and Date
..............................
'arg-type = time-date;'
The argument will be converted into the number of seconds since the
epoch. The conversion rules are very complicated, please see the
'getdate_r(3GNU)' man page. There are some additional restrictions:
1. Your project must be compiled with 'PKGDATADIR' defined and naming
a valid directory.
2. The 'DATEMSK' environment variable will be set to the 'datemsk'
file within that directory.
If that file is not accessible for any reason, the string will be
parsed as a time duration (*note arg-type time-duration::) instead of a
specific date and time.
File: autogen.info, Node: arg-keyword, Next: arg-optional, Prev: arg-type time-date, Up: Option Arguments
7.5.6.10 Keyword list
.....................
If the 'arg-type' is 'keyword' (*note arg-type keyword::) or
'set-membership' (*note arg-type set membership::), then you must
specify the list of keywords by a series of 'keyword' entries. The
interface file will contain values for '_' for each
keyword entry. 'keyword' option types will have an enumeration and
'set-membership' option types will have a set of unsigned bits
'#define'-d.
If the 'arg-type' is specifically 'keyword', you may also add special
handling code with a 'extra-code' attribute. After
'optionEnumerationVal' has converted the input string into an
enumeration, you may insert code to process this enumeration value
('pOptDesc->optArg.argEnum').
File: autogen.info, Node: arg-optional, Next: arg-default, Prev: arg-keyword, Up: Option Arguments
7.5.6.11 Option Argument Optional
.................................
The 'arg-optional' attribute indicates that the argument to the option
is optional (need not be specified on the command line). This is only
valid if the ARG-TYPE is 'string' (*note arg-type string::) or 'keyword'
(*note arg-type keyword::). If it is 'keyword', then this attribute may
also specify the default keyword to assume when the argument is not
supplied. If left empty, ARG-DEFAULT (*note arg-default::) or the
zero-valued keyword will be used.
The syntax rules for identifying the option argument are:
* If the option is specified with a flag character and there is a
character following the flag character, then string following that
flag character is the option argument.
* If the flag character is the last character in an argument, then
the first character of the next argument is examined. If it is a
hyphen, then the option is presumed to not have an argument.
Otherwise, the entire next argument is the argument for the option.
* If the option is specified with a long option name and that name is
ended with an equal sign character ('='), then everything after
that character is the option argument.
* If the long name is ended by the end of the argument, then the
first character of the next argument is examined, just as with the
flag character ending an argument string.
This is overridden and the options are required if the libopts
library gets configured with '--disable-optional-args'.
File: autogen.info, Node: arg-default, Prev: arg-optional, Up: Option Arguments
7.5.6.12 Default Option Argument Value
......................................
This specifies the default option argument value to be used when the
option is not specified or preset. You may specify multiple
'arg-default' values if the argument type is 'set membership'.
File: autogen.info, Node: Option Argument Handling, Next: Internationalizing Options, Prev: Option Arguments, Up: Option Definitions
7.5.7 Option Argument Handling
------------------------------
AutoOpts will either specify or automatically generate callback
procedures for options that take specialized arguments. The only option
argument types that are not specialized are plain string arguments and
no argument at all. For options that fall into one of those two
categories, you may specify your own callback function, as specified
below. If you do this and if you specify that options are resettable
(*note automatic options::), then your option handling code *must* look
for the 'OPTST_RESET' bit in the 'fOptState' field of the option
descriptor.
If the option takes a string argument, then the 'stack-arg' attribute
can be used to specify that the option is to be handled by the 'libopts'
'stackOptArg()' and 'unstackOptArg()' library procedures (see below).
In this case, you may not provide option handling code.
Finally, 'documentation' options (*note opt-attr documentation::) may
also be marked as 'settable' (*note opt-attr settable::) and have
special callback functions (either 'flag-code', 'extract-code', or
'call-proc').
'flag-code'
statements to execute when the option is encountered. This may be
used in conjunction with option argument types that cause AutoOpts
to emit handler code. If you do this, the 'flag-code' with index
zero (0) is emitted into the handler code _before_ the argument is
handled, and the entry with index one (1) is handled afterward.
The generated procedure will be laid out something like this:
static void
doOpt(tOptions* pOptions, tOptDesc* pOptDesc)
{
}
Only certain fields within the 'tOptions' and 'tOptDesc' structures
may be accessed. *Note Option Processing Data::. When writing
this code, you must be very careful with the 'pOptions' pointer.
The handler code is called with this pointer set to special values
for handling special situations. Your code must handle them. As
an example, look at 'optionEnumerationVal' in 'enum.c'.
'extract-code'
This is effectively identical to 'flag-code', except that the
source is kept in the output file instead of the definitions file
and you cannot use this in conjunction with options with arguments,
other than string arguments.
A long comment is used to demarcate the code. You must not modify
that marker. Before regenerating the option code file, the old
file is renamed from MUMBLE.c to MUMBLE.c.save. The template will
be looking there for the text to copy into the new output file.
'call-proc'
external procedure to call when option is encountered. The calling
sequence must conform to the sequence defined above for the
generated procedure, 'doOpt'. It has the same restrictions
regarding the fields within the structures passed in as arguments.
*Note Option Processing Data::.
'flag-proc'
Name of another option whose 'flag-code' can be executed when this
option is encountered.
'stack-arg'
Call a special library routine to stack the option's arguments.
Special macros in the interface file are provided for determining
how many of the options were found ('STACKCT_OPT(NAME)') and to
obtain a pointer to a list of pointers to the argument values
('STACKLST_OPT(NAME)'). Obviously, for a stackable argument, the
'max' attribute (*note Common Attributes::) needs to be set higher
than '1'.
If this stacked argument option has a disablement prefix, then the
entire stack of arguments will be cleared by specifying the option
with that disablement prefix.
'unstack-arg'
Call a special library routine to remove ('unstack') strings from a
'stack-arg' option stack. This attribute must name the option that
is to be 'unstacked'. Neither this option nor the stacked argument
option it references may be equivalenced to another option.
File: autogen.info, Node: Internationalizing Options, Next: documentation attributes, Prev: Option Argument Handling, Up: Option Definitions
7.5.8 Internationalizing Options
--------------------------------
Normally, AutoOpts produces usage text that is difficult to translate.
It is pieced together on the fly using words and phrases scattered
around here and there, piecing together toe document. This does not
translate well.
Incorporated into this package are some ways around the problem.
First, you should specify the 'full-usage' and 'short-usage' program
attributes (*note program attributes::). This will enable your
translators to translate the usage text as a whole.
Your translators will also be able to translate long option names.
The option name translations will then become the names searched for
both on the command line and in configuration files. However, it will
not affect the names of environment variable names used to configure
your program.
If it is considered desireable to keep configuration files in the 'C'
locale, then several macros are available to suppress or delay the
translations of option names at run time. These are all disabled if
'ENABLE_NLS' is not defined at compile time or if 'no-xlate' has been
set to the value _anything_. These macros *must* be invoked before the
first invocation of 'optionProcess'.
'OPT_NO_XLAT_CFG_NAMES;'
'OPT_XLAT_CFG_NAMES;'
Disable (or enable) the translations of option names for
configuration files. If you enable translation for config files,
then they will be translated for command line options.
'OPT_NO_XLAT_OPT_NAMES;'
'OPT_XLAT_OPT_NAMES;'
Disable (or enable) the translations of option names for command
line processing. If you disable the translation for command line
processing, you will also disable it for configuration file
processing. Once translated, the option names will remain
translated.
File: autogen.info, Node: documentation attributes, Next: automatic options, Prev: Internationalizing Options, Up: Option Definitions
7.5.9 Man and Info doc Attributes
---------------------------------
AutoOpts includes AutoGen templates for producing abbreviated man pages
and for producing the invoking section of an info document. To take
advantage of these templates, you must add several attributes to your
option definitions.
* Menu:
* per option attributes:: Per option documentation attributes
* global option attributes:: Global documentation attributes
File: autogen.info, Node: per option attributes, Next: global option attributes, Up: documentation attributes
7.5.9.1 Per option documentation attributes
...........................................
These attributes are sub-attributes (sub-stanzas) of the 'flag' stanzas.
'arg-name'
If an option has an argument, the argument should have a name for
documentation purposes. It will default to 'arg-type', but it will
likely be clearer with something else like, 'file-name' instead of
'string' (the type).
'doc'
First, every 'flag' definition _other than_ 'documentation'
definitions, must have a 'doc' attribute defined. If the option
takes an argument, then it will need an 'arg-name' attribute as
well. The 'doc' text should be in plain sentences with minimal
formatting. The Texinfo commands '@code', and '@var' will have its
enclosed text made into *\fB* entries in the man page, and the
'@file' text will be made into *\fI* entries. The 'arg-name'
attribute is used to display the option's argument in the man page.
Options marked with the 'documentation' attribute are for
documenting the usage text. All other options should have the
'doc' attribute in order to document the usage of the option in the
generated man pages.
Since these blocks of text are inserted into all output forms, any
markup text included in these blocks must be massaged for each
output format. By default, it is presumed to be 'texi' format.
File: autogen.info, Node: global option attributes, Prev: per option attributes, Up: documentation attributes
7.5.9.2 Global documentation attributes
.......................................
'cmd-section'
If your command is a game or a system management command, specify
this attribute with the value '5' or '8', respectively. The
default is a user command (section 1).
'detail'
This attribute is used to add a very short explanation about what a
program is used for when the 'title' attribute is insufficient. If
there is no 'doc-section' stanza of type 'DESCRIPTION', then this
text is used for the man page DESCRIPTION section, too.
'addtogroup'
This attribute tells the template that the generated code should be
surrounded with the following doxygen comments:
/** @file
* @addtogroup
* @{
*/
and
/** @} */
'option-format'
Specify the default markup style for the 'doc' stanzas. By
default, it is 'texi', but 'man' and 'mdoc' may also be selected.
There are nine converter programs that do a partial job of
converting one form of markup into another. 'texi2texi', 'man2man'
and 'mdoc2mdoc' work pretty well.
You may also post process the document by using 'doc-sub' stanzas,
see below.
'option-info'
This text will be inserted as a lead-in paragraph in the 'OPTIONS'
section of the generated man page.
'doc-section'
This is a compound attribute that requires three subattributes:
ds-format
This describes the format of the associated 'ds-text' section.
'man', 'mdoc' and 'texi' formats are supported. Regardless of
the chosen format, the formatting tags in the output text will
be converted to 'man' macros for 'man' pages, 'mdoc' macros
for 'mdoc' pages, and 'texi' macros for 'texinfo' pages.
ds-text
This is the descriptive text, written according to the rules
for 'ds-format' documents.
ds-type
This describes the section type. Basically, the title of the
section that will be added to all output documentation. There
may be only one 'doc-section' for any given 'ds-type'. If
there are duplicates, the results are undefined (it might
work, it might not).
There are five categories of 'ds-type' sections. They are
those that the documentation templates would otherwise:
1. always create itself, ignoring any 'ds-type's by this
name. These are marked, below, as 'ao-only'.
2. create, if none was provided. These are marked,
'alternate'.
3. create, but augment if the 'doc-section' was provided.
These are marked, 'augments'.
4. do nothing, but inserts them into the output in a
prescribed order. These are marked, 'known'
5. knows nothing about them. They will be alphabetized and
inserted after the list of leading sections and before
the list of trailing sections. These are not marked
because I don't know their names.
Some of these are emitted by the documentation templates only
if certain conditions are met. If there are conditions, they
are explained below. If there are no conditions, then you
will always see the named section in the output.
The output sections will appear in this order:
'NAME'
'ao-only'.
'SYNOPSIS'
'alternate'.
'DESCRIPTION'
'augments'.
'OPTIONS'
'ao-only'.
'OPTION PRESETS'
'ao-only', if environment presets or configuration file
processing has been specified.
'unknown'
At this point, the unknown, alphabetized sections are
inserted.
'IMPLEMENTATION NOTES'
'known'
'ENVIRONMENT'
'augments', if environment presets have been specified.
'FILES'
'augments', if configuration file processing has been
specified.
'EXAMPLES'
'known'
'EXIT STATUS'
'augments'.
'ERRORS'
'known'
'COMPATIBILITY'
'known'
'SEE ALSO'
'known'
'CONFORMING TO'
'known'
'HISTORY'
'known'
'AUTHORS'
'alternate', if the 'copyright' stanza has either an
'author' or an 'owner' attribute.
'COPYRIGHT'
'alternate', if there is a 'copyright' stanza.
'BUGS'
'augments', if the 'copyright' stanza has an 'eaddr'
attribute.
'NOTES'
'augments'.
Here is an example of a 'doc-section' for a 'SEE ALSO' type.
doc-section = {
ds-type = 'SEE ALSO'; // or anything else
ds-format = 'man'; // or texi or mdoc format
ds-text = <<-_EOText_
text relevant to this section type,
in the chosen format
_EOText_;
};
'doc-sub'
This attribute will cause the resulting documentation to be
post-processed. This is normally with 'sed', see 'doc-sub-cmd'
below. This attribute has several sub-attributes:
'sub-name'
This is the name of an autogen text definition value, like
'prog-name' or 'version'. In the 'sub-text' field,
occurrences of this name preceded by two less than characters
and followed by two greater than characters will be replaced
by the text value of the definition, e.g. '<>'.
'sub-text'
The text that gets added to the command file for the post
processing program.
'sub-type'
If this command only applies to certain types of output,
specify this with a regular expression that will match one of
the valid output format types, e.g. 'man|mdoc' will match
those two kinds, but not 'texi' output. If omitted, it will
always apply.
For example, if you want to reference the program name in the 'doc'
text for an option common to two programs, put '#PROG#' into the
text. The following will replace all occrrences of '#PROG#' with
the current value for 'prog':
doc-sub = {
sub-name = prog-name;
sub-text = 's/#PROG#/<>/g';
};
'doc-sub-cmd'
A formatting string for constructing the post-processing command.
The first parameter is the name of the file with editing commands
in it, and the second is the file containing the unprocessed
document. The default value is:
sed -f %s %s
File: autogen.info, Node: automatic options, Next: standard options, Prev: documentation attributes, Up: Option Definitions
7.5.10 Automatically Supported Options
--------------------------------------
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 *Note program
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.
'help -?'
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.
'more-help -!'
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.)
'usage -u'
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').
'version -v'
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.
'load-opts -<'
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.
'save-opts ->'
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 (*note SET_OPT_name::).
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 (*note
libopts-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 )' (*note CLEAR_OPT::)
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:
'default'
If an option has a default value (has not been set), then the
default value is inserted as a comment.
'usage'
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
'update'
Instead of removing the old file and writing a new one, the
output file is kept, but any pre-existing segment labeled with
'' 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.
'reset-option -R'
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.
File: autogen.info, Node: standard options, Prev: automatic options, Up: Option Definitions
7.5.11 Library of Standard Options
----------------------------------
AutoOpts has developed a set of standardized options. You may
incorporate these options in your program simply by _first_ adding a
'#define' for the options you want, and then the line,
#include stdoptions.def
in your option definitions. The supported options are specified thus:
#define DEBUG
#define DIRECTORY
#define DRY_RUN
#define INPUT
#define INTERACTIVE
#define OUTPUT
#define WARN
#define SILENT
#define QUIET
#define BRIEF
#define VERBOSE
By default, only the long form of the option will be available. To
specify the short (flag) form, suffix these names with '_FLAG'. e.g.,
#define DEBUG_FLAG
'--silent', '--quiet', '--brief' and '--verbose' are related in that
they all indicate some level of diagnostic output. These options are
all designed to conflict with each other. Instead of four different
options, however, several levels can be incorporated by '#define'-ing
'VERBOSE_ENUM'. In conjunction with 'VERBOSE', it incorporates the
notion of 5 levels in an enumeration: 'silent', 'quiet', 'brief',
'informative' and 'verbose'; with the default being 'brief'.
Here is an example program that uses the following set of
definitions:
AutoGen Definitions options;
prog-name = default-test;
prog-title = 'Default Option Example';
homerc = '$$/../share/default-test', '$HOME', '.';
environrc;
long-opts;
gnu-usage;
usage-opt;
version = '1.0';
main = {
main-type = shell-process;
};
#define DEBUG_FLAG
#define WARN_FLAG
#define WARN_LEVEL
#define VERBOSE_FLAG
#define VERBOSE_ENUM
#define DRY_RUN_FLAG
#define OUTPUT_FLAG
#define INPUT_FLAG
#define DIRECTORY_FLAG
#define INTERACTIVE_FLAG
#include stdoptions.def
Running a few simple commands on that definition file:
autogen default-test.def
copts="-DTEST_DEFAULT_TEST_OPTS `autoopts-config cflags`"
lopts="`autoopts-config ldflags`"
cc -o default-test ${copts} default-test.c ${lopts}
Yields a program which, when run with '--help', prints out:
exit 0
File: autogen.info, Node: AutoOpts API, Next: Multi-Threading, Prev: Option Definitions, Up: AutoOpts
7.6 Programmatic Interface
==========================
The user interface for access to the argument information is completely
defined in the generated header file and in the portions of the
distributed file "options.h" that are marked "public".
In the following macros, text marked or NAME is the name of
the option *in upper case* and *segmented with underscores '_'*. The
macros and enumerations defined in the options header (interface) file
are used as follows:
To see how these '#define' macros are used in a program, the reader
is referred to the several 'opts.h' files included with the AutoGen
sources.
* Menu:
* Option Processing Data:: Data for Option Processing
* CLEAR_OPT:: CLEAR_OPT( ) - Clear Option Markings
* COUNT_OPT:: COUNT_OPT( ) - Definition Count
* DESC:: DESC( ) - Option Descriptor
* DISABLE_OPT_name:: DISABLE_OPT_name - Disable an option
* ENABLED_OPT:: ENABLED_OPT( ) - Is Option Enabled?
* ERRSKIP_OPTERR:: ERRSKIP_OPTERR - Ignore Option Errors
* ERRSTOP_OPTERR:: ERRSTOP_OPTERR - Stop on Errors
* HAVE_OPT:: HAVE_OPT( ) - Have this option?
* ISSEL_OPT:: ISSEL_OPT( ) - Is Option Selected?
* ISUNUSED_OPT:: ISUNUSED_OPT( ) - Never Specified?
* OPTION_CT:: OPTION_CT - Full Count of Options
* OPT_ARG:: OPT_ARG( ) - Option Argument String
* OPT_NO_XLAT_CFG_NAMES:: OPT_NO_XLAT_CFG_NAMES - option name xlation
* OPT_NO_XLAT_OPT_NAMES:: OPT_NO_XLAT_OPT_NAMES - option name xlation
* OPT_VALUE_name:: OPT_VALUE_name - Option Argument Value
* OPT_XLAT_CFG_NAMES:: OPT_XLAT_CFG_NAMES - option name xlation
* OPT_XLAT_OPT_NAMES:: OPT_XLAT_OPT_NAMES - option name xlation
* RESTART_OPT:: RESTART_OPT( n ) - Resume Option Processing
* SET_OPT_name:: SET_OPT_name - Force an option to be set
* STACKCT_OPT:: STACKCT_OPT( ) - Stacked Arg Count
* STACKLST_OPT:: STACKLST_OPT( ) - Argument Stack
* START_OPT:: START_OPT - Restart Option Processing
* STATE_OPT:: STATE_OPT( ) - Option State
* USAGE:: USAGE( exit-code ) - Usage invocation macro
* VALUE_OPT_name:: VALUE_OPT_name - Option Flag Value
* VERSION:: VERSION - Version and Full Version
* WHICH_IDX_name:: WHICH_IDX_name - Which Equivalenced Index
* WHICH_OPT_name:: WHICH_OPT_name - Which Equivalenced Option
* teOptIndex:: teOptIndex - Option Index and Enumeration
* OPTIONS_STRUCT_VERSION:: OPTIONS_STRUCT_VERSION - active version
* libopts procedures:: libopts External Procedures
File: autogen.info, Node: Option Processing Data, Next: CLEAR_OPT, Up: AutoOpts API
7.6.1 Data for Option Processing
--------------------------------
This section describes the data that may be accessed from within the
option processing callback routines. The following fields may be used
in the following ways and may be used for read only. The first set is
addressed from the 'tOptDesc*' pointer:
'optIndex'
'optValue'
These may be used by option procedures to determine which option
they are working on (in case they handle several options).
'optActualIndex'
'optActualValue'
These may be used by option procedures to determine which option
was used to set the current option. This may be different from the
above if the options are members of an equivalence class.
'optOccCt'
If AutoOpts is processing command line arguments, then this value
will contain the current occurrence count. During the option
preset phase (reading configuration files and examining environment
variables), the value is zero.
'fOptState'
The field may be tested for the following bit values (prefix each
name with 'OPTST_', e.g. 'OPTST_INIT'):
'INIT'
Initial compiled value. As a bit test, it will always yield
FALSE.
'SET'
The option was set via the 'SET_OPT()' macro.
'PRESET'
The option was set via a configuration file.
'DEFINED'
The option was set via a command line option.
'SET_MASK'
This is a mask of flags that show the set state, one of the
above four values.
'EQUIVALENCE'
This bit is set when the option was selected by an
equivalenced option.
'DISABLED'
This bit is set if the option is to be disabled. (Meaning it
was a long option prefixed by the disablement prefix, or the
option has not been specified yet and initializes as
'disabled'.)
As an example of how this might be used, in AutoGen I want to allow
template writers to specify that the template output can be left in
a writable or read-only state. To support this, there is a Guile
function named 'set-writable' (*note SCM set-writable::). Also, I
provide for command options '--writable' and '--not-writable'. I
give precedence to command line and RC file options, thus:
switch (STATE_OPT( WRITABLE )) {
case OPTST_DEFINED:
case OPTST_PRESET:
fprintf(stderr, zOverrideWarn, pCurTemplate->pzFileName,
pCurMacro->lineNo);
break;
default:
if (gh_boolean_p( set ) && (set == SCM_BOOL_F))
CLEAR_OPT( WRITABLE );
else
SET_OPT_WRITABLE;
}
'pzLastArg'
Pointer to the latest argument string. BEWARE If the argument type
is numeric, an enumeration or a bit mask, then this will be the
argument *value* and not a pointer to a string.
The following two fields are addressed from the 'tOptions*' pointer:
'pzProgName'
Points to a NUL-terminated string containing the current program
name, as retrieved from the argument vector.
'pzProgPath'
Points to a NUL-terminated string containing the full path of the
current program, as retrieved from the argument vector. (If
available on your system.)
Note these fields get filled in during the first call to
'optionProcess()'. All other fields are private, for the exclusive use
of AutoOpts code and are subject to change.
File: autogen.info, Node: CLEAR_OPT, Next: COUNT_OPT, Prev: Option Processing Data, Up: AutoOpts API
7.6.2 CLEAR_OPT( ) - Clear Option Markings
-------------------------------------------------
Make as if the option had never been specified. 'HAVE_OPT()' will
yield 'FALSE' after invoking this macro.
File: autogen.info, Node: COUNT_OPT, Next: DESC, Prev: CLEAR_OPT, Up: AutoOpts API
7.6.3 COUNT_OPT( ) - Definition Count
--------------------------------------------
This macro will tell you how many times the option was specified on the
command line. It does not include counts of preset options.
if (COUNT_OPT( NAME ) != desired-count) {
make-an-undesirable-message.
}
File: autogen.info, Node: DESC, Next: DISABLE_OPT_name, Prev: COUNT_OPT, Up: AutoOpts API
7.6.4 DESC( ) - Option Descriptor
----------------------------------------
This macro is used internally by other AutoOpt macros. It is not for
general use. It is used to obtain the option description corresponding
to its *UPPER CASED* option name argument. This is primarily used in
other macro definitions.
File: autogen.info, Node: DISABLE_OPT_name, Next: ENABLED_OPT, Prev: DESC, Up: AutoOpts API
7.6.5 DISABLE_OPT_name - Disable an option
------------------------------------------
This macro is emitted if it is both settable and it can be disabled. If
it cannot be disabled, it may always be CLEAR-ed (see above).
The form of the macro will actually depend on whether the option is
equivalenced to another, and/or has an assigned handler procedure.
Unlike the 'SET_OPT' macro, this macro does not allow an option
argument.
DISABLE_OPT_NAME;
File: autogen.info, Node: ENABLED_OPT, Next: ERRSKIP_OPTERR, Prev: DISABLE_OPT_name, Up: AutoOpts API
7.6.6 ENABLED_OPT( ) - Is Option Enabled?
------------------------------------------------
Yields true if the option defaults to disabled and 'ISUNUSED_OPT()'
would yield true. It also yields true if the option has been specified
with a disablement prefix, disablement value or the 'DISABLE_OPT_NAME'
macro was invoked.
File: autogen.info, Node: ERRSKIP_OPTERR, Next: ERRSTOP_OPTERR, Prev: ENABLED_OPT, Up: AutoOpts API
7.6.7 ERRSKIP_OPTERR - Ignore Option Errors
-------------------------------------------
When it is necessary to continue (return to caller) on option errors,
invoke this option. It is reversible. *Note ERRSTOP_OPTERR::.
File: autogen.info, Node: ERRSTOP_OPTERR, Next: HAVE_OPT, Prev: ERRSKIP_OPTERR, Up: AutoOpts API
7.6.8 ERRSTOP_OPTERR - Stop on Errors
-------------------------------------
After invoking this macro, if 'optionProcess()' encounters an error, it
will call 'exit(1)' rather than return. This is the default processing
mode. It can be overridden by specifying 'allow-errors' in the
definitions file, or invoking the macro *Note ERRSKIP_OPTERR::.
File: autogen.info, Node: HAVE_OPT, Next: ISSEL_OPT, Prev: ERRSTOP_OPTERR, Up: AutoOpts API
7.6.9 HAVE_OPT( ) - Have this option?
--------------------------------------------
This macro yields true if the option has been specified in any fashion
at all. It is used thus:
if (HAVE_OPT( NAME )) {
;
}
File: autogen.info, Node: ISSEL_OPT, Next: ISUNUSED_OPT, Prev: HAVE_OPT, Up: AutoOpts API
7.6.10 ISSEL_OPT( ) - Is Option Selected?
------------------------------------------------
This macro yields true if the option has been specified either on the
command line or via a SET/DISABLE macro.
File: autogen.info, Node: ISUNUSED_OPT, Next: OPTION_CT, Prev: ISSEL_OPT, Up: AutoOpts API
7.6.11 ISUNUSED_OPT( ) - Never Specified?
------------------------------------------------
This macro yields true if the option has never been specified, or has
been cleared via the 'CLEAR_OPT()' macro.
File: autogen.info, Node: OPTION_CT, Next: OPT_ARG, Prev: ISUNUSED_OPT, Up: AutoOpts API
7.6.12 OPTION_CT - Full Count of Options
----------------------------------------
The full count of all options, both those defined and those generated
automatically by AutoOpts. This is primarily used to initialize the
program option descriptor structure.
File: autogen.info, Node: OPT_ARG, Next: OPT_NO_XLAT_CFG_NAMES, Prev: OPTION_CT, Up: AutoOpts API
7.6.13 OPT_ARG( ) - Option Argument String
-------------------------------------------------
The option argument value as a pointer to string. Note that argument
values that have been specified as numbers are stored as numbers or
keywords. For such options, use instead the 'OPT_VALUE_name' define.
It is used thus:
if (HAVE_OPT( NAME )) {
char* p = OPT_ARG( NAME );
;
}
File: autogen.info, Node: OPT_NO_XLAT_CFG_NAMES, Next: OPT_NO_XLAT_OPT_NAMES, Prev: OPT_ARG, Up: AutoOpts API
7.6.14 OPT_NO_XLAT_CFG_NAMES - option name xlation
--------------------------------------------------
Invoking this macro will disable the translation of option names only
while processing configuration files and environment variables. This
must be invoked before the first call to 'optionProcess'.. You need not
invoke this if your option definition file contains the attribute
assignment, 'no-xlate = opt-cfg;'.
File: autogen.info, Node: OPT_NO_XLAT_OPT_NAMES, Next: OPT_VALUE_name, Prev: OPT_NO_XLAT_CFG_NAMES, Up: AutoOpts API
7.6.15 OPT_NO_XLAT_OPT_NAMES - option name xlation
--------------------------------------------------
Invoking this macro will completely disable the translation of option
names. This must be invoked before the first call to 'optionProcess'.
You need not invoke this if your option definition file contains the
attribute assignment, 'no-xlate = opt;'.
File: autogen.info, Node: OPT_VALUE_name, Next: OPT_XLAT_CFG_NAMES, Prev: OPT_NO_XLAT_OPT_NAMES, Up: AutoOpts API
7.6.16 OPT_VALUE_name - Option Argument Value
---------------------------------------------
This macro gets emitted only for options that take numeric, keyword or
set membership arguments. The macro yields a word-sized integer
containing the enumeration, bit set or numeric value for the option
argument.
int opt_val = OPT_VALUE_name;
File: autogen.info, Node: OPT_XLAT_CFG_NAMES, Next: OPT_XLAT_OPT_NAMES, Prev: OPT_VALUE_name, Up: AutoOpts API
7.6.17 OPT_XLAT_CFG_NAMES - option name xlation
-----------------------------------------------
If 'ENABLE_NLS' is defined and 'no-xlate' has been not set to the value
_anything_, this macro will cause the translation of option names to
happen before starting the processing of configuration files and
environment variables. This will change the recognition of options
within the '$PROGRAMNAME' environment variable, but will not alter the
names used for setting options via '$PROGRAMNAME_name' environment
variables.
This must be invoked before the first call to 'optionProcess'. You
might need to use this macro if your option definition file contains the
attribute assignment, 'no-xlate = opt;' or 'no-xlate = opt-cfg;', and
you have determined in some way that you wish to override that.
File: autogen.info, Node: OPT_XLAT_OPT_NAMES, Next: RESTART_OPT, Prev: OPT_XLAT_CFG_NAMES, Up: AutoOpts API
7.6.18 OPT_XLAT_OPT_NAMES - option name xlation
-----------------------------------------------
If 'ENABLE_NLS' is defined and 'no-xlate' has been not set to the value
_anything_, translate the option names before processing the command
line options. Long option names may thus be localized. (If the names
were translated before configuration processing, they will not be
re-translated.)
This must be invoked before the first call to 'optionProcess'. You
might need to use this macro if your option definition file contains the
attribute assignment, 'no-xlate = opt;' and you have determined in some
way that you wish to override that.
File: autogen.info, Node: RESTART_OPT, Next: SET_OPT_name, Prev: OPT_XLAT_OPT_NAMES, Up: AutoOpts API
7.6.19 RESTART_OPT( n ) - Resume Option Processing
--------------------------------------------------
If option processing has stopped (either because of an error or
something was encountered that looked like a program argument), it can
be resumed by providing this macro with the index 'n' of the next option
to process and calling 'optionProcess()' again.
int main(int argc, char ** argv) {
for (int ai = 0; ai < argc ;) {
restart:
ai = optionProcess(&progOptions, argc, argv);
for (; ai < argc; ai++) {
char * arg = arg[ai];
if (*arg == '-') {
RESTART_OPT(ai);
goto restart;
}
process(arg);
}
}
}
If you want a program to operate this way, you might consider
specifying a 'for-each' main function (*note for-each main procedure:
main for-each.) with the 'interleaved' attribute. It will allow you to
process interleaved operands and options from either the command line or
when reading them from standard input.
File: autogen.info, Node: SET_OPT_name, Next: STACKCT_OPT, Prev: RESTART_OPT, Up: AutoOpts API
7.6.20 SET_OPT_name - Force an option to be set
-----------------------------------------------
This macro gets emitted only when the given option has the 'settable'
attribute specified.
The form of the macro will actually depend on whether the option is
equivalenced to another, has an option argument and/or has an assigned
handler procedure. If the option has an argument, then this macro will
too. Beware that the argument is not reallocated, so the value must not
be on the stack or deallocated in any other way for as long as the value
might get referenced.
If you have supplied at least one 'homerc' file (*note program
attributes::), this macro will be emitted for the '--save-opts' option.
SET_OPT_SAVE_OPTS( "filename" );
*Note automatic options::, for a discussion of the implications of using
this particular example.
File: autogen.info, Node: STACKCT_OPT, Next: STACKLST_OPT, Prev: SET_OPT_name, Up: AutoOpts API
7.6.21 STACKCT_OPT( ) - Stacked Arg Count
------------------------------------------------
When the option handling attribute is specified as 'stack_arg', this
macro may be used to determine how many of them actually got stacked.
Do not use this on options that have not been stacked or has not been
specified (the 'stack_arg' attribute must have been specified, and
'HAVE_OPT()' must yield TRUE). Otherwise, you will likely seg
fault.
if (HAVE_OPT( NAME )) {
int ct = STACKCT_OPT( NAME );
char** pp = STACKLST_OPT( NAME );
do {
char* p = *pp++;
do-things-with-p;
} while (--ct > 0);
}
File: autogen.info, Node: STACKLST_OPT, Next: START_OPT, Prev: STACKCT_OPT, Up: AutoOpts API
7.6.22 STACKLST_OPT( ) - Argument Stack
----------------------------------------------
The address of the list of pointers to the option arguments. The
pointers are ordered by the order in which they were encountered in the
option presets and command line processing.
Do not use this on options that have not been stacked or has not been
specified (the 'stack_arg' attribute must have been specified, and
'HAVE_OPT(