Fixed build with HWASan

[platform/upstream/autogen.git] / doc / autogen.info-2

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 <http://www.gnu.org/licenses/>.

\1f
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.

\1f
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.

\1f
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

\1f
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.

\1f
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.)

\1f
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 */
     }

\1f
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

\1f
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.

\1f
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.

\1f
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.

\1f
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

\1f
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.

\1f
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.

\1f
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.

\1f
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.

\1f
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.

\1f
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;
     }

\1f
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.

\1f
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.

\1f
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.

\1f
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 '<OPTN_NAME>_<KEYWORD>' 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').

\1f
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'.

\1f
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'.

\1f
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<name>(tOptions* pOptions, tOptDesc* pOptDesc)
          {
          <flag-code[0]>
          <AutoOpts defined handler code>
          <flag-code[1]>
          }

     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<name>'.  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.

\1f
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.

\1f
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

\1f
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.

\1f
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 <header-or-code-file-name>
           *  @addtogroup <value-of-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.  '<<prog-name>>'.

     '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#/<<prog-name>>/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

\1f
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
          '<?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.

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

\1f
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

\1f
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 <NAME> 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( <NAME> ) - Clear Option Markings
* COUNT_OPT::               COUNT_OPT( <NAME> ) - Definition Count
* DESC::                    DESC( <NAME> ) - Option Descriptor
* DISABLE_OPT_name::        DISABLE_OPT_name - Disable an option
* ENABLED_OPT::             ENABLED_OPT( <NAME> ) - Is Option Enabled?
* ERRSKIP_OPTERR::          ERRSKIP_OPTERR - Ignore Option Errors
* ERRSTOP_OPTERR::          ERRSTOP_OPTERR - Stop on Errors
* HAVE_OPT::                HAVE_OPT( <NAME> ) - Have this option?
* ISSEL_OPT::               ISSEL_OPT( <NAME> ) - Is Option Selected?
* ISUNUSED_OPT::            ISUNUSED_OPT( <NAME> ) - Never Specified?
* OPTION_CT::               OPTION_CT - Full Count of Options
* OPT_ARG::                 OPT_ARG( <NAME> ) - 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( <NAME> ) - Stacked Arg Count
* STACKLST_OPT::            STACKLST_OPT( <NAME> ) - Argument Stack
* START_OPT::               START_OPT - Restart Option Processing
* STATE_OPT::               STATE_OPT( <NAME> ) - 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

\1f
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.

\1f
File: autogen.info,  Node: CLEAR_OPT,  Next: COUNT_OPT,  Prev: Option Processing Data,  Up: AutoOpts API

7.6.2 CLEAR_OPT( <NAME> ) - Clear Option Markings
-------------------------------------------------

Make as if the option had never been specified.  'HAVE_OPT(<NAME>)' will
yield 'FALSE' after invoking this macro.

\1f
File: autogen.info,  Node: COUNT_OPT,  Next: DESC,  Prev: CLEAR_OPT,  Up: AutoOpts API

7.6.3 COUNT_OPT( <NAME> ) - 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.
     }

\1f
File: autogen.info,  Node: DESC,  Next: DISABLE_OPT_name,  Prev: COUNT_OPT,  Up: AutoOpts API

7.6.4 DESC( <NAME> ) - 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.

\1f
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;

\1f
File: autogen.info,  Node: ENABLED_OPT,  Next: ERRSKIP_OPTERR,  Prev: DISABLE_OPT_name,  Up: AutoOpts API

7.6.6 ENABLED_OPT( <NAME> ) - 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.

\1f
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::.

\1f
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::.

\1f
File: autogen.info,  Node: HAVE_OPT,  Next: ISSEL_OPT,  Prev: ERRSTOP_OPTERR,  Up: AutoOpts API

7.6.9 HAVE_OPT( <NAME> ) - 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 )) {
         <do-things-associated-with-opt-name>;
     }

\1f
File: autogen.info,  Node: ISSEL_OPT,  Next: ISUNUSED_OPT,  Prev: HAVE_OPT,  Up: AutoOpts API

7.6.10 ISSEL_OPT( <NAME> ) - Is Option Selected?
------------------------------------------------

This macro yields true if the option has been specified either on the
command line or via a SET/DISABLE macro.

\1f
File: autogen.info,  Node: ISUNUSED_OPT,  Next: OPTION_CT,  Prev: ISSEL_OPT,  Up: AutoOpts API

7.6.11 ISUNUSED_OPT( <NAME> ) - Never Specified?
------------------------------------------------

This macro yields true if the option has never been specified, or has
been cleared via the 'CLEAR_OPT()' macro.

\1f
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.

\1f
File: autogen.info,  Node: OPT_ARG,  Next: OPT_NO_XLAT_CFG_NAMES,  Prev: OPTION_CT,  Up: AutoOpts API

7.6.13 OPT_ARG( <NAME> ) - 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 );
         <do-things-with-opt-name-argument-string>;
     }

\1f
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;'.

\1f
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;'.

\1f
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;

\1f
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.

\1f
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.

\1f
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.

\1f
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.

\1f
File: autogen.info,  Node: STACKCT_OPT,  Next: STACKLST_OPT,  Prev: SET_OPT_name,  Up: AutoOpts API

7.6.21 STACKCT_OPT( <NAME> ) - 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(<NAME>)' 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);
     }

\1f
File: autogen.info,  Node: STACKLST_OPT,  Next: START_OPT,  Prev: STACKCT_OPT,  Up: AutoOpts API

7.6.22 STACKLST_OPT( <NAME> ) - 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(<OPTION>)' 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);
     }

\1f
File: autogen.info,  Node: START_OPT,  Next: STATE_OPT,  Prev: STACKLST_OPT,  Up: AutoOpts API

7.6.23 START_OPT - Restart Option Processing
--------------------------------------------

This is just a shortcut for RESTART_OPT(1) (*Note RESTART_OPT::.)

\1f
File: autogen.info,  Node: STATE_OPT,  Next: USAGE,  Prev: START_OPT,  Up: AutoOpts API

7.6.24 STATE_OPT( <NAME> ) - Option State
-----------------------------------------

If you need to know if an option was set because of presetting actions
(configuration file processing or environment variables), versus a
command line entry versus one of the SET/DISABLE macros, then use this
macro.  It will yield one of four values: 'OPTST_INIT', 'OPTST_SET',
'OPTST_PRESET' or 'OPTST_DEFINED'.  It is used thus:

     switch (STATE_OPT( NAME )) {
         case OPTST_INIT:
             not-preset, set or on the command line.  (unless CLEAR-ed)

         case OPTST_SET:
             option set via the SET_OPT_NAME() macro.

         case OPTST_PRESET:
             option set via an configuration file or environment variable

         case OPTST_DEFINED:
             option set via a command line option.

         default:
             cannot happen :)
     }

\1f
File: autogen.info,  Node: USAGE,  Next: VALUE_OPT_name,  Prev: STATE_OPT,  Up: AutoOpts API

7.6.25 USAGE( exit-code ) - Usage invocation macro
--------------------------------------------------

This macro invokes the procedure registered to display the usage text.
Normally, this will be 'optionUsage' from the AutoOpts library, but you
may select another procedure by specifying 'usage = "proc_name"' program
attribute.  This procedure must take two arguments first, a pointer to
the option descriptor, and second the exit code.  The macro supplies the
option descriptor automatically.  This routine is expected to call
'exit(3)' with the provided exit code.

   The 'optionUsage' routine also behaves differently depending on the
exit code:

'EXIT_SUCCESS (the value zero)'
     It is assumed that full usage help has been requested.
     Consequently, more information is provided than when displaying
     usage and exiting with a non-zero exit code.  Output will be sent
     to 'stdout' and the program will exit with a zero status code.

'EX_USAGE (64)'
     The abbreviated usage will be printed to 'stdout' and the program
     will exit with a zero status code.  'EX_USAGE' may or may not be
     64.  If your system provides '/usr/include/sysexits.h' that has a
     different value, then that value will be used.

'any other value'
     The abbreviated usage will be printed to stderr and the program
     will exit with the provided status code.

\1f
File: autogen.info,  Node: VALUE_OPT_name,  Next: VERSION,  Prev: USAGE,  Up: AutoOpts API

7.6.26 VALUE_OPT_name - Option Flag Value
-----------------------------------------

This is a #define for the flag character used to specify an option on
the command line.  If 'value' was not specified for the option, then it
is a unique number associated with the option.  'option value' refers to
this value, 'option argument' refers to the (optional) argument to the
option.

     switch (WHICH_OPT_OTHER_OPT) {
     case VALUE_OPT_NAME:
         this-option-was-really-opt-name;
     case VALUE_OPT_OTHER_OPT:
         this-option-was-really-other-opt;
     }

\1f
File: autogen.info,  Node: VERSION,  Next: WHICH_IDX_name,  Prev: VALUE_OPT_name,  Up: AutoOpts API

7.6.27 VERSION - Version and Full Version
-----------------------------------------

If the 'version' attribute is defined for the program, then a
stringified version will be #defined as PROGRAM_VERSION and
PROGRAM_FULL_VERSION. PROGRAM_FULL_VERSION is used for printing the
program version in response to the version option.  The version option
is automatically supplied in response to this attribute, too.

   You may access PROGRAM_VERSION via 'programOptions.pzFullVersion'.

\1f
File: autogen.info,  Node: WHICH_IDX_name,  Next: WHICH_OPT_name,  Prev: VERSION,  Up: AutoOpts API

7.6.28 WHICH_IDX_name - Which Equivalenced Index
------------------------------------------------

This macro gets emitted only for equivalenced-to options.  It is used to
obtain the index for the one of the several equivalence class members
set the equivalenced-to option.

     switch (WHICH_IDX_OTHER_OPT) {
     case INDEX_OPT_NAME:
         this-option-was-really-opt-name;
     case INDEX_OPT_OTHER_OPT:
         this-option-was-really-other-opt;
     }

\1f
File: autogen.info,  Node: WHICH_OPT_name,  Next: teOptIndex,  Prev: WHICH_IDX_name,  Up: AutoOpts API

7.6.29 WHICH_OPT_name - Which Equivalenced Option
-------------------------------------------------

This macro gets emitted only for equivalenced-to options.  It is used to
obtain the value code for the one of the several equivalence class
members set the equivalenced-to option.

     switch (WHICH_OPT_OTHER_OPT) {
     case VALUE_OPT_NAME:
         this-option-was-really-opt-name;
     case VALUE_OPT_OTHER_OPT:
         this-option-was-really-other-opt;
     }

\1f
File: autogen.info,  Node: teOptIndex,  Next: OPTIONS_STRUCT_VERSION,  Prev: WHICH_OPT_name,  Up: AutoOpts API

7.6.30 teOptIndex - Option Index and Enumeration
------------------------------------------------

This enum defines the complete set of options, both user specified and
automatically provided.  This can be used, for example, to distinguish
which of the equivalenced options was actually used.

     switch (pOptDesc->optActualIndex) {
     case INDEX_OPT_FIRST:
         stuff;
     case INDEX_OPT_DIFFERENT:
         different-stuff;
     default:
         unknown-things;
     }

\1f
File: autogen.info,  Node: OPTIONS_STRUCT_VERSION,  Next: libopts procedures,  Prev: teOptIndex,  Up: AutoOpts API

7.6.31 OPTIONS_STRUCT_VERSION - active version
----------------------------------------------

You will not actually need to reference this value, but you need to be
aware that it is there.  It is the first value in the option descriptor
that you pass to 'optionProcess'.  It contains a magic number and
version information.  Normally, you should be able to work with a more
recent option library than the one you compiled with.  However, if the
library is changed incompatibly, then the library will detect the out of
date magic marker, explain the difficulty and exit.  You will then need
to rebuild and recompile your option definitions.  This has rarely been
necessary.

\1f
File: autogen.info,  Node: libopts procedures,  Prev: OPTIONS_STRUCT_VERSION,  Up: AutoOpts API

7.6.32 libopts External Procedures
----------------------------------

These are the routines that libopts users may call directly from their
code.  There are several other routines that can be called by code
generated by the libopts option templates, but they are not to be called
from any other user code.  The 'options.h' header is fairly clear about
this, too.

* Menu:

* libopts-ao_string_tokenize:: ao_string_tokenize
* libopts-configFileLoad::    configFileLoad
* libopts-optionFileLoad::    optionFileLoad
* libopts-optionFindNextValue:: optionFindNextValue
* libopts-optionFindValue::   optionFindValue
* libopts-optionFree::        optionFree
* libopts-optionGetValue::    optionGetValue
* libopts-optionLoadLine::    optionLoadLine
* libopts-optionMemberList::  optionMemberList
* libopts-optionNextValue::   optionNextValue
* libopts-optionOnlyUsage::   optionOnlyUsage
* libopts-optionPrintVersion:: optionPrintVersion
* libopts-optionPrintVersionAndReturn:: optionPrintVersionAndReturn
* libopts-optionProcess::     optionProcess
* libopts-optionRestore::     optionRestore
* libopts-optionSaveFile::    optionSaveFile
* libopts-optionSaveState::   optionSaveState
* libopts-optionUnloadNested:: optionUnloadNested
* libopts-optionVersion::     optionVersion
* libopts-strequate::         strequate
* libopts-streqvcmp::         streqvcmp
* libopts-streqvmap::         streqvmap
* libopts-strneqvcmp::        strneqvcmp
* libopts-strtransform::      strtransform

   This subsection was automatically generated by AutoGen using
extracted information and the aginfo3.tpl template.

\1f
File: autogen.info,  Node: libopts-ao_string_tokenize,  Next: libopts-configFileLoad,  Up: libopts procedures

7.6.32.1 ao_string_tokenize
...........................

tokenize an input string

Usage:
     token_list_t * res = ao_string_tokenize( string );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     string      'char const    string to be tokenized
                 *'
     returns     token_list_t   pointer to a structure that lists each
                 *              token

   This function will convert one input string into a list of strings.
The list of strings is derived by separating the input based on white
space separation.  However, if the input contains either single or
double quote characters, then the text after that character up to a
matching quote will become the string in the list.

   The returned pointer should be deallocated with 'free(3C)' when are
done using the data.  The data are placed in a single block of allocated
memory.  Do not deallocate individual token/strings.

   The structure pointed to will contain at least these two fields:
'tkn_ct'
     The number of tokens found in the input string.
'tok_list'
     An array of 'tkn_ct + 1' pointers to substring tokens, with the
     last pointer set to NULL.

   There are two types of quoted strings: single quoted (''') and double
quoted ('"').  Singly quoted strings are fairly raw in that escape
characters ('\\') are simply another character, except when preceding
the following characters:
     \\  double backslashes reduce to one
     '   incorporates the single quote into the string
     \n  suppresses both the backslash and newline character

   Double quote strings are formed according to the rules of string
constants in ANSI-C programs.

   NULL is returned and 'errno' will be set to indicate the problem:
   * 'EINVAL' - There was an unterminated quoted string.
   * 'ENOENT' - The input string was empty.
   * 'ENOMEM' - There is not enough memory.

\1f
File: autogen.info,  Node: libopts-configFileLoad,  Next: libopts-optionFileLoad,  Prev: libopts-ao_string_tokenize,  Up: libopts procedures

7.6.32.2 configFileLoad
.......................

parse a configuration file

Usage:
     const tOptionValue * res = configFileLoad( fname );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     fname       'char const    the file to load
                 *'
     returns     const          An allocated, compound value structure
                 tOptionValue
                 *

   This routine will load a named configuration file and parse the text
as a hierarchically valued option.  The option descriptor created from
an option definition file is not used via this interface.  The returned
value is "named" with the input file name and is of type
"'OPARG_TYPE_HIERARCHY'".  It may be used in calls to
'optionGetValue()', 'optionNextValue()' and 'optionUnloadNested()'.

   If the file cannot be loaded or processed, 'NULL' is returned and
ERRNO is set.  It may be set by a call to either 'open(2)' 'mmap(2)' or
other file system calls, or it may be:
   * 'ENOENT' - the file was not found.
   * 'ENOMSG' - the file was empty.
   * 'EINVAL' - the file contents are invalid - not properly formed.
   * 'ENOMEM' - not enough memory to allocate the needed structures.

\1f
File: autogen.info,  Node: libopts-optionFileLoad,  Next: libopts-optionFindNextValue,  Prev: libopts-configFileLoad,  Up: libopts procedures

7.6.32.3 optionFileLoad
.......................

Load the locatable config files, in order

Usage:
     int res = optionFileLoad( opts, prog );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     opts        'tOptions *'   program options descriptor
                                
     prog        'char const    program name
                 *'
     returns     int            0 -> SUCCESS, -1 -> FAILURE

   This function looks in all the specified directories for a
configuration file ("rc" file or "ini" file) and processes any found
twice.  The first time through, they are processed in reverse order
(last file first).  At that time, only "immediate action" configurables
are processed.  For example, if the last named file specifies not
processing any more configuration files, then no more configuration
files will be processed.  Such an option in the *first* named directory
will have no effect.

   Once the immediate action configurables have been handled, then the
directories are handled in normal, forward order.  In that way, later
config files can override the settings of earlier config files.

   See the AutoOpts documentation for a thorough discussion of the
config file format.

   Configuration files not found or not decipherable are simply ignored.

   Returns the value, "-1" if the program options descriptor is out of
date or indecipherable.  Otherwise, the value "0" will always be
returned.

\1f
File: autogen.info,  Node: libopts-optionFindNextValue,  Next: libopts-optionFindValue,  Prev: libopts-optionFileLoad,  Up: libopts procedures

7.6.32.4 optionFindNextValue
............................

find a hierarcicaly valued option instance

Usage:
     const tOptionValue * res = optionFindNextValue( odesc, pPrevVal, name, value );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     odesc       'const         an option with a nested arg type
                 tOptDesc *'    
     pPrevVal    'const         the last entry
                 tOptionValue   
                 *'
     name        'char const    name of value to find
                 *'             
     value       'char const    the matching value
                 *'
     returns     const          a compound value structure
                 tOptionValue
                 *

   This routine will find the next entry in a nested value option or
configurable.  It will search through the list and return the next entry
that matches the criteria.

   The returned result is NULL and errno is set:
   * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical
     option value.
   * 'ENOENT' - no entry matched the given name.

\1f
File: autogen.info,  Node: libopts-optionFindValue,  Next: libopts-optionFree,  Prev: libopts-optionFindNextValue,  Up: libopts procedures

7.6.32.5 optionFindValue
........................

find a hierarcicaly valued option instance

Usage:
     const tOptionValue * res = optionFindValue( odesc, name, val );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     odesc       'const         an option with a nested arg type
                 tOptDesc *'    
     name        'char const    name of value to find
                 *'             
     val         'char const    the matching value
                 *'
     returns     const          a compound value structure
                 tOptionValue
                 *

   This routine will find an entry in a nested value option or
configurable.  It will search through the list and return a matching
entry.

   The returned result is NULL and errno is set:
   * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical
     option value.
   * 'ENOENT' - no entry matched the given name.

\1f
File: autogen.info,  Node: libopts-optionFree,  Next: libopts-optionGetValue,  Prev: libopts-optionFindValue,  Up: libopts procedures

7.6.32.6 optionFree
...................

free allocated option processing memory

Usage:
     optionFree( pOpts );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     pOpts       'tOptions *'   program options descriptor

   AutoOpts sometimes allocates memory and puts pointers to it in the
option state structures.  This routine deallocates all such memory.

   As long as memory has not been corrupted, this routine is always
successful.

\1f
File: autogen.info,  Node: libopts-optionGetValue,  Next: libopts-optionLoadLine,  Prev: libopts-optionFree,  Up: libopts procedures

7.6.32.7 optionGetValue
.......................

get a specific value from a hierarcical list

Usage:
     const tOptionValue * res = optionGetValue( pOptValue, valueName );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     pOptValue   'const         a hierarchcal value
                 tOptionValue   
                 *'
     valueName   'char const    name of value to get
                 *'
     returns     const          a compound value structure
                 tOptionValue
                 *

   This routine will find an entry in a nested value option or
configurable.  If "valueName" is NULL, then the first entry is returned.
Otherwise, the first entry with a name that exactly matches the argument
will be returned.  If there is no matching value, NULL is returned and
errno is set to ENOENT. If the provided option value is not a
hierarchical value, NULL is also returned and errno is set to EINVAL.

   The returned result is NULL and errno is set:
   * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical
     option value.
   * 'ENOENT' - no entry matched the given name.

\1f
File: autogen.info,  Node: libopts-optionLoadLine,  Next: libopts-optionMemberList,  Prev: libopts-optionGetValue,  Up: libopts procedures

7.6.32.8 optionLoadLine
.......................

process a string for an option name and value

Usage:
     optionLoadLine( opts, line );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     opts        'tOptions *'   program options descriptor
                                
     line        'char const    NUL-terminated text
                 *'

   This is a client program callable routine for setting options from,
for example, the contents of a file that they read in.  Only one option
may appear in the text.  It will be treated as a normal (non-preset)
option.

   When passed a pointer to the option struct and a string, it will find
the option named by the first token on the string and set the option
argument to the remainder of the string.  The caller must NUL terminate
the string.  The caller need not skip over any introductory hyphens.
Any embedded new lines will be included in the option argument.  If the
input looks like one or more quoted strings, then the input will be
"cooked".  The "cooking" is identical to the string formation used in
AutoGen definition files (*note basic expression::), except that you may
not use backquotes.

   Invalid options are silently ignored.  Invalid option arguments will
cause a warning to print, but the function should return.

\1f
File: autogen.info,  Node: libopts-optionMemberList,  Next: libopts-optionNextValue,  Prev: libopts-optionLoadLine,  Up: libopts procedures

7.6.32.9 optionMemberList
.........................

Get the list of members of a bit mask set

Usage:
     char * res = optionMemberList( od );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     od          'tOptDesc *'   the set membership option description
     returns     char *         the names of the set bits

   This converts the OPT_VALUE_name mask value to a allocated string.
It is the caller's responsibility to free the string.

\1f
File: autogen.info,  Node: libopts-optionNextValue,  Next: libopts-optionOnlyUsage,  Prev: libopts-optionMemberList,  Up: libopts procedures

7.6.32.10 optionNextValue
.........................

get the next value from a hierarchical list

Usage:
     const tOptionValue * res = optionNextValue( pOptValue, pOldValue );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     pOptValue   'const         a hierarchcal list value
                 tOptionValue   
                 *'
     pOldValue   'const         a value from this list
                 tOptionValue
                 *'
     returns     const          a compound value structure
                 tOptionValue
                 *

   This routine will return the next entry after the entry passed in.
At the end of the list, NULL will be returned.  If the entry is not
found on the list, NULL will be returned and "ERRNO" will be set to
EINVAL. The "POLDVALUE" must have been gotten from a prior call to this
routine or to "'opitonGetValue()'".

   The returned result is NULL and errno is set:
   * 'EINVAL' - the 'pOptValue' does not point to a valid hierarchical
     option value or 'pOldValue' does not point to a member of that
     option value.
   * 'ENOENT' - the supplied 'pOldValue' pointed to the last entry.

\1f
File: autogen.info,  Node: libopts-optionOnlyUsage,  Next: libopts-optionPrintVersion,  Prev: libopts-optionNextValue,  Up: libopts procedures

7.6.32.11 optionOnlyUsage
.........................

Print usage text for just the options

Usage:
     optionOnlyUsage( pOpts, ex_code );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     pOpts       'tOptions *'   program options descriptor
                                
     ex_code     'int'          exit code for calling exit(3)

   This routine will print only the usage for each option.  This
function may be used when the emitted usage must incorporate information
not available to AutoOpts.

\1f
File: autogen.info,  Node: libopts-optionPrintVersion,  Next: libopts-optionPrintVersionAndReturn,  Prev: libopts-optionOnlyUsage,  Up: libopts procedures

7.6.32.12 optionPrintVersion
............................

Print the program version

Usage:
     optionPrintVersion( opts, od );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     opts        'tOptions *'   program options descriptor
                                
     od          'tOptDesc *'   the descriptor for this arg

   This routine will print the version to stdout.

\1f
File: autogen.info,  Node: libopts-optionPrintVersionAndReturn,  Next: libopts-optionProcess,  Prev: libopts-optionPrintVersion,  Up: libopts procedures

7.6.32.13 optionPrintVersionAndReturn
.....................................

Print the program version

Usage:
     optionPrintVersionAndReturn( opts, od );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     opts        'tOptions *'   program options descriptor
                                
     od          'tOptDesc *'   the descriptor for this arg

   This routine will print the version to stdout and return instead of
exiting.  Please see the source for the 'print_ver' funtion for details
on selecting how verbose to be after this function returns.

\1f
File: autogen.info,  Node: libopts-optionProcess,  Next: libopts-optionRestore,  Prev: libopts-optionPrintVersionAndReturn,  Up: libopts procedures

7.6.32.14 optionProcess
.......................

this is the main option processing routine

Usage:
     int res = optionProcess( opts, a_ct, a_v );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     opts        'tOptions *'   program options descriptor
                                
     a_ct        'int'          program arg count
                                
     a_v         'char **'      program arg vector
     returns     int            the count of the arguments processed

   This is the main entry point for processing options.  It is intended
that this procedure be called once at the beginning of the execution of
a program.  Depending on options selected earlier, it is sometimes
necessary to stop and restart option processing, or to select completely
different sets of options.  This can be done easily, but you generally
do not want to do this.

   The number of arguments processed always includes the program name.
If one of the arguments is "-", then it is counted and the processing
stops.  If an error was encountered and errors are to be tolerated, then
the returned value is the index of the argument causing the error.  A
hyphen by itself ("-") will also cause processing to stop and will _not_
be counted among the processed arguments.  A hyphen by itself is treated
as an operand.  Encountering an operand stops option processing.

   Errors will cause diagnostics to be printed.  'exit(3)' may or may
not be called.  It depends upon whether or not the options were
generated with the "allow-errors" attribute, or if the ERRSKIP_OPTERR or
ERRSTOP_OPTERR macros were invoked.

\1f
File: autogen.info,  Node: libopts-optionRestore,  Next: libopts-optionSaveFile,  Prev: libopts-optionProcess,  Up: libopts procedures

7.6.32.15 optionRestore
.......................

restore option state from memory copy

Usage:
     optionRestore( pOpts );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     pOpts       'tOptions *'   program options descriptor

   Copy back the option state from saved memory.  The allocated memory
is left intact, so this routine can be called repeatedly without having
to call optionSaveState again.  If you are restoring a state that was
saved before the first call to optionProcess(3AO), then you may change
the contents of the argc/argv parameters to optionProcess.

   If you have not called 'optionSaveState' before, a diagnostic is
printed to 'stderr' and exit is called.

\1f
File: autogen.info,  Node: libopts-optionSaveFile,  Next: libopts-optionSaveState,  Prev: libopts-optionRestore,  Up: libopts procedures

7.6.32.16 optionSaveFile
........................

saves the option state to a file

Usage:
     optionSaveFile( opts );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     opts        'tOptions *'   program options descriptor

   This routine will save the state of option processing to a file.  The
name of that file can be specified with the argument to the
'--save-opts' option, or by appending the 'rcfile' attribute to the last
'homerc' attribute.  If no 'rcfile' attribute was specified, it will
default to '.programnamerc'.  If you wish to specify another file, you
should invoke the 'SET_OPT_SAVE_OPTS(filename)' macro.

   The recommend usage is as follows:
     optionProcess(&progOptions, argc, argv);
     if (i_want_a_non_standard_place_for_this)
     SET_OPT_SAVE_OPTS("myfilename");
     optionSaveFile(&progOptions);

   If no 'homerc' file was specified, this routine will silently return
and do nothing.  If the output file cannot be created or updated, a
message will be printed to 'stderr' and the routine will return.

\1f
File: autogen.info,  Node: libopts-optionSaveState,  Next: libopts-optionUnloadNested,  Prev: libopts-optionSaveFile,  Up: libopts procedures

7.6.32.17 optionSaveState
.........................

saves the option state to memory

Usage:
     optionSaveState( pOpts );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     pOpts       'tOptions *'   program options descriptor

   This routine will allocate enough memory to save the current option
processing state.  If this routine has been called before, that memory
will be reused.  You may only save one copy of the option state.  This
routine may be called before optionProcess(3AO). If you do call it
before the first call to optionProcess, then you may also change the
contents of argc/argv after you call optionRestore(3AO)

   In fact, more strongly put: it is safest to only use this function
before having processed any options.  In particular, the saving and
restoring of stacked string arguments and hierarchical values is
disabled.  The values are not saved.

   If it fails to allocate the memory, it will print a message to stderr
and exit.  Otherwise, it will always succeed.

\1f
File: autogen.info,  Node: libopts-optionUnloadNested,  Next: libopts-optionVersion,  Prev: libopts-optionSaveState,  Up: libopts procedures

7.6.32.18 optionUnloadNested
............................

Deallocate the memory for a nested value

Usage:
     optionUnloadNested( pOptVal );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     pOptVal     'tOptionValue  the hierarchical value
                 const *'

   A nested value needs to be deallocated.  The pointer passed in should
have been gotten from a call to 'configFileLoad()' (See *note
libopts-configFileLoad::).

\1f
File: autogen.info,  Node: libopts-optionVersion,  Next: libopts-strequate,  Prev: libopts-optionUnloadNested,  Up: libopts procedures

7.6.32.19 optionVersion
.......................

return the compiled AutoOpts version number

Usage:
     char const * res = optionVersion();
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     returns     char const *   the version string in constant memory

   Returns the full version string compiled into the library.  The
returned string cannot be modified.

\1f
File: autogen.info,  Node: libopts-strequate,  Next: libopts-streqvcmp,  Prev: libopts-optionVersion,  Up: libopts procedures

7.6.32.20 strequate
...................

map a list of characters to the same value

Usage:
     strequate( ch_list );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     ch_list     'char const    characters to equivalence
                 *'

   Each character in the input string get mapped to the first character
in the string.  This function name is mapped to option_strequate so as
to not conflict with the POSIX name space.

   none.

\1f
File: autogen.info,  Node: libopts-streqvcmp,  Next: libopts-streqvmap,  Prev: libopts-strequate,  Up: libopts procedures

7.6.32.21 streqvcmp
...................

compare two strings with an equivalence mapping

Usage:
     int res = streqvcmp( str1, str2 );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     str1        'char const    first string
                 *'             
     str2        'char const    second string
                 *'
     returns     int            the difference between two differing
                                characters

   Using a character mapping, two strings are compared for
"equivalence".  Each input character is mapped to a comparison character
and the mapped-to characters are compared for the two NUL terminated
input strings.  This function name is mapped to option_streqvcmp so as
to not conflict with the POSIX name space.

   none checked.  Caller responsible for seg faults.

\1f
File: autogen.info,  Node: libopts-streqvmap,  Next: libopts-strneqvcmp,  Prev: libopts-streqvcmp,  Up: libopts procedures

7.6.32.22 streqvmap
...................

Set the character mappings for the streqv functions

Usage:
     streqvmap( from, to, ct );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     from        'char'         Input character
                                
     to          'char'         Mapped-to character
                                
     ct          'int'          compare length

   Set the character mapping.  If the count ('ct') is set to zero, then
the map is cleared by setting all entries in the map to their index
value.  Otherwise, the "'From'" character is mapped to the "'To'"
character.  If 'ct' is greater than 1, then 'From' and 'To' are
incremented and the process repeated until 'ct' entries have been set.
For example,
     streqvmap('a', 'A', 26);
will alter the mapping so that all English lower case letters will map
to upper case.

   This function name is mapped to option_streqvmap so as to not
conflict with the POSIX name space.

   none.

\1f
File: autogen.info,  Node: libopts-strneqvcmp,  Next: libopts-strtransform,  Prev: libopts-streqvmap,  Up: libopts procedures

7.6.32.23 strneqvcmp
....................

compare two strings with an equivalence mapping

Usage:
     int res = strneqvcmp( str1, str2, ct );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     str1        'char const    first string
                 *'             
     str2        'char const    second string
                 *'             
     ct          'int'          compare length
     returns     int            the difference between two differing
                                characters

   Using a character mapping, two strings are compared for
"equivalence".  Each input character is mapped to a comparison character
and the mapped-to characters are compared for the two NUL terminated
input strings.  The comparison is limited to 'ct' bytes.  This function
name is mapped to option_strneqvcmp so as to not conflict with the POSIX
name space.

   none checked.  Caller responsible for seg faults.

\1f
File: autogen.info,  Node: libopts-strtransform,  Prev: libopts-strneqvcmp,  Up: libopts procedures

7.6.32.24 strtransform
......................

convert a string into its mapped-to value

Usage:
     strtransform( dest, src );
Where the arguments are:
     Name        Type           Description
     ---         ---            ---------
     dest        'char *'       output string
                                
     src         'char const    input string
                 *'

   Each character in the input string is mapped and the mapped-to
character is put into the output.  This function name is mapped to
option_strtransform so as to not conflict with the POSIX name space.

   The source and destination may be the same.

   none.

\1f
File: autogen.info,  Node: Multi-Threading,  Next: option descriptor,  Prev: AutoOpts API,  Up: AutoOpts

7.7 Multi-Threading
===================

AutoOpts was designed to configure a program for running.  This
generally happens before much real work has been started.  Consequently,
it is expected to be run before multi-threaded applications have started
multiple threads.  However, this is not always the case.  Some
applications may need to reset and reload their running configuration,
and some may use 'SET_OPT_xxx()' macros during processing.  If you need
to dynamically change your option configuration in your multi-threaded
application, it is your responsibility to prevent all threads from
accessing the option configuration state, except the one altering the
configuration.

   The various accessor macros ('HAVE_OPT()', etc.)  do not modify state
and are safe to use in a multi-threaded application.  It is safe as long
as no other thread is concurrently modifying state, of course.

\1f
File: autogen.info,  Node: option descriptor,  Next: Using AutoOpts,  Prev: Multi-Threading,  Up: AutoOpts

7.8 Option Descriptor File
==========================

This is the module that is to be compiled and linked with your program.
It contains internal data and procedures subject to change.  Basically,
it contains a single global data structure containing all the
information provided in the option definitions, plus a number of static
strings and any callout procedures that are specified or required.  You
should never have need for looking at this, except, perhaps, to examine
the code generated for implementing the 'flag-code' construct.

\1f
File: autogen.info,  Node: Using AutoOpts,  Next: Presetting Options,  Prev: option descriptor,  Up: AutoOpts

7.9 Using AutoOpts
==================

There are actually several levels of 'using' autoopts.  Which you choose
depends upon how you plan to distribute (or not) your application.

* Menu:

* local use::               local-only use
* binary not installed::    binary distro, AutoOpts not installed
* binary pre-installed::    binary distro, AutoOpts pre-installed
* source pre-installed::    source distro, AutoOpts pre-installed
* source not installed::    source distro, AutoOpts not installed

\1f
File: autogen.info,  Node: local use,  Next: binary not installed,  Up: Using AutoOpts

7.9.1 local-only use
--------------------

To use AutoOpts in your application where you do not have to worry about
distribution issues, your issues are simple and few.

   * Create a file 'myopts.def', according to the documentation above.
     It is probably easiest to start with the example in *note Quick
     Start:: and edit it into the form you need.

   * Run AutoGen to create the option interface file ('myopts.h') and
     the option descriptor code ('myopts.c'):

          autogen myopts.def

   * In all your source files where you need to refer to option state,
     '#include "myopts.h"'.
   * In your main routine, code something along the lines of:

          #define ARGC_MIN some-lower-limit
          #define ARGC_MAX some-upper-limit
          main( int argc, char** argv )
          {
              {
                  int arg_ct = optionProcess( &myprogOptions, argc, argv );
                  argc -= arg_ct;
                  if ((argc < ARGC_MIN) || (argc > ARGC_MAX)) {
                      fprintf( stderr, "%s ERROR:  remaining args (%d) "
                               "out of range\n", myprogOptions.pzProgName,
                               argc );

                      USAGE( EXIT_FAILURE );
                  }
                  argv += arg_ct;
              }
              if (HAVE_OPT(OPTN_NAME))
                  respond_to_optn_name();
              ...
          }

   * Compile 'myopts.c' and link your program with the following
     additional arguments:

          `autoopts-config cflags ldflags` myopts.c

\1f
File: autogen.info,  Node: binary not installed,  Next: binary pre-installed,  Prev: local use,  Up: Using AutoOpts

7.9.2 binary distro, AutoOpts not installed
-------------------------------------------

If you will be distributing (or copying) your project to a system that
does not have AutoOpts installed, you will need to statically link the
AutoOpts library, 'libopts' into your program.  Get the link information
with 'static-libs' instead of 'ldflags':

     `autoopts-config static-libs`

\1f
File: autogen.info,  Node: binary pre-installed,  Next: source pre-installed,  Prev: binary not installed,  Up: Using AutoOpts

7.9.3 binary distro, AutoOpts pre-installed
-------------------------------------------

If you will be distributing (or copying) your project to a system that
does have AutoOpts (or only 'libopts') installed, you will still need to
ensure that the library is findable at program load time, or you will
still have to statically link.  The former can be accomplished by
linking your project with '--rpath' or by setting the 'LD_LIBRARY_PATH'
appropriately.  Otherwise, *Note binary not installed::.

\1f
File: autogen.info,  Node: source pre-installed,  Next: source not installed,  Prev: binary pre-installed,  Up: Using AutoOpts

7.9.4 source distro, AutoOpts pre-installed
-------------------------------------------

If you will be distributing your project to a system that will build
your product but it may not be pre-installed with AutoOpts, you will
need to do some configuration checking before you start the build.
Assuming you are willing to fail the build if AutoOpts has not been
installed, you will still need to do a little work.

   AutoOpts is distributed with a configuration check M4 script,
'autoopts.m4'.  It will add an 'autoconf' macro named,
'AG_PATH_AUTOOPTS'.  Add this to your 'configure.ac' script and use the
following substitution values:

'AUTOGEN'
     the name of the autogen executable
'AUTOGEN_TPLIB'
     the directory where AutoGen template library is stored
'AUTOOPTS_CFLAGS'
     the compile time options needed to find the AutoOpts headers
'AUTOOPTS_LIBS'
     the link options required to access the 'libopts' library

\1f
File: autogen.info,  Node: source not installed,  Prev: source pre-installed,  Up: Using AutoOpts

7.9.5 source distro, AutoOpts not installed
-------------------------------------------

If you will be distributing your project to a system that will build
your product but it may not be pre-installed with AutoOpts, you may wish
to incorporate the sources for 'libopts' in your project.  To do this, I
recommend reading the tear-off libopts library 'README' that you can
find in the 'pkg/libopts' directory.  You can also examine an example
package (blocksort) that incorporates this tear off library in the
autogen distribution directory.  There is also a web page that describes
what you need to do:
     <http://autogen.sourceforge.net/blocksort.html>

   Alternatively, you can pull the 'libopts' library sources into a
build directory and build it for installation along with your package.
This can be done approximately as follows:
     tar -xzvf `autoopts-config libsrc`
     cd libopts-*
     ./bootstrap
     configure
     make
     make install
   That will install the library, but not the headers or anything else.

\1f
File: autogen.info,  Node: Presetting Options,  Next: Config File Format,  Prev: Using AutoOpts,  Up: AutoOpts

7.10 Configuring your program
=============================

AutoOpts supports the notion of 'presetting' the value or state of an
option.  The values may be obtained either from environment variables or
from configuration files ('rc' or 'ini' files).  In order to take
advantage of this, the AutoOpts client program must specify these
features in the option descriptor file (*note program attributes::) with
the 'rcfile' or 'environrc' attributes.

* Menu:

* loading rcfile::      configuration file presets
* saving rcfile::       Saving the presets into a configuration file
* sample rcfile::       Creating a sample configuration file
* environrc::           environment variable presets
* config example::      Config file only example

   It is also possible to configure your program without using the
command line option parsing code.  This is done by using only the
following four functions from the 'libopts' library:

'configFileLoad'
     (*note libopts-configFileLoad::) will parse the contents of a
     config file and return a pointer to a structure representing the
     hierarchical value.  The values are sorted alphabetically by the
     value name and all entries with the same name will retain their
     original order.  Insertion sort is used.

'optionGetValue'
     (*note libopts-optionGetValue::) will find the first value within
     the hierarchy with a name that matches the name passed in.

'optionNextValue'
     (*note libopts-optionNextValue::) will return the next value that
     follows the value passed in as an argument.  If you wish to get all
     the values for a particular name, you must take note when the name
     changes.

'optionUnloadNested'
     (*note libopts-optionUnloadNested::).  The pointer passed in must
     be of type, 'OPARG_TYPE_HIERARCHY' (see the autoopts/options.h
     header file).  'configFileLoad' will return a 'tOptionValue'
     pointer of that type.  This function will release all the
     associated memory.  'AutoOpts' generated code uses this function
     for its own needs.  Client code should only call this function with
     pointers gotten from 'configFileLoad'.

\1f
File: autogen.info,  Node: loading rcfile,  Next: saving rcfile,  Up: Presetting Options

7.10.1 configuration file presets
---------------------------------

Configuration files are enabled by specifying the program attribute
'homerc' (*note program attributes::).  Any option not marked with the
'no-preset' attribute may appear in a configuration file.  The files
loaded are selected both by the 'homerc' entries and, optionally, via a
command line option.  The first component of the 'homerc' entry may be
an environment variable such as '$HOME', or it may also be '$$' (*two*
dollar sign characters) to specify the directory of the executable.  For
example:

     homerc = "$$/../share/autogen";

will cause the AutoOpts library to look in the normal autogen datadir
relative to the current installation directory for autogen.

   The configuration files are processed in the order they are specified
by the 'homerc' attribute, so that each new file will normally override
the settings of the previous files.  This may be overridden by marking
some options for 'immediate action' (*note Immediate Action::).  Any
such options are acted upon in *reverse* order.  The disabled
'load-opts' ('--no-load-opts') option, for example, is an immediate
action option.  Its presence in the last 'homerc' file will prevent the
processing of any prior 'homerc' files because its effect is immediate.

   Configuration file processing can be completely suppressed by
specifying '--no-load-opts' on the command line, or
'PROGRAM_LOAD_OPTS=no' in the environment (if 'environrc' has been
specified).

   See the 'Configuration File Format' section (*note Config File
Format::) for details on the format of the file.

\1f
File: autogen.info,  Node: saving rcfile,  Next: sample rcfile,  Prev: loading rcfile,  Up: Presetting Options

7.10.2 Saving the presets into a configuration file
---------------------------------------------------

When configuration files are enabled for an application, the user is
also provided with an automatically supplied '--save-opts' option.  All
of the known option state will be written to either the specified output
file or, if it is not specified, then to the last specified 'homerc'
file.

\1f
File: autogen.info,  Node: sample rcfile,  Next: environrc,  Prev: saving rcfile,  Up: Presetting Options

7.10.3 Creating a sample configuration file
-------------------------------------------

AutoOpts is shipped with a template named, 'rc-sample.tpl'.  If your
option definition file specifies the 'homerc' attribute, then you may
invoke 'autogen' thus:

     autogen -Trc-sample <your-option-def-file>

   This will, by default, produce a sample file named,
'sample-<prog-name>rc'.  It will be named differently if you specify
your configuration (rc) file name with the 'rcfile' attribute.  In that
case, the output file will be named, 'sample-<rcfile-name>'.  It will
contain all of the program options not marked as 'no-preset'.  It will
also include the text from the 'doc' attribute.

Doing so with getdefs' option definitions yields this sample-getdefsrc
file.  I tend to be wordy in my 'doc' attributes:

     # getdefs sample configuration file
     ## This source file is copyrighted and licensed under the following terms:
     #
     #  Copyright (C) 1999-2018 Bruce Korb, all rights reserved.
     #  This is free software. It is licensed for use, modification and
     #  redistribution under the terms of the GNU General Public License,
     #  version 3 or later <http://gnu.org/licenses/gpl.html>
     #
     #  getdefs 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.
     #
     #  getdefs 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 <http://www.gnu.org/licenses/>.

     # defs_to_get -- Regexp to look for after the "/*="
     #
     #
     #
     #
     # If you want definitions only from a particular category, or even
     # with names matching particular patterns, then specify this regular
     # expression for the text that must follow the @code{/*=}.
     # Example:
     #
     #defs_to_get       reg-ex

     # subblock -- subblock definition names
     #
     #
     #
     #
     # This option is used to create shorthand entries for nested definitions.
     # For example, with:
     # @table @r
     # @item using subblock thus
     # @code{--subblock=arg=argname,type,null}
     # @item and defining an @code{arg} thus
     # @code{arg: this, char *}
     # @item will then expand to:
     # @code{arg = @{ argname = this; type = "char *"; @};}
     # @end table
     # The "this, char *" string is separated at the commas, with the
     # white space removed.  You may use characters other than commas by
     # starting the value string with a punctuation character other than
     # a single or double quote character.  You may also omit intermediate
     # values by placing the commas next to each other with no intervening
     # white space.  For example, "+mumble++yes+" will expand to:
     # @*
     # @code{arg = @{ argname = mumble; null = "yes"; @};}.
     # Example:
     #
     #subblock  sub-def

     # listattr -- attribute with list of values
     #
     #
     #
     #
     # This option is used to create shorthand entries for definitions
     # that generally appear several times.  That is, they tend to be
     # a list of values.  For example, with:
     # @*
     # @code{listattr=foo} defined, the text:
     # @*
     # @code{foo: this, is, a, multi-list} will then expand to:
     # @*
     # @code{foo = 'this', 'is', 'a', 'multi-list';}
     # @*
     # The texts are separated by the commas, with the
     # white space removed.  You may use characters other than commas by
     # starting the value string with a punctuation character other than
     # a single or double quote character.
     # Example:
     #
     #listattr  def

     # ordering -- Alphabetize or use named file
     #
     #
     #
     #
     # By default, ordering is alphabetical by the entry name.  Use,
     # @code{no-ordering} if order is unimportant.  Use @code{ordering}
     # with no argument to order without case sensitivity.  Use
     # @code{ordering=<file-name>} if chronological order is important.
     # getdefs will maintain the text content of @code{file-name}.
     # @code{file-name} need not exist.
     # Example:
     #
     #ordering  file-name

     # first_index -- The first index to apply to groups
     #
     # This configuration value takes an integer number as its argument.
     #
     #
     # By default, the first occurrence of a named definition will have an
     # index of zero.  Sometimes, that needs to be a reserved value.  Provide
     # this option to specify a different starting point.
     # Example:
     #
     #first_index       0

     # filelist -- Insert source file names into defs
     #
     #
     #
     #
     # Inserts the name of each input file into the output definitions.
     # If no argument is supplied, the format will be:
     # @example
     # infile = '%s';
     # @end example
     # If an argument is supplied, that string will be used for the entry
     # name instead of @var{infile}.
     # Example:
     #
     #filelist  file

     # assign -- Global assignments
     #
     #
     #
     #
     # The argument to each copy of this option will be inserted into
     # the output definitions, with only a semicolon attached.
     # Example:
     #
     #assign    ag-def

     # common_assign -- Assignments common to all blocks
     #
     #
     #
     #
     # The argument to each copy of this option will be inserted into
     # each output definition, with only a semicolon attached.
     # Example:
     #
     #common_assign     ag-def

     # copy -- File(s) to copy into definitions
     #
     #
     #
     #
     # The content of each file named by these options will be inserted into
     # the output definitions.
     # Example:
     #
     #copy      file

     # srcfile -- Insert source file name into each def
     #
     #
     #
     #
     # Inserts the name of the input file where a definition was found
     # into the output definition.
     # If no argument is supplied, the format will be:
     # @example
     # srcfile = '%s';
     # @end example
     # If an argument is supplied, that string will be used for the entry
     # name instead of @var{srcfile}.
     # Example:
     #
     #srcfile   file

     # linenum -- Insert source line number into each def
     #
     #
     #
     #
     # Inserts the line number in the input file where a definition
     # was found into the output definition.
     # If no argument is supplied, the format will be:
     # @example
     # linenum = '%s';
     # @end example
     # If an argument is supplied, that string will be used for the entry
     # name instead of @var{linenum}.
     # Example:
     #
     #linenum   def-name

     # input -- Input file to search for defs
     #
     #
     #
     #
     # All files that are to be searched for definitions must be named on
     # the command line or read from @code{stdin}.  If there is only one
     # @code{input} option and it is the string, "-", then the input file
     # list is read from @code{stdin}.  If a command line argument is not
     # an option name and does not contain an assignment operator
     # (@code{=}), then it defaults to being an input file name.
     # At least one input file must be specified.
     # Example:
     #
     #input     src-file

     # output -- Output file to open
     #
     #
     #
     #
     # If you are not sending the output to an AutoGen process,
     # you may name an output file instead.
     # Example:
     #
     #output    file

     # autogen -- Invoke AutoGen with defs
     #
     #
     #
     #
     # This is the default output mode.  Specifying @code{no-autogen} is
     # equivalent to @code{output=-}.  If you supply an argument to this
     # option, that program will be started as if it were AutoGen and
     # its standard in will be set to the output definitions of this program.
     # Example:
     #
     #autogen   ag-cmd

     # template -- Template Name
     #
     #
     #
     #
     # Specifies the template name to be used for generating the final output.
     # Example:
     #
     #template  file

     # agarg -- AutoGen Argument
     #
     #
     #
     #
     # This is a pass-through argument.  It allows you to specify any
     # arbitrary argument to be passed to AutoGen.
     # Example:
     #
     #agarg     ag-opt

     # base_name -- Base name for output file(s)
     #
     #
     #
     #
     # When output is going to AutoGen, a base name must either be supplied
     # or derived.  If this option is not supplied, then it is taken from
     # the @code{template} option.  If that is not provided either, then
     # it is set to the base name of the current directory.
     # Example:
     #
     #base_name name

\1f
File: autogen.info,  Node: environrc,  Next: config example,  Prev: sample rcfile,  Up: Presetting Options

7.10.4 environment variable presets
-----------------------------------

If the AutoOpts client program specifies 'environrc' in its option
descriptor file, then environment variables will be used for presetting
option state.  Variables will be looked for that are named,
'PROGRAM_OPTNAME' and 'PROGRAM'.  'PROGRAM' is the upper cased 'C-name'
of the program, and OPTNAME is the upper cased 'C-name' of a specific
option.  (The 'C-name's are the regular names with all special
characters converted to underscores ('_').)

   Option specific environment variables are processed after (and thus
take precedence over) the contents of the 'PROGRAM' environment
variable.  The option argument string for these options takes on the
string value gotten from the environment.  Consequently, you can only
have one instance of the OPTNAME.

   If a particular option may be disabled, then its disabled state is
indicated by setting the 'PROGRAM_OPTNAME' 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'.  *Note Common Attributes::.

   The 'PROGRAM' environment string is tokenized and parsed much like a
command line.  Doubly quoted strings have backslash escapes processed
the same way they are processed in C program constant strings.  Singly
quoted strings are pretty raw in that backslashes are honored before
other backslashes, apostrophes, newlines and cr/newline pairs.  The
options must be introduced with hyphens in the same way as the command
line.

   Note that not all options may be preset.  Options that are specified
with the 'no-preset' attribute and the '--help', '--more-help', and
'--save-opts' auto-supported options may not be preset.

\1f
File: autogen.info,  Node: config example,  Prev: environrc,  Up: Presetting Options

7.10.5 Config file only example
-------------------------------

If for some reason it is difficult or unworkable to integrate
configuration file processing with command line option parsing, the
'libopts' (*note libopts procedures::) library can still be used to
process configuration files.  Below is a Hello, World! greeting program
that tries to load a configuration file 'hello.conf' to see if it should
use an alternate greeting or to personalize the salutation.
     #include <config.h>
     #include <sys/types.h>
     #include <stdio.h>
     #include <pwd.h>
     #include <string.h>
     #ifdef   HAVE_UNISTD_H
     #include <unistd.h>
     #endif
     #include <autoopts/options.h>
     int main(int argc, char ** argv) {
       char const * greeting = "Hello";
       char const * greeted  = "World";
       tOptionValue const * pOV = configFileLoad("hello.conf");

       if (pOV != NULL) {
         const tOptionValue* pGetV = optionGetValue(pOV, "greeting");

         if (  (pGetV != NULL)
            && (pGetV->valType == OPARG_TYPE_STRING))
           greeting = strdup(pGetV->v.strVal);

         pGetV = optionGetValue(pOV, "personalize");
         if (pGetV != NULL) {
           struct passwd * pwe = getpwuid(getuid());
           if (pwe != NULL)
             greeted = strdup(pwe->pw_gecos);
         }

         optionUnloadNested(pOV); /* deallocate config data */
       }
       printf("%s, %s!\n", greeting, greeted);
       return 0;
     }

With that text in a file named "hello.c", this short script:

     cc -o hello hello.c `autoopts-config cflags ldflags`
     ./hello
     echo 'greeting Buzz off' > hello.conf
     ./hello
     echo personalize > hello.conf
     ./hello

will produce the following output:

     Hello, World!
     Buzz off, World!
     Hello, Bruce Korb,,,!

\1f
File: autogen.info,  Node: Config File Format,  Next: shell options,  Prev: Presetting Options,  Up: AutoOpts

7.11 Configuration File Format
==============================

The configuration file is designed to associate names and values, much
like an AutoGen Definition File (*note Definitions File::).
Unfortunately, the file formats are different.  Specifically, AutoGen
Definitions provide for simpler methods for the precise control of a
value string and provides for dynamically computed content.
Configuration files have some established traditions in their layout.
So, they are different, even though they do both allow for a single name
to be associated with multiple values and they both allow for
hierarchical values.

* Menu:

* config name/string-value::    assigning a string value to a configurable
* config integer-values::       integer values
* config nested-values::        hierarchical values
* config directives::           configuration file directives
* config comments::             comments in the configuration file

\1f
File: autogen.info,  Node: config name/string-value,  Next: config integer-values,  Up: Config File Format

7.11.1 assigning a string value to a configurable
-------------------------------------------------

The basic syntax is a name followed by a value on a single line.  They
are separated from each other by either white space, a colon (':') or an
equal sign ('=').  The colon or equal sign may optionally be surrounded
by additional white space.  If more than one value line is needed, a
backslash ('\') may be used to continue the value.  The backslash (but
not the newline) will be erased.  Leading and trailing white space is
always stripped from the value.

   Fundamentally, it looks like this:

     name  value for that name
     name = another \
          multi-line value \
          for that name.
     name: a *third* value for name

   If you need more control over the content of the value, you may
enclose the value in XML style brackets:
     <name>value </name>
Within these brackets you need not (must not) continue the value data
with backslashes.  You may also select the string formation rules to
use, just add the attribute after the name, thus: '<name keep>'.

'keep'
     This mode will keep all text between the brackets and not strip any
     white space.
'uncooked'
     This mode strips leading and trailing white space, but not do any
     quote processing.  This is the default and need not be specified.
'cooked'
     The text is trimmed of leading and trailing white space and XML
     encodings are processed.  These encodings are slightly expanded
     over the XML specification.  They are specified with an ampersand
     followed by a value name or numeric value and then a semicolon:

     'amp'
     'lt'
     'gt'
     'quot'
     'apos'
     '#dd'
     '#xHH'

          These are all per fairly standad HTML and/or XML encodings.
          Additionally:

     'bs'
          The ASCII back space character.
     'ff'
          The ASCII form feed character.
     'ht'
          The ASCII horizontal (normal) tab character.
     'cr'
          The ASCII carriage return character.
     'vt'
          The ASCII vertical tab character.
     'bel'
          The ASCII alarm bell character.
     'nl'
          The ASCII new line character.
     'space'
          The ASCII space character.  Normally not necessary, but if you
          want to preserve leading or trailing space characters, then
          use this.

   And here is an example of an XML-styled value:

     <name cooked>
         This is&nl;&ht;another multi-line
     &ht;string example.
     </name>

   The string value associated with 'name' will be exactly the text
enclosed in quotes with the encoded characters 'cooked' as you would
expect (three text lines with the last line not ending with a newline,
but ending with a period).

\1f
File: autogen.info,  Node: config integer-values,  Next: config nested-values,  Prev: config name/string-value,  Up: Config File Format

7.11.2 integer values
---------------------

A name can be specified as having an integer value.  To do this, you
must use the XML-ish format and specify a 'type' attribute for the name:

     <name type=integer> 1234 </name>

   Boolean, enumeration and set membership types will be added as time
allows.  'type=string' is also supported, but also is the default.

\1f
File: autogen.info,  Node: config nested-values,  Next: config directives,  Prev: config integer-values,  Up: Config File Format

7.11.3 hierarchical values
--------------------------

In order to specify a hierarchical value, you *must* use XML-styled
formatting, specifying a type that is shorter and easier to spell:

     <structured-name type=nested>
         [[....]]
     </structured-name>

The ellipsis may be filled with any legal configuration file name/value
assignments.

\1f
File: autogen.info,  Node: config directives,  Next: config comments,  Prev: config nested-values,  Up: Config File Format

7.11.4 configuration file directives
------------------------------------

The '<?' marker indicates an XML directive.  There is only one directive
supported: program sectioning, though two syntaxes are supported.

   If, for example, you have a collection of programs that work closely
together and, likely, have a common set of options, these programs may
use a single, sectioned, configuration file.  The file may be sectioned
in either of two ways.  The two ways may not be intermixed in a single
configuration file.  All text before the first segmentation line is
processed, then only the segment that applies:

'<?auto-options ...>'
     The '...' ellipsis may contain AutoOpts option processing options.
     Currently, that consists of one or both of:

     'gnu'
     'autoopts'
          to indicate GNU-standard or AutoOpts-standard layout of usage
          and version information, and/or

     'misuse-usage'
     'no-misuse-usage'
          to indicate whether the available options should be listed
          when an invalid option appears on the command line.
     Anything else will be silently ignored.

'<?program prog-name>'
     The '<?' marker indicates an XML directive.  The file is
     partitioned by these lines and the options are processed for the
     'prog-name' program only before the first '<?program' directive and
     the program section with a matching program name.

'[PROG_NAME]'
     This is basically an alias for '<?program prog-name>', except that
     the program name must be upper cased and segmented only with
     underscores and it is *not* recognized as a program segment when
     updating configuration files with the '--save-opts' option.  In
     other words, use this only for Windows compatibility.

Segmentation does not apply if the config file is being parsed with the
'configFileLoad(3AutoOpts)' function.

\1f
File: autogen.info,  Node: config comments,  Prev: config directives,  Up: Config File Format

7.11.5 comments in the configuration file
-----------------------------------------

Comments are lines beginning with a hash mark ('#'), XML-style comments
('<!-- arbitrary text -->'), and unrecognized XML directives.

     # this is a comment
     <!-- this is also
          a comment -->
     <?this is
       a bad comment ;->

\1f
File: autogen.info,  Node: shell options,  Next: AutoInfo,  Prev: Config File Format,  Up: AutoOpts

7.12 AutoOpts for Shell Scripts
===============================

AutoOpts may be used with shell scripts either by automatically creating
a complete program that will process command line options and pass back
the results to the invoking shell by issuing shell variable assignment
commands, or it may be used to generate portable shell code that can be
inserted into your script.

   The functionality of these features, of course, is somewhat
constrained compared with the normal program facilities.  Specifically,
you cannot invoke callout procedures with either of these methods.
Additionally, if you generate a shell script to do the parsing:

  1. You cannot obtain options from configuration files.
  2. You cannot obtain options from environment variables.
  3. You cannot save the option state to an option file.
  4. Option conflict/requirement verification is disabled.

   Both of these methods are enabled by running AutoGen on the
definitions file with the additional main procedure attribute:

     main = { main-type = shell-process; };
or:
     main = { main-type = shell-parser; };

   If you do not supply a 'proc-to-call', it will default to
'optionPutShell'.  That will produce a program that will process the
options and generate shell text for the invoking shell to interpret
(*note binary-parser::).  If you supply the name, 'optionParseShell',
then you will have a program that will generate a shell script that can
parse the options (*note script-parser::).  If you supply a different
procedure name, you will have to provide that routine and it may do
whatever you like.

* Menu:

* binary-parser::        Parsing with an Executable
* script-parser::        Parsing with a Portable Script

\1f
File: autogen.info,  Node: binary-parser,  Next: script-parser,  Up: shell options

7.12.1 Parsing with an Executable
---------------------------------

The following commands are approximately all that is needed to build a
shell script command line option parser from an option definition file:

     autogen -L <opt-template-dir> test-errors.def
     cc -o test-errors -L <opt-lib-dir> -I <opt-include-dir> \
             -DTEST_PROGRAM_OPTS test-errors.c -lopts

   The resulting program can then be used within your shell script as
follows:

     eval `./test-errors "$@"`
     if [ -z "${OPTION_CT}" ] ; then exit 1 ; fi
     test ${OPTION_CT} -gt 0 && shift ${OPTION_CT}

   Here is the usage output example from AutoOpts error handling tests.
The option definition has argument reordering enabled:

     test_errors - Test AutoOpts for errors
     Usage:  errors [ -<flag> [<val>] | --<name>[{=| }<val>] ]... arg ...
       Flg Arg Option-Name    Description
        -o no  option         The option option descrip
        -s Str second         The second option descrip
                                     - may appear up to 10 times
        -i --- ignored        we have dumped this
        -X no  another        Another option descrip
                                     - may appear up to 5 times
        -? no  help           display extended usage information and exit
        -! no  more-help      extended usage information passed thru pager
        -> opt save-opts      save the option state to a config file
        -< Str load-opts      load options from a config file
                                     - disabled as '--no-load-opts'
                                     - may appear multiple times

     Options are specified by doubled hyphens and their name or by a single
     hyphen and the flag character.
     Operands and options may be intermixed.  They will be reordered.

     The following option preset mechanisms are supported:
      - reading file errorsRC

   Using the invocation,
       test-errors operand1 -s first operand2 -X -- -s operand3
   you get the following output for your shell script to evaluate:

     OPTION_CT=4
     export OPTION_CT
     TEST_ERRORS_SECOND='first'
     export TEST_ERRORS_SECOND
     TEST_ERRORS_ANOTHER=1 # 0x1
     export TEST_ERRORS_ANOTHER
     set -- 'operand1' 'operand2' '-s' 'operand3'
     OPTION_CT=0

\1f
File: autogen.info,  Node: script-parser,  Prev: binary-parser,  Up: shell options

7.12.2 Parsing with a Portable Script
-------------------------------------

If you had used 'test-main = optionParseShell' instead, then you can, at
this point, merely run the program and it will write the parsing script
to standard out.  You may also provide this program with command line
options to specify the shell script file to create or edit, and you may
specify the shell program to use on the first shell script line.  That
program's usage text would look something like the following and the
script parser itself would be very verbose:

     genshellopt - Generate Shell Option Processing Script - Ver. 1
     Usage:  genshellopt [ -<flag> [<val>] | --<name>[{=| }<val>] ]...
       Flg Arg Option-Name    Description
        -o Str script         Output Script File
        -s Str shell          Shell name (follows "#!" magic)
                                     - disabled as '--no-shell'
                                     - enabled by default
        -v opt version        output version information and exit
        -? no  help           display extended usage information and exit
        -! no  more-help      extended usage information passed thru pager

     Options are specified by doubled hyphens and their name or by a single
     hyphen and the flag character.
     Note that 'shell' is only useful if the output file does not already exist.
     If it does, then the shell name and optional first argument will be
     extracted from the script file.
     If the script file already exists and contains Automated Option Processing
     text, the second line of the file through the ending tag will be replaced
     by the newly generated text.  The first '#!' line will be regenerated.

     Please send bug reports to:  <autogen-users@lists.sourceforge.net>

     = = = = = = = =

     This incarnation of genshell will produce
     a shell script to parse the options for getdefs:

     getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5
     Usage:  getdefs [ <option-name>[{=| }<val>] ]...
        Arg Option-Name    Description
        Str defs-to-get    Regexp to look for after the "/*="
        Str subblock       subblock definition names
        Str listattr       attribute with list of values
        opt ordering       Alphabetize or use named file
        Num first-index    The first index to apply to groups
        opt filelist       Insert source file names into defs
        Str assign         Global assignments
        Str common-assign  Assignments common to all blocks
        Str copy           File(s) to copy into definitions
        opt srcfile        Insert source file name into each def
        opt linenum        Insert source line number into each def
        Str input          Input file to search for defs
        Str output         Output file to open
        opt autogen        Invoke AutoGen with defs
        Str template       Template Name
        Str agarg          AutoGen Argument
        Str base-name      Base name for output file(s)

Resulting in the following script:
     #! /bin/sh
     # # # # # # # # # # -- do not modify this marker --
     #
     #  DO NOT EDIT THIS SECTION
      OF /u/bkorb/tools/ag/autogen-bld/doc/ag-texi-32340.d/.ag-5GQlKL/genshellopt.sh
     #
     #  From here to the next `-- do not modify this marker --',
     #  the text has been generated Sunday August 26, 2018 at 10:46:02 AM PDT
     #  From the GETDEFS option definitions
     #
     GETDEFS_LONGUSAGE_TEXT='getdefs error:  invalid option descriptor for version
     getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5
     Usage:  getdefs [ <option-name>[{=| }<val>] ]...

     Specify which definitions are of interest and what to say about them:

        Arg Option-Name    Description
        Str defs-to-get    Regexp to look for after the "/*="
        Str subblock       subblock definition names
                                     - may appear multiple times
        Str listattr       attribute with list of values
                                     - may appear multiple times

     specify how to number the definitions:

        Arg Option-Name    Description
        opt ordering       Alphabetize or use named file
                                     - disabled as '\''--no-ordering'\''
                                     - enabled by default
        Num first-index    The first index to apply to groups

     Definition insertion options:

        Arg Option-Name    Description
        opt filelist       Insert source file names into defs
        Str assign         Global assignments
                                     - may appear multiple times
        Str common-assign  Assignments common to all blocks
                                     - may appear multiple times
        Str copy           File(s) to copy into definitions
                                     - may appear multiple times
        opt srcfile        Insert source file name into each def
        opt linenum        Insert source line number into each def

     specify which files to search for markers:

        Arg Option-Name    Description
        Str input          Input file to search for defs
                                     - may appear multiple times
                                     - default option for unnamed options

     Definition output disposition options::

        Arg Option-Name    Description
        Str output         Output file to open
                                     - an alternate for '\''autogen'\''
        opt autogen        Invoke AutoGen with defs
                                     - disabled as '\''--no-autogen'\''
                                     - enabled by default
        Str template       Template Name
        Str agarg          AutoGen Argument
                                     - prohibits the option '\''output'\''
                                     - may appear multiple times
        Str base-name      Base name for output file(s)
                                     - prohibits the option '\''output'\''

     Version, usage and configuration options:

        Arg Option-Name    Description
       '

     GETDEFS_USAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5
     Usage:  getdefs [ <option-name>[{=| }<val>] ]...
        Arg Option-Name    Description
        Str defs-to-get    Regexp to look for after the "/*="
        Str subblock       subblock definition names
        Str listattr       attribute with list of values
        opt ordering       Alphabetize or use named file
        Num first-index    The first index to apply to groups
        opt filelist       Insert source file names into defs
        Str assign         Global assignments
        Str common-assign  Assignments common to all blocks
        Str copy           File(s) to copy into definitions
        opt srcfile        Insert source file name into each def
        opt linenum        Insert source line number into each def
        Str input          Input file to search for defs
        Str output         Output file to open
        opt autogen        Invoke AutoGen with defs
        Str template       Template Name
        Str agarg          AutoGen Argument
        Str base-name      Base name for output file(s)
       getdefs error:  invalid option descriptor for version'


     GETDEFS_DEFS_TO_GET=${GETDEFS_DEFS_TO_GET}
     GETDEFS_DEFS_TO_GET_set=false
     export GETDEFS_DEFS_TO_GET

     if test -z "${GETDEFS_SUBBLOCK}"
     then
       GETDEFS_SUBBLOCK_CT=0
       export GETDEFS_SUBBLOCK_CT
     else
       GETDEFS_SUBBLOCK_CT=1
       GETDEFS_SUBBLOCK_1=${GETDEFS_SUBBLOCK}
       export GETDEFS_SUBBLOCK_CT GETDEFS_SUBBLOCK_1
     fi

     if test -z "${GETDEFS_LISTATTR}"
     then
       GETDEFS_LISTATTR_CT=0
       export GETDEFS_LISTATTR_CT
     else
       GETDEFS_LISTATTR_CT=1
       GETDEFS_LISTATTR_1=${GETDEFS_LISTATTR}
       export GETDEFS_LISTATTR_CT GETDEFS_LISTATTR_1
     fi

     GETDEFS_ORDERING=${GETDEFS_ORDERING}
     GETDEFS_ORDERING_set=false
     export GETDEFS_ORDERING

     GETDEFS_FIRST_INDEX=${GETDEFS_FIRST_INDEX-'0'}
     GETDEFS_FIRST_INDEX_set=false
     export GETDEFS_FIRST_INDEX

     GETDEFS_FILELIST=${GETDEFS_FILELIST}
     GETDEFS_FILELIST_set=false
     export GETDEFS_FILELIST

     if test -z "${GETDEFS_ASSIGN}"
     then
       GETDEFS_ASSIGN_CT=0
       export GETDEFS_ASSIGN_CT
     else
       GETDEFS_ASSIGN_CT=1
       GETDEFS_ASSIGN_1=${GETDEFS_ASSIGN}
       export GETDEFS_ASSIGN_CT GETDEFS_ASSIGN_1
     fi

     if test -z "${GETDEFS_COMMON_ASSIGN}"
     then
       GETDEFS_COMMON_ASSIGN_CT=0
       export GETDEFS_COMMON_ASSIGN_CT
     else
       GETDEFS_COMMON_ASSIGN_CT=1
       GETDEFS_COMMON_ASSIGN_1=${GETDEFS_COMMON_ASSIGN}
       export GETDEFS_COMMON_ASSIGN_CT GETDEFS_COMMON_ASSIGN_1
     fi

     if test -z "${GETDEFS_COPY}"
     then
       GETDEFS_COPY_CT=0
       export GETDEFS_COPY_CT
     else
       GETDEFS_COPY_CT=1
       GETDEFS_COPY_1=${GETDEFS_COPY}
       export GETDEFS_COPY_CT GETDEFS_COPY_1
     fi

     GETDEFS_SRCFILE=${GETDEFS_SRCFILE}
     GETDEFS_SRCFILE_set=false
     export GETDEFS_SRCFILE

     GETDEFS_LINENUM=${GETDEFS_LINENUM}
     GETDEFS_LINENUM_set=false
     export GETDEFS_LINENUM

     if test -z "${GETDEFS_INPUT}"
     then
       GETDEFS_INPUT_CT=0
       export GETDEFS_INPUT_CT
     else
       GETDEFS_INPUT_CT=1
       GETDEFS_INPUT_1=${GETDEFS_INPUT}
       export GETDEFS_INPUT_CT GETDEFS_INPUT_1
     fi

     GETDEFS_OUTPUT=${GETDEFS_OUTPUT}
     GETDEFS_OUTPUT_set=false
     export GETDEFS_OUTPUT

     GETDEFS_AUTOGEN=${GETDEFS_AUTOGEN}
     GETDEFS_AUTOGEN_set=false
     export GETDEFS_AUTOGEN

     GETDEFS_TEMPLATE=${GETDEFS_TEMPLATE}
     GETDEFS_TEMPLATE_set=false
     export GETDEFS_TEMPLATE

     if test -z "${GETDEFS_AGARG}"
     then
       GETDEFS_AGARG_CT=0
       export GETDEFS_AGARG_CT
     else
       GETDEFS_AGARG_CT=1
       GETDEFS_AGARG_1=${GETDEFS_AGARG}
       export GETDEFS_AGARG_CT GETDEFS_AGARG_1
     fi

     GETDEFS_BASE_NAME=${GETDEFS_BASE_NAME}
     GETDEFS_BASE_NAME_set=false
     export GETDEFS_BASE_NAME

     ARG_COUNT=$#
     OPT_ARG=$1
     while [ $# -gt 0 ]
     do
         OPT_ELEMENT=''
         OPT_ARG_VAL=''
         OPT_ARG=${1}
             OPT_CODE=`echo "X${OPT_ARG}"|sed 's/^X-*//'`
             shift
             OPT_ARG=$1
             case "${OPT_CODE}" in *=* )
                 OPT_ARG_VAL=`echo "${OPT_CODE}"|sed 's/^[^=]*=//'`
                 OPT_CODE=`echo "${OPT_CODE}"|sed 's/=.*$//'` ;; esac
             case "${OPT_CODE}" in
             'de' | \
             'def' | \
             'defs' | \
             'defs-' | \
             'defs-t' | \
             'defs-to' | \
             'defs-to-' | \
             'defs-to-g' | \
             'defs-to-ge' | \
             'defs-to-get' )
                 if [ -n "${GETDEFS_DEFS_TO_GET}" ] && ${GETDEFS_DEFS_TO_GET_set} ; then
                     echo 'Error:  duplicate DEFS_TO_GET option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_DEFS_TO_GET_set=true
                 OPT_NAME='DEFS_TO_GET'
                 OPT_ARG_NEEDED=YES
                 ;;

             'su' | \
             'sub' | \
             'subb' | \
             'subbl' | \
             'subblo' | \
             'subbloc' | \
             'subblock' )
                 GETDEFS_SUBBLOCK_CT=`expr ${GETDEFS_SUBBLOCK_CT} + 1`
                 OPT_ELEMENT="_${GETDEFS_SUBBLOCK_CT}"
                 OPT_NAME='SUBBLOCK'
                 OPT_ARG_NEEDED=YES
                 ;;

             'li' | \
             'lis' | \
             'list' | \
             'lista' | \
             'listat' | \
             'listatt' | \
             'listattr' )
                 GETDEFS_LISTATTR_CT=`expr ${GETDEFS_LISTATTR_CT} + 1`
                 OPT_ELEMENT="_${GETDEFS_LISTATTR_CT}"
                 OPT_NAME='LISTATTR'
                 OPT_ARG_NEEDED=YES
                 ;;

             'or' | \
             'ord' | \
             'orde' | \
             'order' | \
             'orderi' | \
             'orderin' | \
             'ordering' )
                 if [ -n "${GETDEFS_ORDERING}" ] && ${GETDEFS_ORDERING_set} ; then
                     echo 'Error:  duplicate ORDERING option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_ORDERING_set=true
                 OPT_NAME='ORDERING'
                 eval GETDEFS_ORDERING${OPT_ELEMENT}=true
                 export GETDEFS_ORDERING${OPT_ELEMENT}
                 OPT_ARG_NEEDED=OK
                 ;;

             'no-' | \
             'no-o' | \
             'no-or' | \
             'no-ord' | \
             'no-orde' | \
             'no-order' | \
             'no-orderi' | \
             'no-orderin' | \
             'no-ordering' )
                 if [ -n "${GETDEFS_ORDERING}" ] && ${GETDEFS_ORDERING_set} ; then
                     echo 'Error:  duplicate ORDERING option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_ORDERING_set=true
                 GETDEFS_ORDERING='no'
                 export GETDEFS_ORDERING
                 OPT_NAME='ORDERING'
                 OPT_ARG_NEEDED=NO
                 ;;

             'fi' | \
             'fir' | \
             'firs' | \
             'first' | \
             'first-' | \
             'first-i' | \
             'first-in' | \
             'first-ind' | \
             'first-inde' | \
             'first-index' )
                 if [ -n "${GETDEFS_FIRST_INDEX}" ] && ${GETDEFS_FIRST_INDEX_set} ; then
                     echo 'Error:  duplicate FIRST_INDEX option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_FIRST_INDEX_set=true
                 OPT_NAME='FIRST_INDEX'
                 OPT_ARG_NEEDED=YES
                 ;;

             'fi' | \
             'fil' | \
             'file' | \
             'filel' | \
             'fileli' | \
             'filelis' | \
             'filelist' )
                 if [ -n "${GETDEFS_FILELIST}" ] && ${GETDEFS_FILELIST_set} ; then
                     echo 'Error:  duplicate FILELIST option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_FILELIST_set=true
                 OPT_NAME='FILELIST'
                 eval GETDEFS_FILELIST${OPT_ELEMENT}=true
                 export GETDEFS_FILELIST${OPT_ELEMENT}
                 OPT_ARG_NEEDED=OK
                 ;;

             'as' | \
             'ass' | \
             'assi' | \
             'assig' | \
             'assign' )
                 GETDEFS_ASSIGN_CT=`expr ${GETDEFS_ASSIGN_CT} + 1`
                 OPT_ELEMENT="_${GETDEFS_ASSIGN_CT}"
                 OPT_NAME='ASSIGN'
                 OPT_ARG_NEEDED=YES
                 ;;

             'co' | \
             'com' | \
             'comm' | \
             'commo' | \
             'common' | \
             'common-' | \
             'common-a' | \
             'common-as' | \
             'common-ass' | \
             'common-assi' | \
             'common-assig' | \
             'common-assign' )
                 GETDEFS_COMMON_ASSIGN_CT=`expr ${GETDEFS_COMMON_ASSIGN_CT} + 1`
                 OPT_ELEMENT="_${GETDEFS_COMMON_ASSIGN_CT}"
                 OPT_NAME='COMMON_ASSIGN'
                 OPT_ARG_NEEDED=YES
                 ;;

             'co' | \
             'cop' | \
             'copy' )
                 GETDEFS_COPY_CT=`expr ${GETDEFS_COPY_CT} + 1`
                 OPT_ELEMENT="_${GETDEFS_COPY_CT}"
                 OPT_NAME='COPY'
                 OPT_ARG_NEEDED=YES
                 ;;

             'sr' | \
             'src' | \
             'srcf' | \
             'srcfi' | \
             'srcfil' | \
             'srcfile' )
                 if [ -n "${GETDEFS_SRCFILE}" ] && ${GETDEFS_SRCFILE_set} ; then
                     echo 'Error:  duplicate SRCFILE option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_SRCFILE_set=true
                 OPT_NAME='SRCFILE'
                 eval GETDEFS_SRCFILE${OPT_ELEMENT}=true
                 export GETDEFS_SRCFILE${OPT_ELEMENT}
                 OPT_ARG_NEEDED=OK
                 ;;

             'li' | \
             'lin' | \
             'line' | \
             'linen' | \
             'linenu' | \
             'linenum' )
                 if [ -n "${GETDEFS_LINENUM}" ] && ${GETDEFS_LINENUM_set} ; then
                     echo 'Error:  duplicate LINENUM option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_LINENUM_set=true
                 OPT_NAME='LINENUM'
                 eval GETDEFS_LINENUM${OPT_ELEMENT}=true
                 export GETDEFS_LINENUM${OPT_ELEMENT}
                 OPT_ARG_NEEDED=OK
                 ;;

             'in' | \
             'inp' | \
             'inpu' | \
             'input' )
                 GETDEFS_INPUT_CT=`expr ${GETDEFS_INPUT_CT} + 1`
                 OPT_ELEMENT="_${GETDEFS_INPUT_CT}"
                 OPT_NAME='INPUT'
                 OPT_ARG_NEEDED=YES
                 ;;

             'ou' | \
             'out' | \
             'outp' | \
             'outpu' | \
             'output' )
                 if [ -n "${GETDEFS_OUTPUT}" ] && ${GETDEFS_OUTPUT_set} ; then
                     echo 'Error:  duplicate OUTPUT option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_OUTPUT_set=true
                 OPT_NAME='OUTPUT'
                 OPT_ARG_NEEDED=YES
                 ;;

             'au' | \
             'aut' | \
             'auto' | \
             'autog' | \
             'autoge' | \
             'autogen' )
                 if [ -n "${GETDEFS_AUTOGEN}" ] && ${GETDEFS_AUTOGEN_set} ; then
                     echo 'Error:  duplicate AUTOGEN option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_AUTOGEN_set=true
                 OPT_NAME='AUTOGEN'
                 eval GETDEFS_AUTOGEN${OPT_ELEMENT}=true
                 export GETDEFS_AUTOGEN${OPT_ELEMENT}
                 OPT_ARG_NEEDED=OK
                 ;;

             'no-' | \
             'no-a' | \
             'no-au' | \
             'no-aut' | \
             'no-auto' | \
             'no-autog' | \
             'no-autoge' | \
             'no-autogen' )
                 if [ -n "${GETDEFS_AUTOGEN}" ] && ${GETDEFS_AUTOGEN_set} ; then
                     echo 'Error:  duplicate AUTOGEN option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_AUTOGEN_set=true
                 GETDEFS_AUTOGEN='no'
                 export GETDEFS_AUTOGEN
                 OPT_NAME='AUTOGEN'
                 OPT_ARG_NEEDED=NO
                 ;;

             'te' | \
             'tem' | \
             'temp' | \
             'templ' | \
             'templa' | \
             'templat' | \
             'template' )
                 if [ -n "${GETDEFS_TEMPLATE}" ] && ${GETDEFS_TEMPLATE_set} ; then
                     echo 'Error:  duplicate TEMPLATE option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_TEMPLATE_set=true
                 OPT_NAME='TEMPLATE'
                 OPT_ARG_NEEDED=YES
                 ;;

             'ag' | \
             'aga' | \
             'agar' | \
             'agarg' )
                 GETDEFS_AGARG_CT=`expr ${GETDEFS_AGARG_CT} + 1`
                 OPT_ELEMENT="_${GETDEFS_AGARG_CT}"
                 OPT_NAME='AGARG'
                 OPT_ARG_NEEDED=YES
                 ;;

             'ba' | \
             'bas' | \
             'base' | \
             'base-' | \
             'base-n' | \
             'base-na' | \
             'base-nam' | \
             'base-name' )
                 if [ -n "${GETDEFS_BASE_NAME}" ] && ${GETDEFS_BASE_NAME_set} ; then
                     echo 'Error:  duplicate BASE_NAME option'
                     echo "$GETDEFS_USAGE_TEXT"
                     exit 1
                 fi >&2
                 GETDEFS_BASE_NAME_set=true
                 OPT_NAME='BASE_NAME'
                 OPT_ARG_NEEDED=YES
                 ;;

             've' | \
             'ver' | \
             'vers' | \
             'versi' | \
             'versio' | \
             'version' )
                 echo "$GETDEFS_LONGUSAGE_TEXT"
                 exit 0
                 ;;

             'he' | \
             'hel' | \
             'help' )
                 echo "$GETDEFS_LONGUSAGE_TEXT"
                 exit 0
                 ;;

             'mo' | \
             'mor' | \
             'more' | \
             'more-' | \
             'more-h' | \
             'more-he' | \
             'more-hel' | \
             'more-help' )
                 echo "$GETDEFS_LONGUSAGE_TEXT" | ${PAGER-more}
                 exit 0
                 ;;

             'sa' | \
             'sav' | \
             'save' | \
             'save-' | \
             'save-o' | \
             'save-op' | \
             'save-opt' | \
             'save-opts' )
                 echo 'Warning:  Cannot save options files' >&2
                 OPT_ARG_NEEDED=OK
                 ;;

             'lo' | \
             'loa' | \
             'load' | \
             'load-' | \
             'load-o' | \
             'load-op' | \
             'load-opt' | \
             'load-opts' )
                 echo 'Warning:  Cannot load options files' >&2
                 OPT_ARG_NEEDED=YES
                 ;;

             'no-' | \
             'no-l' | \
             'no-lo' | \
             'no-loa' | \
             'no-load' | \
             'no-load-' | \
             'no-load-o' | \
             'no-load-op' | \
             'no-load-opt' | \
             'no-load-opts' )
                 echo 'Warning:  Cannot suppress the loading of options files' >&2
                 OPT_ARG_NEEDED=NO
                 ;;

             * )
                 echo Unknown option: "${OPT_CODE}" >&2
                 echo "$GETDEFS_USAGE_TEXT" >&2
                 exit 1
                 ;;
             esac
             case "${OPT_ARG_NEEDED}" in
             NO )
                 OPT_ARG_VAL=''
                 ;;
             YES )
                 if [ -z "${OPT_ARG_VAL}" ]
                 then
                     if [ $# -eq 0 ]
                     then
                         echo No argument provided for ${OPT_NAME} option
                         echo "$GETDEFS_USAGE_TEXT"
                         exit 1
                     fi >&2
                     OPT_ARG_VAL=${OPT_ARG}
                     shift
                     OPT_ARG=$1
                 fi
                 ;;
             OK )
                 if [ -z "${OPT_ARG_VAL}" ] && [ $# -gt 0 ]
                 then
                     case "${OPT_ARG}" in -* ) ;; * )
                         OPT_ARG_VAL=${OPT_ARG}
                         shift
                         OPT_ARG=$1 ;; esac
                 fi
                 ;;
             esac
         if [ -n "${OPT_ARG_VAL}" ]
         then
             eval GETDEFS_${OPT_NAME}${OPT_ELEMENT}="'${OPT_ARG_VAL}'"
             export GETDEFS_${OPT_NAME}${OPT_ELEMENT}
         fi
     done
     OPTION_COUNT=`expr $ARG_COUNT - $#`
     OPERAND_COUNT=$#
     unset OPT_PROCESS || :
     unset OPT_ELEMENT || :
     unset OPT_ARG     || :
     unset OPT_ARG_NEEDED || :
     unset OPT_NAME    || :
     unset OPT_CODE    || :
     unset OPT_ARG_VAL || :

     # # # # # # # # # #
     #
     #  END OF AUTOMATED OPTION PROCESSING
     #
     # # # # # # # # # # -- do not modify this marker --

     env | grep '^GETDEFS_'

\1f
File: autogen.info,  Node: AutoInfo,  Next: AutoMan pages,  Prev: shell options,  Up: AutoOpts

7.13 Automated Info Docs
========================

AutoOpts provides two templates for producing '.texi' documentation.
'agtexi-cmd.tpl' for the invoking section, and 'aginfo3.tpl' for
describing exported library functions and macros.

   For both types of documents, the documentation level is selected by
passing a '-DLEVEL=<level-name>' argument to AutoGen when you build the
document.  (See the example invocation below.)

   Two files will be produced, a '.texi' file and a '.menu' file.  You
should include the text in the '.menu' file in a '@menu' list, either
with '@include'-ing it or just copying text.  The '.texi' file should be
'@include'-ed where the invoking section belongs in your document.

   The '.texi' file will contain an introductory paragraph, a menu and a
subordinate section for the invocation usage and for each documented
option.  The introductory paragraph is normally the boiler plate text,
along the lines of:

     This chapter documents the @file{AutoOpts} generated usage text
     and option meanings for the @file{your-program} program.

or:

     These are the publicly exported procedures from the libname library.
     Any other functions mentioned in the header file are for the private use
     of the library.

* Menu:

* command-info::      'invoking' info docs
* library-info::      library info docs

\1f
File: autogen.info,  Node: command-info,  Next: library-info,  Up: AutoInfo

7.13.1 'invoking' info docs
---------------------------

Using the option definitions for an AutoOpt client program, the
'agtexi-cmd.tpl' template will produce texinfo text that documents the
invocation of your program.  The text emitted is designed to be included
in the full texinfo document for your product.  It is not a stand-alone
document.  The usage text for the *note autogen usage::, *note getdefs
usage:: and *note columns usage:: programs, are included in this
document and are all generated using this template.

   If your program's option definitions include a 'prog-info-descrip'
section, then that text will replace the boilerplate introductory
paragraph.

These files are produced by invoking the following command:

     autogen -L ${prefix}/share/autogen -Tagtexi-cmd.tpl \
             -DLEVEL=section your-opts.def

Where '${prefix}' is the AutoGen installation prefix and 'your-opts.def'
is the name of your product's option definition file.

\1f
File: autogen.info,  Node: library-info,  Prev: command-info,  Up: AutoInfo

7.13.2 library info docs
------------------------

The 'texinfo' doc for libraries is derived from mostly the same
information as is used for producing man pages *Note man3::.  The main
difference is that there is only one output file and the individual
functions are referenced from a 'texi' menu.  There is also a small
difference in the global attributes used:

  lib_description   A description of the library.  This text
                    appears before the menu.  If not provided,
                    the standard boilerplate version will be
                    inserted.
  see_also          The 'SEE ALSO' functionality is not supported
                    for the 'texinfo' documentation, so any
                    'see_also' attribute will be ignored.

These files are produced by invoking the following commands:

     getdefs linenum srcfile template=aginfo3.tpl output=libexport.def \
            <source-file-list>

     autogen -L ${prefix}/share/autogen -DLEVEL=section libexport.def

Where '${prefix}' is the AutoGen installation prefix and 'libexport.def'
is some name that suits you.

   An example of this can be seen in this document, *Note libopts
procedures::.

\1f
File: autogen.info,  Node: AutoMan pages,  Next: getopt_long,  Prev: AutoInfo,  Up: AutoOpts

7.14 Automated Man Pages
========================

AutoOpts provides two templates for producing man pages.  The command
('man1') pages are derived from the options definition file, and the
library ('man3') pages are derived from stylized comments (*note getdefs
Invocation::).

   Man pages include a date in the footer.  By default, this is derived
from the current date.  However, this may be overridden with the
'MAN_PAGE_DATE' environment variable.  If set and not empty, its
contents will be copied into where the output of 'date '+%d %b %Y''
would otherwise go.

   Man pages may be formatted as either traditional man pages or using
'mdoc' formatting.  The format is selected by selecting the appropriate
template.

* Menu:

* man1::      command line man pages
* man3::      library man pages

\1f
File: autogen.info,  Node: man1,  Next: man3,  Up: AutoMan pages

7.14.1 command line man pages
-----------------------------

Man pages for commands are documented using the 'agman-cmd.tpl' and
'agmdoc-cmd.tpl' templates.  If the options specify pulling information
from 'RC'/'ini'/'cfg' files, then you may use the 'rc-sample.tpl'
template to produce an example config file for your program.

   Using the option definitions for an AutoOpts client program, the
'agman-cmd.tpl' template will produce an nroff document suitable for use
as a 'man(1)' page document for a command line command.  The description
section of the document is either the 'prog-man-descrip' text, if
present, or the 'detail' text.

   Each option in the option definitions file is fully documented in its
usage.  This includes all the information documented above for each
option (*note option attributes::), plus the 'doc' attribute is
appended.  Since the 'doc' text is presumed to be designed for 'texinfo'
documentation, 'sed' is used to convert some constructs from 'texi' to
'nroff'-for-'man'-pages.  Specifically,

     convert @code, @var and @samp into \fB...\fP phrases
     convert @file into \fI...\fP phrases
     Remove the '@' prefix from curly braces
     Indent example regions
     Delete the example commands
     Replace 'end example' command with ".br"
     Replace the '@*' command with ".br"

This document is produced by invoking the following command:

     autogen -L ${prefix}/share/autogen -Tagman-cmd.tpl options.def

Where '${prefix}' is the AutoGen installation prefix and 'options.def'
is the name of your product's option definition file.  I do not use this
very much, so any feedback or improvements would be greatly appreciated.

\1f
File: autogen.info,  Node: man3,  Prev: man1,  Up: AutoMan pages

7.14.2 library man pages
------------------------

Man pages for libraries are documented using the 'agman3.tpl' template.

   Two global definitions are required, and then one library man page is
produced for each 'export_func' definition that is found.  It is
generally convenient to place these definitions as 'getdefs' comments
(*note getdefs Invocation::) near the procedure definition, but they may
also be a separate AutoGen definitions file (*note Definitions File::).
Each function will be cross referenced with their sister functions in a
'SEE ALSO' section.  A global 'see_also' definition will be appended to
this cross referencing text.

The two global definitions required are:

  library     This is the name of your library, without the 'lib'
              prefix.  The AutoOpts library is named
              'libopts.so...', so the 'library' attribute would
              have the value 'opts'.
  header      Generally, using a library with a compiled program
              entails '#include'-ing a header file.  Name that
              header with this attribute.  In the case of AutoOpts,
              it is generated and will vary based on the name of
              the option definition file.  Consequently,
              'your-opts.h' is specified.

The 'export_func' definition should contain the following attributes:

  name        The name of the procedure the library user may call.
  what        A brief sentence describing what the procedure does.
  doc         A detailed description of what the procedure does.
              It may ramble on for as long as necessary to properly
              describe it.
  err         A short description of how errors are handled.
  ret_type    The data type returned by the procedure.  Omit this
              for 'void' procedures.
  ret_desc    Describe what the returned value is, if needed.
  private     If specified, the function will *not* be documented.
              This is used, for example, to produce external
              declarations for functions that are not available for
              public use, but are used in the generated text.
  arg         This is a compound attribute that contains:
              arg_type    The data type of the argument.
              arg_name    A short name for it.
              arg_desc    A brief description.

As a 'getdefs' comment, this would appear something like this:

     /*=--subblock=arg=arg_type,arg_name,arg_desc =*/
     /*=*
      * library: opts
      * header:  your-opts.h
     =*/
     /*=export_func optionProcess
      *
      * what: this is the main option processing routine
      * arg:  + tOptions* + pOpts + program options descriptor +
      * arg:  + int       + argc  + program arg count  +
      * arg:  + char**    + argv  + program arg vector +
      * ret_type:  int
      * ret_desc:  the count of the arguments processed
      *
      * doc:  This is what it does.
      * err:  When it can't, it does this.
     =*/

Note the 'subblock' and 'library' comments.  'subblock' is an embedded
'getdefs' option (*note getdefs subblock::) that tells it how to parse
the 'arg' attribute.  The 'library' and 'header' entries are global
definitions that apply to all the documented functions.

\1f
File: autogen.info,  Node: getopt_long,  Next: i18n,  Prev: AutoMan pages,  Up: AutoOpts

7.15 Using getopt(3C)
=====================

There is a template named, 'getopt.tpl' that is distributed with
AutoOpts.  Using that template instead of 'options.tpl' will produce
completely independent source code that will parse command line options.
It will utilize either the standard 'getopt(3C)' or the GNU
'getopt_long(3GNU)' function to drive the parsing.  Which is used is
selected by the presence or absence of the 'long-opts' program
attribute.  It will save you from being dependent upon the 'libopts'
library and it produces code ready for internationalization.  However,
it also carries with it some limitations on the use of AutoOpts features
and some requirements on the build environment.

   *PLEASE NOTE*: in processing the option definitions to produce the
usage text, it is necessary to compile some generated code in a
temporary directory.  That means that all the include directories needed
to compile the code must be full path names and not relative directory
names.  "."  is a relative directory name.  To specify "-I." in the
'CFLAGS' environment variable, you must expand it.  For example, use:
     CFLAGS=-I`pwd`

* Menu:

* getopt limitations::  getopt feature limitations
* getopt building::     getopt build requirements

\1f
File: autogen.info,  Node: getopt limitations,  Next: getopt building,  Up: getopt_long

7.15.1 getopt feature limitations
---------------------------------

This list of limitations is relative to the full list of AutoOpts
supported features, *Note Features::.

  1. You cannot automatically take advantage of environment variable
     options or automated parsing of configuration files ('rc' or 'ini'
     files).  Consequently, the resulting code does not support
     '--load-opts' or '--save-opts' options automatically.

  2. You cannot use set membership, enumerated, range checked or stacked
     argument type options.  In fact, you cannot use anything that
     depends upon the 'libopts' library.  You are constrained to options
     that take 'string' arguments, though you may handle the option
     argument with a callback procedure.

  3. Special disablement and/or enablement prefixes are not recognized.

  4. Option coordination with external libraries will not work.

  5. Every option must be 'settable' because the emitted code depends
     upon the 'SET_OPT_XXX' macros having been defined.  Specify this as
     a global (program) attribute.

  6. You must specify a main procedure attribute (*note Generated
     main::).  The 'getopt.tpl' template depends upon being able to
     compile the traditional .c file into a program and get it to emit
     the usage text.

  7. For the same reason, the traditional option parsing table code must
     be emitted before the 'getopt.tpl' template gets expanded.

  8. The usage text is, therefore, statically defined.

\1f
File: autogen.info,  Node: getopt building,  Prev: getopt limitations,  Up: getopt_long

7.15.2 getopt build requirements
--------------------------------

You must supply some compile and link options via environment variables.

'srcdir'
     In case the option definition file lives in a different directory.
'CFLAGS'
     Any special flags required to compile.  The flags from
     'autoopts-config cflags' will be included automatically.  Since the
     creation of the option parsing code includes creating a program
     that prints out help text, if it is necessary to include files from
     various directories to compile that program, you will need to
     specify those directories with '-Idirpath' text in the 'CFLAGS'.
     Some experimentation may be necessary in that case.

     *NOTE*: the '-Idirpath' text is only needed if your option callback
     functions include code that require additional '#include'
     directives.
'LDFLAGS'
     Any special flags required to link.  The flags from
     'autoopts-config ldflags' will be included automatically.  This is
     required only if additional link flags for the help text emission
     program might be needed.
'CC'
     This is needed only if 'cc' cannot be found in '$PATH' (or it is
     not the one you want).

   To use this, set the exported environment variables and specify
'getopt' as the default template in your option definitions file (*note
Identification::).  You will have four new files.  Assuming your
definitions were in a file named 'myprog-opts.def' and your program name
was specified as 'progname', the resulting files would be created:
'myprog-opts.h', 'myprog-opts.c', 'getopt-progname.h' and
'getopt-progname.c'.  You must compile and link both '.c' files into
your program.  If there are link failures, then you are using AutoOpts
features that require the 'libopts' library.  You must remove these
features, *Note getopt limitations::.

   These generated files depend upon configure defines to work
correctly.  Therefore, you must specify a 'config-header' attribute
(*note programming attributes::) and ensure it has '#defines' for either
'HAVE_STDINT_H' or 'HAVE_INTTYPES_H'; either 'HAVE_SYS_LIMITS_H' or
'HAVE_LIMITS_H'; and 'HAVE_SYSEXITS_H', if the 'sysexits.h' header is
available.  The required header files for these defines are,
respectively, the '/usr/include' files named:
   * stdint.h
   * inttypes.h
   * sys/limits.h
   * limits.h
   * sysexits.h

The following header files must also exist on the build platform:
   * sys/types.h
   * stdio.h
   * string.h
   * unistd.h - or, for getopt_long:
   * getopt.h

\1f
File: autogen.info,  Node: i18n,  Next: Naming Conflicts,  Prev: getopt_long,  Up: AutoOpts

7.16 Internationalizing AutoOpts
================================

The generated code for AutoOpts will enable and disable the translation
of AutoOpts run time messages.  If 'ENABLE_NLS' is defined at compile
time and 'no-xlate' has been not set to the value _anything_, then the
'_()' macro may be used to specify a translation function.  If
undefined, it will default to 'gettext(3GNU)'.  This define will also
enable a callback function that 'optionProcess' invokes at the beginning
of option processing.  The AutoOpts 'libopts' library will always check
for this _compiled with NLS_ flag, so 'libopts' does not need to be
specially compiled.  The strings returned by the translation function
will be 'strdup(3)-ed' and kept.  They will not be re-translated, even
if the locale changes, but they will also not be dependent upon reused
or unmappable memory.

   You should also ensure that the 'ATTRIBUTE_FORMAT_ARG()' gets
'#define'-ed to something 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.

   To internationalize option processing, you should first
internationalize your program.  Then, the option processing strings can
be added to your translation text by processing the AutoOpts-generated
'my-opts.c' file and adding the distributed 'po/usage-txt.pot' file.
(Also by extracting the strings yourself from the 'usage-txt.h' file.)
When you call 'optionProcess', all of the user visible AutoOpts strings
will be passed through the localization procedure established with the
'_()' preprocessing macro.

   All of this is _dis_-abled if you specify the global attribute
'no-xlate' to _anything_.

\1f
File: autogen.info,  Node: Naming Conflicts,  Next: All Attribute Names,  Prev: i18n,  Up: AutoOpts

7.17 Naming Conflicts
=====================

AutoOpts generates a header file that contains many C preprocessing
macros and several external names.  For the most part, they begin with
either 'opt_' or 'option', or else they end with '_opt'.  If this
happens to conflict with other macros you are using, or if you are
compiling multiple option sets in the same compilation unit, the
conflicts can be avoided.  You may specify an external name 'prefix'
(*note program attributes::) for all of the names generated for each set
of option definitions.

   Among these macros, several take an option name as a macro argument.
Sometimes, this will inconveniently conflict.  For example, if you
specify an option named, 'debug', the emitted code will presume that
'DEBUG' is not a preprocessing name.  Or also, if you are building on a
Windows platform, you may find that MicroSoft has usurped a number of
user space names in its header files.  Consequently, you will get a
preprocessing error if you use, for example, 'HAVE_OPT(DEBUG)' or
'HAVE_OPT(INTERNAL)' (*note HAVE_OPT::) in your code.  You may trigger
an obvious warning for such conflicts by specifying the
'guard-option-names' attribute (*note program attributes::).  That
emitted code will also '#undef'-ine the conflicting name.

\1f
File: autogen.info,  Node: All Attribute Names,  Next: Option Define Names,  Prev: Naming Conflicts,  Up: AutoOpts

7.18 All Attribute Names
========================

This is the list of all the option attributes used in the various option
processing templates.  There are several flavors of attributes, and
these are not distinguished here.

   * Valid, current attributes that you are encouraged to use.
   * Internally generated attributes that you cannot use at all.  I need
     to prefix these with a distinguished prefix.  e.g.  'ao-'
   * Valid attributes, but are deprecated.  Alternates should be
     documented.

   This list is derived by running many example option definitions
through the option generation and man page templates and noting which
attributes are actually used.  There may be a few that are used but not
exercised in my testing.  If so, I need to ferret those out and test
them, too.

     addtogroup         aliases          allow_errors  arg_default
     arg_name           arg_optional     arg_range     arg_type
     argument           author           call_proc     cmd_section
     comment_char       concept          config_header copyright
     date               default          deprecated    descrip
     detail             die_code         disable       disable_load
     disable_save       doc              doc_section   doc_sub
     doc_sub_cmd        documentation    ds_format     ds_text
     ds_type            eaddr            enable        enabled
     environrc          equivalence      exit_desc     exit_name
     explain            export           extract_code  field
     file_fail_code     flag             flag_code     flag_proc
     flags_cant         flags_must       full_usage    gnu_usage
     guard_option_names handler_proc     handler_type  help_type
     help_value         home_rc          homerc        ifdef
     ifndef             immed_disable    immediate     include
     interleaved        keyword          lib_name      library
     load_opts_value    long_opts        main_fini     main_init
     main_type          max              min           more_help_value
     must_set           name             no_command    no_libopts
     no_misuse_usage    no_preset        no_xlate      omit_texi
     omitted_usage      open_file        opt_state     option_format
     option_info        owner            package       prefix
     prefix_enum        preserve_case    prog_descrip  prog_info_descrip
     prog_man_descrip   prog_name        prog_title    rcfile
     reorder_args       reset_value      resettable    save_opts_value
     scaled             set_desc         set_index     settable
     short_usage        stack_arg        stdin_input   sub_name
     sub_text           sub_type         test_main     translators
     type               unshar_file_code unstack_arg   usage
     usage_message      usage_opt        usage_value   value
     vendor_opt         version          version_proc  version_value

\1f
File: autogen.info,  Node: Option Define Names,  Prev: All Attribute Names,  Up: AutoOpts

7.19 Option Definition Name Index
=================================

\0\b[index\0\b]
* Menu:

* addtogroup:                            global option attributes.
                                                              (line  18)
* allow-errors:                          presentation attributes.
                                                              (line   9)
* arg-default:                           arg-default.         (line   6)
* arg-name:                              per option attributes.
                                                              (line   9)
* arg-optional:                          arg-optional.        (line   6)
* arg-range:                             arg-type number.     (line  21)
* arg-type:                              Option Arguments.    (line  24)
* argument:                              program attributes.  (line  22)
* author:                                information attributes.
                                                              (line  25)
* before-guile-boot:                     main guile.          (line   9)
* call-proc:                             Option Argument Handling.
                                                              (line  62)
* cmd-section:                           global option attributes.
                                                              (line   7)
* comment-char:                          main-for-each-opts.  (line  25)
* config-header:                         program attributes.  (line  33)
* config-header <1>:                     programming attributes.
                                                              (line  10)
* copyright:                             information attributes.
                                                              (line  10)
* date:                                  information attributes.
                                                              (line  13)
* default:                               opt-attr default option.
                                                              (line   6)
* deprecated:                            Common Attributes.   (line  28)
* descrip:                               Required Attributes. (line  34)
* detail:                                information attributes.
                                                              (line  39)
* detail <1>:                            global option attributes.
                                                              (line  12)
* die-code:                              programming attributes.
                                                              (line  51)
* disable:                               Common Attributes.   (line  33)
* disable-load:                          config attributes.   (line  13)
* disable-save:                          config attributes.   (line  13)
* doc:                                   per option attributes.
                                                              (line  15)
* doc-section:                           global option attributes.
                                                              (line  42)
* doc-sub:                               global option attributes.
                                                              (line 141)
* doc-sub-cmd:                           global option attributes.
                                                              (line 173)
* documentation:                         lib and program.     (line  16)
* documentation <1>:                     opt-attr documentation.
                                                              (line  17)
* eaddr:                                 information attributes.
                                                              (line  27)
* enable:                                Common Attributes.   (line  45)
* enabled:                               Common Attributes.   (line  49)
* environrc:                             config attributes.   (line  17)
* equivalence:                           opt-attr equivalence.
                                                              (line   6)
* exit-desc:                             programming attributes.
                                                              (line  16)
* exit-name:                             programming attributes.
                                                              (line  16)
* explain:                               information attributes.
                                                              (line  43)
* export:                                programming attributes.
                                                              (line  66)
* extra-code:                            arg-keyword.         (line  15)
* extract-code:                          Option Argument Handling.
                                                              (line  51)
* file-exists:                           arg-type file name.  (line  13)
* file-mode:                             arg-type file name.  (line  29)
* flag-code:                             Option Argument Handling.
                                                              (line  27)
* flag-proc:                             Option Argument Handling.
                                                              (line  69)
* full-usage:                            usage attributes.    (line  10)
* gnu-usage:                             usage attributes.    (line  43)
* gnu-usage <1>:                         information attributes.
                                                              (line  82)
* guard-option-names:                    programming attributes.
                                                              (line  73)
* guile-main:                            main guile.          (line  14)
* handler-frees:                         main-for-each-type.  (line  66)
* handler-proc:                          main-for-each-proc.  (line   6)
* handler-type:                          main-for-each-type.  (line   6)
* help-value:                            automatic options.   (line  18)
* homerc:                                config attributes.   (line  26)
* ifdef:                                 Common Attributes.   (line  56)
* ifndef:                                Common Attributes.   (line  56)
* immed-disable:                         Immediate Action.    (line  31)
* immediate:                             Immediate Action.    (line  24)
* include:                               programming attributes.
                                                              (line 104)
* interleaved:                           main-for-each-opts.  (line  10)
* keyword:                               arg-keyword.         (line   6)
* lib-name:                              lib and program.     (line  24)
* library:                               lib and program.     (line   7)
* load-opts-value:                       automatic options.   (line  15)
* long-opts:                             presentation attributes.
                                                              (line  15)
* main:                                  Generated main.      (line   8)
* main-fini:                             main-for-each-opts.  (line  21)
* main-init:                             main-for-each-opts.  (line  17)
* main-type:                             Generated main.      (line  12)
* max:                                   Common Attributes.   (line  14)
* min:                                   Common Attributes.   (line  19)
* more-help-value:                       automatic options.   (line  15)
* must-set:                              Common Attributes.   (line  24)
* MYHANDLER-code:                        main-for-each-code.  (line   6)
* name:                                  Required Attributes. (line   9)
* no-command:                            Common Attributes.   (line  87)
* no-libopts:                            programming attributes.
                                                              (line 108)
* no-misuse-usage:                       usage attributes.    (line  57)
* no-preset:                             opt-attr no-preset.  (line   6)
* no-xlate:                              presentation attributes.
                                                              (line  35)
* omitted-usage:                         Common Attributes.   (line  56)
* open-file:                             arg-type file name.  (line  23)
* option-code:                           main main.           (line   7)
* option-format:                         global option attributes.
                                                              (line  28)
* option-info:                           global option attributes.
                                                              (line  38)
* opts-ptr:                              information attributes.
                                                              (line  61)
* owner:                                 information attributes.
                                                              (line  14)
* package:                               information attributes.
                                                              (line  46)
* prefix:                                programming attributes.
                                                              (line 115)
* prefix-enum:                           arg-type keyword.    (line  38)
* preserve-case:                         information attributes.
                                                              (line  52)
* prog-desc:                             information attributes.
                                                              (line  61)
* prog-group:                            usage attributes.    (line  65)
* prog-name:                             program attributes.  (line  15)
* prog-title:                            program attributes.  (line  19)
* rcfile:                                config attributes.   (line  56)
* reorder-args:                          presentation attributes.
                                                              (line  51)
* reorder-args <1>:                      information attributes.
                                                              (line  91)
* reset-value:                           automatic options.   (line  15)
* resettable:                            presentation attributes.
                                                              (line  68)
* save-opts-value:                       automatic options.   (line  19)
* scaled:                                arg-type number.     (line  15)
* settable:                              opt-attr settable.   (line   6)
* short-usage:                           usage attributes.    (line  38)
* stack-arg:                             Option Argument Handling.
                                                              (line  73)
* text:                                  information attributes.
                                                              (line  23)
* translators:                           opt-attr translators.
                                                              (line   6)
* type:                                  information attributes.
                                                              (line  15)
* unstack-arg:                           Option Argument Handling.
                                                              (line  86)
* usage:                                 usage attributes.    (line  73)
* usage <1>:                             information attributes.
                                                              (line  74)
* usage-message:                         programming attributes.
                                                              (line  41)
* usage-opt:                             Features.            (line  56)
* usage-opt <1>:                         usage attributes.    (line  51)
* usage-value:                           automatic options.   (line  15)
* value:                                 Common Attributes.   (line  10)
* vendor-opt:                            config attributes.   (line  61)
* version:                               usage attributes.    (line  90)
* version-proc:                          automatic options.   (line  23)
* version-value:                         automatic options.   (line  15)

\1f
File: autogen.info,  Node: Add-Ons,  Next: Future,  Prev: AutoOpts,  Up: Top

8 Add-on packages for AutoGen
*****************************

This chapter includes several programs that either work closely with
AutoGen (extracting definitions or providing special formatting
functions), or leverage off of AutoGen technology.  There is also a
formatting library that helps make AutoGen possible.

   AutoOpts ought to appear in this list as well, but since it is the
primary reason why many people would even look into AutoGen at all, I
decided to leave it in the list of chapters.

* Menu:

* AutoFSM::                        Automated Finite State Machine.
* AutoXDR::                        Combined RPC Marshalling.
* AutoEvents::                     Automated Event Management.
* Bit Maps::                       Bit Maps and Enumerations.
* columns Invocation::             Invoking columns.
* getdefs Invocation::             Invoking getdefs.
* xml2ag Invocation::              Invoking xml2ag.
* snprintfv::                      The extensible format printing library.

\1f
File: autogen.info,  Node: AutoFSM,  Next: AutoXDR,  Up: Add-Ons

8.1 Automated Finite State Machine
==================================

The templates to generate a finite state machine in C or C++ is included
with AutoGen.  The documentation is not.  The documentation is in HTML
format for viewing (http://www.gnu.org/software/autogen/autofsm.html),
or you can download FSM (http://download.sourceforge.net/autogen/).

\1f
File: autogen.info,  Node: AutoXDR,  Next: AutoEvents,  Prev: AutoFSM,  Up: Add-Ons

8.2 Combined RPC Marshalling
============================

The templates and NFSv4 definitions are not included with AutoGen in any
way.  The folks that designed NFSv4 noticed that much time and bandwidth
was wasted sending queries and responses when many of them could be
bundled.  The protocol bundles the data, but there is no support for it
in rpcgen.  That means you have to write your own code to do that.
Until now.  Download this and you will have a large, complex example of
how to use 'AutoXDR' for generating the marshaling and unmarshaling of
combined RPC calls.  There is a brief example on the web
(http://www.gnu.org/software/autogen/xdr/index.html), but you should
download AutoXDR (http://download.sourceforge.net/autogen/).

\1f
File: autogen.info,  Node: AutoEvents,  Next: Bit Maps,  Prev: AutoXDR,  Up: Add-Ons

8.3 Automated Event Management
==============================

Large software development projects invariably have a need to manage the
distribution and display of state information and state changes.  In
other words, they need to manage their software events.  Generally, each
such project invents its own way of accomplishing this and then
struggles to get all of its components to play the same way.  It is a
difficult process and not always completely successful.  This project
helps with that.

   AutoEvents completely separates the tasks of supplying the data
needed for a particular event from the methods used to manage the
distribution and display of that event.  Consequently, the programmer
writing the code no longer has to worry about that part of the problem.
Likewise the persons responsible for designing the event management and
distribution no longer have to worry about getting programmers to write
conforming code.

   This is a work in progress.  See my web page
(http://www.gnu.org/software/autogen/autoevents.html) on the subject, if
you are interested.  I have some useful things put together, but it is
not ready to call a product.

\1f
File: autogen.info,  Node: Bit Maps,  Next: columns Invocation,  Prev: AutoEvents,  Up: Add-Ons

8.4 Bit Maps and Enumerations
=============================

AutoGen provides two templates for managing enumerations and bit maps
(flag words).  They produce an enumeration of the enum or '#define's for
the bit maps, plus conversion functions for converting a string into one
of these values or converting one of these values into a human readable
string.  Finally, for enumerations, you may specify one or more sets of
dispatching functions that will be selected by identifying a keyword
prefix of a string (*note the dispatch attribute in Strings to Enums and
Back: enum-code.).

   There is a separate project that produces a GDB add-on that will add
these capabilities into GDB for bit masks.  (GDB does just fine with
enumerations.)

* Menu:

* enums::           Enumerations
* enum-code::       Strings to Enums and Back
* masks::           Bit Maps and Masks

\1f
File: autogen.info,  Node: enums,  Next: enum-code,  Up: Bit Maps

8.4.1 Enumerations
------------------

'str2enum.tpl'

   Produce an enumeration for a list of input "cmd"s (names).
Optionally, produce functions to:

   * convert a string to an enumeration
   * convert an enumeration value into a string
   * invoke a function based on the first token name found in a string

   The header file produced will contain the enumeration and
declarations for the optional procedures.  The code ('.c') file will
contain these optional procedures, but can be omitted if the 'no-code'
attribute is specified.

   The following attributes are recognized with the 'str2enum' template:

'cmd'
     You must provide a series of these attributes: they specify the
     list of names used in the enumeration.  Specific values for the
     names may be specified by specifying a numeric index for these
     attributes.  e.g.  'cmd[5] = mumble;' will cause
          FOO_CMD_MUMBLE = 5
     to be inserted into the enumeration.  Do not specify a value of
     "invalid", unless you specify the 'invalid-name' attribute.  (In
     that case, do not specify a 'cmd' value that matches the
     'invalid-name' value.)

'prefix'
     This specifies the first segment of each enumeration name.  If not
     specified, the first segment of the enumeration definition file
     name will be used.  e.g.  'foo-bar.def' will default to a 'FOO'
     prefix.

'type'
     Normally, there is a second constant segment following the prefix.
     If not specified, it will be 'CMD', so if both 'prefix' and 'type'
     were to default from 'foo-bar.def', you will have enumeration
     values prefixed with 'FOO_CMD_'.  If specified as the empty string,
     there will be no "type" component to the name and the default
     constant prefix will thus be 'FOO_'.

'base-name'
     This specifies the base name of the output files, enumeration type
     and the translation functions.  The default is to use the
     'basename(3)' of the definition file.  e.g.  'foo-bar.def' results
     in a 'base-name' of 'foo-bar'.

'invalid-val'
     The default invalid value is zero.  Sometimes, it is useful for
     zero to be valid.  If so, you can specify ~0 or the empty string to
     be invalid.  The empty string will cause the enumeration count
     (maximum value plus 1) to be the invalid value.

'invalid-name'
     By default, the invalid value is emitted into the enumeration as
     'FOO_INVALID_CMD'.  Specifying this attribute will replace
     'INVALID' with whatever you place in this attribute.

'add-on-text'
     Additional text to insert into the code or header file.

     'ao-file'
          Which file to insert the text into.  There are four choices,
          only two of which are relevant for the 'str2enum' template:
          "enum-header", "enum-code", "mask-header" or "mask-code".

     'ao-text'
          The text to insert.

\1f
File: autogen.info,  Node: enum-code,  Next: masks,  Prev: enums,  Up: Bit Maps

8.4.2 Strings to Enums and Back
-------------------------------

A continuation of the attributes for the 'str2enum.tpl' template.

'no-code'
     Do not emit any string to enumeration or enumeration to string code
     at all.  If this is specified, the remainder of the attributes have
     no effect.

'no-name'
     Do not emit the enumeration to name function.

'no-case'
     When looking up a string, the case of the input string is ignored.

'alias'
     A single punctuation character can be interpreted as a command.
     The first character of this attribute is the aliased character and
     the remainder the aliased-to command.  e.g.  "#comment" makes '#'
     an alias for the 'comment' command.  "#comment" must still be
     listed in the 'cmd' attributes.

'length'
     Specify how lengths are to be handled.  Under the covers,
     'gperf(1)' is used to map a string to an enumeration value.  The
     code it produces requires the string length to be passed in.  You
     may pass in the length yourself, or the generated code may figure
     it out, or you may ask for that length to be returned back after
     being figured out.

     You have four choices with the 'length' attribute:

        * Do not specify it.  You will need to provide the length.
        * Specify "provided".  You will need to provide the length.
        * Specify "returned".  You must pass a pointer to a size_t
          object.  If the name is found, the length will be put there.
        * Specify an empty string.  The generated code will compute the
          length and that computed length will not be returned.  The
          length parameter may be omitted.  If the input strings contain
          only enumeration names, then this would be sufficient.
        * Specifying anything else is undefined.

'partial'
     Normally, a name must fully match to be found successfully.  This
     attribute causes the generated code to look for partial matches if
     the full match 'gperf' function fails.  Partial matches must be at
     least two characters long.

'undef-str'
     by default, the display string for an undefined value is "*
     UNDEFINED *".  Use this to change that.

'equate'
     A series of punctuation characters considered equivalent.
     Typically, "-_" but sometimes (Tandem) "-_^".  Do not use '#' in
     the list of characters.

'dispatch'
     A lookup procedure will call a dispatch function for the procedure
     named after the keyword identified at the start of a string.  Other
     than as specially noted below, for every named "cmd", must have a
     handling function, plus another function to handle errors, with
     "invalid" (or the 'invalid-name' value) as the 'cmd' name.
     Multiple 'dispatch' definitions will produce multiple dispatching
     functions, each with (potentially) unique argument lists and return
     types.

     You may also use 'add-on-text' to "#define" one function to
     another, thus allowing one function to handle multiple keywords or
     commands.  The 'd-nam' and 'd-ret' attributes are required.  The
     'd-arg', 'd-omit' and 'd-only' attributes are optional:

     'd-nam'
          This must be a printf format string with one formatting
          element: '%s'.  The '%s' will be replaced by each 'cmd' name.
          The '%s' will be stripped and the result will be combined with
          the base name to construct the dispatch procedure name.

     'd-ret'
          The return type of the dispatched function, even if "void".

     'd-arg'
          If there are additional arguments that are to be passed
          through to the dispatched function, specify this as though it
          were part of the procedure header.  (It will be glued into the
          dispatching function as is and sedded into what is needed for
          the dispatched function.)

     'd-omit'
          Instead of providing handling functions for all of the 'cmd'
          names, the invalid function will be called for omitted command
          codes.

     'd-only'
          You need only provide functions for the names listed by
          'd-only', plus the "invalid" name.  All other command values
          will trigger calls to the invalid handling function.  Note
          that the invalid call can distinguish from a command that
          could not be found by examining the value of its first ('id')
          argument.

     The handler functions will have the command enumeration as its
     first first argument, a pointer to a constant string that will be
     the character after the parsed command (keyword) name, plus any
     'd-arg' arguments that follow that.

     As an example, a file 'samp-chk.def' containing this:
          AutoGen Definitions str2enum;
          cmd = one, two; invalid-name = oops;
          dispatch = { d-nam = 'hdl_%s_cmd'; d-ret = void; };
     will produce a header containing:
          typedef enum {
              SAMP_OOPS_CMD = 0,
              SAMP_CMD_ONE      = 1,
              SAMP_CMD_TWO      = 2,
              SAMP_COUNT_CMD
          } samp_chk_enum_t;

          extern samp_chk_enum_t
          find_samp_chk_cmd(char const * str, size_t len);

          typedef void(samp_chk_handler_t)(
              samp_chk_enum_t id, char const * str);

          samp_chk_handler_t
                  hdl_oops_cmd, hdl_one_cmd,  hdl_two_cmd;

          extern void
          disp_samp_chk(char * str, size_t len);

          extern char const *
          samp_chk_name(samp_chk_enum_t id);

        * 'find_samp_chk_cmd' will look up a 'len' byte 'str' and return
          the corresponding 'samp_chk_enum_t' value.  That value is
          'SAMP_OOPS_CMD' if the string is not "one" or "two".
        * 'samp_chk_handler_t' is the type of the callback procedures.
          Three must be provided for the dispatching function to call:
          'hdl_oops_cmd', 'hdl_one_cmd' and 'hdl_two_cmd'.
          'hdl_oops_cmd' will receive calls when the string does not
          match.
        * 'disp_samp_chk' this function will call the handler function
          and return whatever the handler returns.  In this case, it is
          void.
        * 'samp_chk_name' will return a string corresponding to the
          enumeration value argument.  If the value is not valid, "*
          UNDEFINED *" (or the value of 'undef-str') is used.

\1f
File: autogen.info,  Node: masks,  Prev: enum-code,  Up: Bit Maps

8.4.3 Bit Maps and Masks
------------------------

'str2mask.tpl'

   This template leverages highly off of enumerations (*note enums::).
It will produce a header file with bit masks defined for each bit
specified with a 'cmd' attribute.  63 is the highest legal bit number
because this template has not been extended to cope with multiple word
masks.  (Patches would be welcome.)

   There are a few constraints on the names allowed:

   * names are constrained to alphanumerics and the underscore
   * aliases are not allowed
   * dispatch procedures are not allowed

   'no-code' and 'no-name' are honored.  'dispatch' is not.  The lookup
function will examine each token in an input string, determine which bit
is specified and add it into a result.  The names may be prefixed with a
hyphen (-) or tilde (~) to remove the bit(s) from the cumulative result.
If the string begins with a plus (+), hyphen or tilde, a "base value"
parameter is used for the starting mask, otherwise the conversion starts
with zero.

   Beyond the enumeration attributes that are used (or ignored), the
'str2mask' template accepts a 'mask' attribute.  It takes a few
"subattributes":

'm-name'
     a special name for a sub-collection of the mask bits

'm-bit'
     The name of each previously defined bit(s).  If the desired
     previously defined value is a mask, that 'm-name' must be suffixed
     with "-mask".

'm-invert'
     When all done collecting the bits, x-or the value with the mask of
     all the bits in the collection.

A mask of all bits in the collection is always generated.

\1f
File: autogen.info,  Node: columns Invocation,  Next: getdefs Invocation,  Prev: Bit Maps,  Up: Add-Ons

8.5 Invoking columns
====================

This program was designed for the purpose of generating compact,
columnized tables.  It will read a list of text items from standard in
or a specified input file and produce a columnized listing of all the
non-blank lines.  Leading white space on each line is preserved, but
trailing white space is stripped.  Methods of applying per-entry and
per-line embellishments are provided.  See the formatting and separation
arguments below.

   This program is used by AutoGen to help clean up and organize its
output.

   See 'autogen/agen5/fsm.tpl' and the generated output 'pseudo-fsm.h'.

   This function was not implemented as an expression function because
either it would have to be many expression functions, or a provision
would have to be added to provide options to expression functions.
Maybe not a bad idea, but it is not being implemented at the moment.

   A side benefit is that you can use it outside of 'autogen' to
columnize input, a la the 'ls' command.

   This section was generated by *AutoGen*, using the 'agtexi-cmd'
template and the option descriptions for the 'columns' program.  This
software is released under the GNU General Public License, version 3 or
later.

* Menu:

* columns usage::                  columns help/usage ('--help')
* columns dimensions::             dimensions options
* columns treatment::              treatment options
* columns ordering::               ordering options
* columns input-text::             input-text options
* columns config::                 presetting/configuring columns
* columns exit status::            exit status
* columns See Also::               See Also

\1f
File: autogen.info,  Node: columns usage,  Next: columns dimensions,  Up: columns Invocation

8.5.1 columns help/usage ('--help')
-----------------------------------

This is the automatically generated usage text for columns.

   The text printed is the same whether selected with the 'help' option
('--help') or the 'more-help' option ('--more-help').  'more-help' will
print the usage text by passing it through a pager program.  'more-help'
is disabled on platforms without a working 'fork(2)' function.  The
'PAGER' environment variable is used to select the program, defaulting
to 'more'.  Both will exit with a status code of 0.

     columns (GNU AutoGen) - Columnize Input Text - Ver. 1.2
     Usage:  columns [ -<flag> [<val>] | --<name>[{=| }<val>] ]...

     Specify the output dimensions:

       Flg Arg Option-Name    Description
        -W Num width          Maximum Line Width
                                     - it must be in the range:
                                       16 to 4095
        -c Num columns        Desired number of columns
                                     - it must be in the range:
                                       1 to 2048
        -w Num col-width      Set width of each column
                                     - it must be in the range:
                                       1 to 2048
           Num tab-width      tab width

     Specify how to lay out the text:

       Flg Arg Option-Name    Description
           Num spread         maximum spread added to column width
                                     - it must be in the range:
                                       1 to 1024
           no  fill           Fill lines with input
                                     - prohibits these options:
                                     spread
                                     col-width
                                     by-columns
        -I Str indent         Line prefix or indentation
           Str first-indent   First line prefix
                                     - requires the option 'indent'
        -f Str format         Formatting string for each input
        -S Str separation     Separation string - follows all but last
           Str line-separation string at end of all lines but last
           Str ending         string at end of last line

     Specify the ordering of the entries:

       Flg Arg Option-Name    Description
           no  by-columns     Print entries in column order
        -s opt sort           Sort input text

     Redirecting stdin to an alternate file:

       Flg Arg Option-Name    Description
        -i Str input          Input file (if not stdin)

     Version, usage and configuration options:

       Flg Arg Option-Name    Description
        -v opt version        output version information and exit
        -? no  help           display extended usage information and exit
        -! no  more-help      extended usage information passed thru pager
        -> opt save-opts      save the option state to a config file
        -< Str load-opts      load options from a config file
                                     - disabled as '--no-load-opts'
                                     - may appear multiple times

     Options are specified by doubled hyphens and their name or by a single
     hyphen and the flag character.

     The following option preset mechanisms are supported:
      - reading file ./.columnsrc
      - reading file $HOME/.columnsrc
      - examining environment variables named COLUMNS_*

     Please send bug reports to:  <autogen-users@lists.sourceforge.net>

\1f
File: autogen.info,  Node: columns dimensions,  Next: columns treatment,  Prev: columns usage,  Up: columns Invocation

8.5.2 dimensions options
------------------------

Specify the output dimensions.

width option (-W).
..................

This is the "maximum line width" option.  This option takes a number
argument 'num'.  This option specifies the full width of the output
line, including any start-of-line indentation.  The output will fill
each line as completely as possible, unless the column width has been
explicitly specified.  If the maximum width is less than the length of
the widest input, you will get a single column of output.

columns option (-c).
....................

This is the "desired number of columns" option.  This option takes a
number argument 'count'.  Use this option to specify exactly how many
columns to produce.  If that many columns will not fit within
LINE_WIDTH, then the count will be reduced to the number that fit.

col-width option (-w).
......................

This is the "set width of each column" option.  This option takes a
number argument 'num'.  Use this option to specify exactly how many
characters are to be allocated for each column.  If it is narrower than
the widest entry, it will be over-ridden with the required width.

tab-width option.
.................

This is the "tab width" option.  This option takes a number argument
'num'.  If an indentation string contains tabs, then this value is used
to compute the ending column of the prefix string.

\1f
File: autogen.info,  Node: columns treatment,  Next: columns ordering,  Prev: columns dimensions,  Up: columns Invocation

8.5.3 treatment options
-----------------------

Specify how to lay out the text.

spread option.
..............

This is the "maximum spread added to column width" option.  This option
takes a number argument 'num'.  Use this option to specify exactly how
many characters may be added to each column.  It allows you to prevent
columns from becoming too far apart.  Without this option, 'columns'
will attempt to widen columns to fill the full width.

fill option.
............

This is the "fill lines with input" option.

This option has some usage constraints.  It:
   * must not appear in combination with any of the following options:
     spread, col_width, by_columns.

   Instead of columnizing the input text, fill the output lines with the
input lines.  Blank lines on input will cause a blank line in the
output, unless the output is sorted.  With sorted output, blank lines
are ignored.

indent option (-I).
...................

This is the "line prefix or indentation" option.  This option takes a
string argument 'l-pfx'.  If a number, then this many spaces will be
inserted at the start of every line.  Otherwise, it is a line prefix
that will be inserted at the start of every line.

first-indent option.
....................

This is the "first line prefix" option.  This option takes a string
argument 'l-pfx'.

This option has some usage constraints.  It:
   * must appear in combination with the following options: indent.

   If a number, then this many spaces will be inserted at the start of
the first line.  Otherwise, it is a line prefix that will be inserted at
the start of that line.  If its length exceeds "indent", then it will be
emitted on a line by itself, suffixed by any line separation string.
For example:

     $ columns --first='#define TABLE' -c 2 -I4 --line=' \' <<_EOF_
     one
     two
     three
     four
     _EOF_
     #define TABLE \
         one   two \
         three four

format option (-f).
...................

This is the "formatting string for each input" option.  This option
takes a string argument 'fmt-str'.  If you need to reformat each input
text, the argument to this option is interpreted as an 'sprintf(3)'
format that is used to produce each output entry.

separation option (-S).
.......................

This is the "separation string - follows all but last" option.  This
option takes a string argument 'sep-str'.  Use this option if, for
example, you wish a comma to appear after each entry except the last.

line-separation option.
.......................

This is the "string at end of all lines but last" option.  This option
takes a string argument 'sep-str'.  Use this option if, for example, you
wish a backslash to appear at the end of every line, except the last.

ending option.
..............

This is the "string at end of last line" option.  This option takes a
string argument 'end-str'.  This option puts the specified string at the
end of the output.

\1f
File: autogen.info,  Node: columns ordering,  Next: columns input-text,  Prev: columns treatment,  Up: columns Invocation

8.5.4 ordering options
----------------------

Specify the ordering of the entries.

by-columns option.
..................

This is the "print entries in column order" option.  Normally, the
entries are printed out in order by rows and then columns.  This option
will cause the entries to be ordered within columns.  The final column,
instead of the final row, may be shorter than the others.

sort option (-s).
.................

This is the "sort input text" option.  This option takes an optional
string argument 'key-pat'.  Causes the input text to be sorted.  If an
argument is supplied, it is presumed to be a pattern and the sort is
based upon the matched text.  If the pattern starts with or consists of
an asterisk ('*'), then the sort is case insensitive.

\1f
File: autogen.info,  Node: columns input-text,  Next: columns config,  Prev: columns ordering,  Up: columns Invocation

8.5.5 input-text options
------------------------

Redirecting stdin to an alternate file.

input option (-i).
..................

This is the "input file (if not stdin)" option.  This option takes a
string argument 'file'.  This program normally runs as a 'filter',
reading from standard input, columnizing and writing to standard out.
This option redirects input to a file.

\1f
File: autogen.info,  Node: columns config,  Next: columns exit status,  Prev: columns input-text,  Up: columns Invocation

8.5.6 presetting/configuring columns
------------------------------------

Any option that is not marked as not presettable may be preset by
loading values from configuration ("rc" or "ini") files, and values from
environment variables named 'COLUMNS' and 'COLUMNS_<OPTION_NAME>'.
'<OPTION_NAME>' must be one of the options listed above in upper case
and segmented with underscores.  The 'COLUMNS' variable will be
tokenized and parsed like the command line.  The remaining variables are
tested for existence and their values are treated like option arguments.

'libopts' will search in 2 places for configuration files:
   * $PWD
   * $HOME
   The environment variables 'PWD', and 'HOME' are expanded and replaced
when 'columns' runs.  For any of these that are plain files, they are
simply processed.  For any that are directories, then a file named
'.columnsrc' is searched for within that directory and processed.

   Configuration files may be in a wide variety of formats.  The basic
format is an option name followed by a value (argument) on the same
line.  Values may be separated from the option name with a colon, equal
sign or simply white space.  Values may be continued across multiple
lines by escaping the newline with a backslash.

   Multiple programs may also share the same initialization file.
Common options are collected at the top, followed by program specific
segments.  The segments are separated by lines like:
     [COLUMNS]
or by
     <?program columns>
Do not mix these styles within one configuration file.

   Compound values and carefully constructed string values may also be
specified using XML syntax:
     <option-name>
        <sub-opt>...&lt;...&gt;...</sub-opt>
     </option-name>
yielding an 'option-name.sub-opt' string value of
     "...<...>..."
   'AutoOpts' does not track suboptions.  You simply note that it is a
hierarchicly valued option.  'AutoOpts' does provide a means for
searching the associated name/value pair list (see: optionFindValue).

   The command line options relating to configuration and/or usage help
are:

version (-v)
............

Print the program version to standard out, optionally with licensing
information, then exit 0.  The optional argument specifies how much
licensing detail to provide.  The default is to print just the version.
The licensing information may be selected with an option argument.  Only
the first letter of the argument is examined:

'version'
     Only print the version.  This is the default.
'copyright'
     Name the copyright usage licensing terms.
'verbose'
     Print the full copyright usage licensing terms.

\1f
File: autogen.info,  Node: columns exit status,  Next: columns See Also,  Prev: columns config,  Up: columns Invocation

8.5.7 columns exit status
-------------------------

One of the following exit values will be returned:
'0 (EXIT_SUCCESS)'
     Successful program execution.
'1 (EXIT_FAILURE)'
     The operation failed or the command syntax was not valid.
'66 (EX_NOINPUT)'
     A specified configuration file could not be loaded.
'70 (EX_SOFTWARE)'
     libopts had an internal operational error.  Please report it to
     autogen-users@lists.sourceforge.net.  Thank you.

\1f
File: autogen.info,  Node: columns See Also,  Prev: columns exit status,  Up: columns Invocation

8.5.8 columns See Also
----------------------

This program is documented more fully in the Columns section of the
Add-On chapter in the 'AutoGen' Info system documentation.

\1f
File: autogen.info,  Node: getdefs Invocation,  Next: xml2ag Invocation,  Prev: columns Invocation,  Up: Add-Ons

8.6 Invoking getdefs
====================

If no 'input' argument is provided or is set to simply "-", and if
'stdin' is not a 'tty', then the list of input files will be read from
'stdin'.  This program extracts AutoGen definitions from a list of
source files.  Definitions are delimited by '/*=<entry-type>
<entry-name>\n' and '=*/\n'.  From that, this program creates a
definition of the following form:

         #line nnn "source-file-name"
         entry_type = {
             name = entry_name;
             ...
         };

  1. The ellipsis '...' is filled in by text found between the two
     delimiters.  Each line of text is stripped of anything before the
     first asterisk, then leading asterisks, then any leading or
     trailing white space.

  2. If what is left starts with what looks like a name followed by a
     colon, then it is interpreted as a name followed by a value.

  3. If the first character of the value is either a single or double
     quote, then you are responsible for quoting the text as it gets
     inserted into the output definitions.  So, if you want whitespace
     at the beginnings of the lines of text, you must do something like
     this:

           * mumble:
           * "  this is some\n"
           * "  indented text."

  4. If the '<entry-name>' is followed by a comma, the word 'ifdef' (or
     'ifndef') and a name 'if_name', then the above entry will be under
     'ifdef' control.

          /*=group entry_name, ifdef FOO
           * attr: attribute value
          =*/

     Will produce the following:

          #ifdef FOO
          #line nnn "source-file-name"
          group = {
              name = entry_name;
              attr = 'attribute value';
          };
          #endif

  5. If you use of the 'subblock' option, you can specify a nested
     value, *Note getdefs subblock::.  That is, this text:

           * arg:  int, this, what-it-is

     with the '--subblock=arg=type,name,doc' option would yield:

          arg = { type = int; name = this; doc = what-it-is; };

   This section was generated by *AutoGen*, using the 'agtexi-cmd'
template and the option descriptions for the 'getdefs' program.  This
software is released under the GNU General Public License, version 3 or
later.

* Menu:

* getdefs usage::                  getdefs help/usage ('help')
* getdefs def-selection::          def-selection options
* getdefs enumerating::            enumerating options
* getdefs doc-insert::             doc-insert options
* getdefs input-files::            input-files options
* getdefs doc-output::             doc-output options
* getdefs config::                 presetting/configuring getdefs
* getdefs exit status::            exit status
* getdefs See Also::               See Also

\1f
File: autogen.info,  Node: getdefs usage,  Next: getdefs def-selection,  Up: getdefs Invocation

8.6.1 getdefs help/usage ('help')
---------------------------------

This is the automatically generated usage text for getdefs.

   The text printed is the same whether selected with the 'help' option
('help') or the 'more-help' option ('more-help').  'more-help' will
print the usage text by passing it through a pager program.  'more-help'
is disabled on platforms without a working 'fork(2)' function.  The
'PAGER' environment variable is used to select the program, defaulting
to 'more'.  Both will exit with a status code of 0.

     getdefs error:  invalid option descriptor for version
     getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5
     Usage:  getdefs [ <option-name>[{=| }<val>] ]...

     Specify which definitions are of interest and what to say about them:

        Arg Option-Name    Description
        Str defs-to-get    Regexp to look for after the "/*="
        Str subblock       subblock definition names
                                     - may appear multiple times
        Str listattr       attribute with list of values
                                     - may appear multiple times

     specify how to number the definitions:

        Arg Option-Name    Description
        opt ordering       Alphabetize or use named file
                                     - disabled as '--no-ordering'
                                     - enabled by default
        Num first-index    The first index to apply to groups

     Definition insertion options:

        Arg Option-Name    Description
        opt filelist       Insert source file names into defs
        Str assign         Global assignments
                                     - may appear multiple times
        Str common-assign  Assignments common to all blocks
                                     - may appear multiple times
        Str copy           File(s) to copy into definitions
                                     - may appear multiple times
        opt srcfile        Insert source file name into each def
        opt linenum        Insert source line number into each def

     specify which files to search for markers:

        Arg Option-Name    Description
        Str input          Input file to search for defs
                                     - may appear multiple times
                                     - default option for unnamed options

     Definition output disposition options::

        Arg Option-Name    Description
        Str output         Output file to open
                                     - an alternate for 'autogen'
        opt autogen        Invoke AutoGen with defs
                                     - disabled as '--no-autogen'
                                     - enabled by default
        Str template       Template Name
        Str agarg          AutoGen Argument
                                     - prohibits the option 'output'
                                     - may appear multiple times
        Str base-name      Base name for output file(s)
                                     - prohibits the option 'output'

     Version, usage and configuration options:

        Arg Option-Name    Description

\1f
File: autogen.info,  Node: getdefs def-selection,  Next: getdefs enumerating,  Prev: getdefs usage,  Up: getdefs Invocation

8.6.2 def-selection options
---------------------------

Specify which definitions are of interest and what to say about them.

defs-to-get option.
...................

This is the "regexp to look for after the "/*="" option.  This option
takes a string argument 'reg-ex'.  If you want definitions only from a
particular category, or even with names matching particular patterns,
then specify this regular expression for the text that must follow the
'/*='.

subblock option.
................

This is the "subblock definition names" option.  This option takes a
string argument 'sub-def'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   This option is used to create shorthand entries for nested
definitions.  For example, with:
using subblock thus
     '--subblock=arg=argname,type,null'
and defining an 'arg' thus
     'arg: this, char *'
will then expand to:
     'arg = { argname = this; type = "char *"; };'
   The "this, char *" string is separated at the commas, with the white
space removed.  You may use characters other than commas by starting the
value string with a punctuation character other than a single or double
quote character.  You may also omit intermediate values by placing the
commas next to each other with no intervening white space.  For example,
"+mumble++yes+" will expand to:
'arg = { argname = mumble; null = "yes"; };'.

listattr option.
................

This is the "attribute with list of values" option.  This option takes a
string argument 'def'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   This option is used to create shorthand entries for definitions that
generally appear several times.  That is, they tend to be a list of
values.  For example, with:
'listattr=foo' defined, the text:
'foo: this, is, a, multi-list' will then expand to:
'foo = 'this', 'is', 'a', 'multi-list';'
The texts are separated by the commas, with the white space removed.
You may use characters other than commas by starting the value string
with a punctuation character other than a single or double quote
character.

\1f
File: autogen.info,  Node: getdefs enumerating,  Next: getdefs doc-insert,  Prev: getdefs def-selection,  Up: getdefs Invocation

8.6.3 enumerating options
-------------------------

specify how to number the definitions.

ordering option.
................

This is the "alphabetize or use named file" option.  This option takes
an optional string argument 'file-name'.

This option has some usage constraints.  It:
   * can be disabled with -no-ordering.
   * It is enabled by default.

   By default, ordering is alphabetical by the entry name.  Use,
'no-ordering' if order is unimportant.  Use 'ordering' with no argument
to order without case sensitivity.  Use 'ordering=<file-name>' if
chronological order is important.  getdefs will maintain the text
content of 'file-name'.  'file-name' need not exist.

first-index option.
...................

This is the "the first index to apply to groups" option.  This option
takes a number argument 'first-index'.  By default, the first occurrence
of a named definition will have an index of zero.  Sometimes, that needs
to be a reserved value.  Provide this option to specify a different
starting point.

\1f
File: autogen.info,  Node: getdefs doc-insert,  Next: getdefs input-files,  Prev: getdefs enumerating,  Up: getdefs Invocation

8.6.4 doc-insert options
------------------------

Definition insertion options.

filelist option.
................

This is the "insert source file names into defs" option.  This option
takes an optional string argument 'file'.  Inserts the name of each
input file into the output definitions.  If no argument is supplied, the
format will be:
     infile = '%s';
   If an argument is supplied, that string will be used for the entry
name instead of INFILE.

assign option.
..............

This is the "global assignments" option.  This option takes a string
argument 'ag-def'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   The argument to each copy of this option will be inserted into the
output definitions, with only a semicolon attached.

common-assign option.
.....................

This is the "assignments common to all blocks" option.  This option
takes a string argument 'ag-def'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   The argument to each copy of this option will be inserted into each
output definition, with only a semicolon attached.

copy option.
............

This is the "file(s) to copy into definitions" option.  This option
takes a string argument 'file'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   The content of each file named by these options will be inserted into
the output definitions.

srcfile option.
...............

This is the "insert source file name into each def" option.  This option
takes an optional string argument 'file'.  Inserts the name of the input
file where a definition was found into the output definition.  If no
argument is supplied, the format will be:
     srcfile = '%s';
   If an argument is supplied, that string will be used for the entry
name instead of SRCFILE.

linenum option.
...............

This is the "insert source line number into each def" option.  This
option takes an optional string argument 'def-name'.  Inserts the line
number in the input file where a definition was found into the output
definition.  If no argument is supplied, the format will be:
     linenum = '%s';
   If an argument is supplied, that string will be used for the entry
name instead of LINENUM.

\1f
File: autogen.info,  Node: getdefs input-files,  Next: getdefs doc-output,  Prev: getdefs doc-insert,  Up: getdefs Invocation

8.6.5 input-files options
-------------------------

specify which files to search for markers.

input option.
.............

This is the "input file to search for defs" option.  This option takes a
string argument 'src-file'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   All files that are to be searched for definitions must be named on
the command line or read from 'stdin'.  If there is only one 'input'
option and it is the string, "-", then the input file list is read from
'stdin'.  If a command line argument is not an option name and does not
contain an assignment operator ('='), then it defaults to being an input
file name.  At least one input file must be specified.

\1f
File: autogen.info,  Node: getdefs doc-output,  Next: getdefs config,  Prev: getdefs input-files,  Up: getdefs Invocation

8.6.6 doc-output options
------------------------

Definition output disposition options:.

output option.
..............

This is the "output file to open" option.  This option takes a string
argument 'file'.

This option has some usage constraints.  It:
   * is a member of the autogen class of options.

   If you are not sending the output to an AutoGen process, you may name
an output file instead.

autogen option.
...............

This is the "invoke autogen with defs" option.  This option takes an
optional string argument 'ag-cmd'.

This option has some usage constraints.  It:
   * can be disabled with -no-autogen.
   * It is enabled by default.
   * is a member of the autogen class of options.

   This is the default output mode.  Specifying 'no-autogen' is
equivalent to 'output=-'.  If you supply an argument to this option,
that program will be started as if it were AutoGen and its standard in
will be set to the output definitions of this program.

template option.
................

This is the "template name" option.  This option takes a string argument
'file'.  Specifies the template name to be used for generating the final
output.

agarg option.
.............

This is the "autogen argument" option.  This option takes a string
argument 'ag-opt'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.
   * must not appear in combination with any of the following options:
     output.

   This is a pass-through argument.  It allows you to specify any
arbitrary argument to be passed to AutoGen.

base-name option.
.................

This is the "base name for output file(s)" option.  This option takes a
string argument 'name'.

This option has some usage constraints.  It:
   * must not appear in combination with any of the following options:
     output.

   When output is going to AutoGen, a base name must either be supplied
or derived.  If this option is not supplied, then it is taken from the
'template' option.  If that is not provided either, then it is set to
the base name of the current directory.

\1f
File: autogen.info,  Node: getdefs config,  Next: getdefs exit status,  Prev: getdefs doc-output,  Up: getdefs Invocation

8.6.7 presetting/configuring getdefs
------------------------------------

Any option that is not marked as not presettable may be preset by
loading values from configuration ("rc" or "ini") files.

'libopts' will search in '/dev/null' for configuration (option) data.
If this is a plain file, it is simply processed.  If it is a directory,
then a file named '.getdefsrc' is searched for within that directory.

   Configuration files may be in a wide variety of formats.  The basic
format is an option name followed by a value (argument) on the same
line.  Values may be separated from the option name with a colon, equal
sign or simply white space.  Values may be continued across multiple
lines by escaping the newline with a backslash.

   Multiple programs may also share the same initialization file.
Common options are collected at the top, followed by program specific
segments.  The segments are separated by lines like:
     [GETDEFS]
or by
     <?program getdefs>
Do not mix these styles within one configuration file.

   Compound values and carefully constructed string values may also be
specified using XML syntax:
     <option-name>
        <sub-opt>...&lt;...&gt;...</sub-opt>
     </option-name>
yielding an 'option-name.sub-opt' string value of
     "...<...>..."
   'AutoOpts' does not track suboptions.  You simply note that it is a
hierarchicly valued option.  'AutoOpts' does provide a means for
searching the associated name/value pair list (see: optionFindValue).

   The command line options relating to configuration and/or usage help
are:

version
.......

Print the program version to standard out, optionally with licensing
information, then exit 0.  The optional argument specifies how much
licensing detail to provide.  The default is to print just the version.
The licensing information may be selected with an option argument.  Only
the first letter of the argument is examined:

'version'
     Only print the version.  This is the default.
'copyright'
     Name the copyright usage licensing terms.
'verbose'
     Print the full copyright usage licensing terms.

\1f
File: autogen.info,  Node: getdefs exit status,  Next: getdefs See Also,  Prev: getdefs config,  Up: getdefs Invocation

8.6.8 getdefs exit status
-------------------------

One of the following exit values will be returned:
'0 (EXIT_SUCCESS)'
     Successful program execution.
'1 (EXIT_FAILURE)'
     The operation failed or the command syntax was not valid.
'2 (EXIT_INVALID_INPUT)'
     An input file was specified that is not a file
'3 (EXIT_NO_MEM)'
     Insufficient memory for operation
'66 (EX_NOINPUT)'
     A specified configuration file could not be loaded.
'70 (EX_SOFTWARE)'
     libopts had an internal operational error.  Please report it to
     autogen-users@lists.sourceforge.net.  Thank you.

\1f
File: autogen.info,  Node: getdefs See Also,  Prev: getdefs exit status,  Up: getdefs Invocation

8.6.9 getdefs See Also
----------------------

This program is documented more fully in the Getdefs section of the
Add-On chapter in the 'AutoGen' Info system documentation.

\1f
File: autogen.info,  Node: xml2ag Invocation,  Next: snprintfv,  Prev: getdefs Invocation,  Up: Add-Ons

8.7 Invoking xml2ag
===================

This program will convert any arbitrary XML file into equivalent AutoGen
definitions, and invoke AutoGen.  The template used will be derived from
either:
   * The *-override-tpl* command line option
   * A top level XML attribute named, "'template'"
One or the other *must* be provided, or the program will exit with a
failure message.

   The _base-name_ for the output will similarly be either:
   * The *-base-name* command line option.
   * The base name of the '.xml' file.

   The definitions derived from XML generally have an extra layer of
definition.  Specifically, this XML input:
     <mumble attr="foo">
       mumble-1
       <grumble>
       grumble, grumble, grumble.
     </grumble>mumble, mumble
     </mumble>
   Will get converted into this:
     mumble = {
       grumble = {
         text = 'grumble, grumble, grumble';
       };
       text = 'mumble-1';
       text = 'mumble, mumble';
     };
   Please notice that some information is lost.  AutoGen cannot tell
that "grumble" used to lie between the mumble texts.  Also please note
that you cannot assign:
     grumble = 'grumble, grumble, grumble.';
   because if another "grumble" has an attribute or multiple texts, it
becomes impossible to have the definitions be the same type (compound or
text values).

   This section was generated by *AutoGen*, using the 'agtexi-cmd'
template and the option descriptions for the 'xml2ag' program.  This
software is released under the GNU General Public License, version 3 or
later.

* Menu:

* xml2ag usage::                  xml2ag help/usage ('--help')
* xml2ag the-xml2ag-option::      the-xml2ag-option options
* xml2ag autogen-options::        autogen-options options
* xml2ag exit status::            exit status

\1f
File: autogen.info,  Node: xml2ag usage,  Next: xml2ag the-xml2ag-option,  Up: xml2ag Invocation

8.7.1 xml2ag help/usage ('--help')
----------------------------------

This is the automatically generated usage text for xml2ag.

   The text printed is the same whether selected with the 'help' option
('--help') or the 'more-help' option ('--more-help').  'more-help' will
print the usage text by passing it through a pager program.  'more-help'
is disabled on platforms without a working 'fork(2)' function.  The
'PAGER' environment variable is used to select the program, defaulting
to 'more'.  Both will exit with a status code of 0.

     xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.18.16
     Usage:  xml2ag [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ]

     All other options are derived from autogen:

       Flg Arg Option-Name    Description
        -O Str output         Output file in lieu of AutoGen processing

     All other options:

       Flg Arg Option-Name    Description
        -L Str templ-dirs     Search for templates in DIR
                                     - may appear multiple times
        -T Str override-tpl   Use TPL-FILE for the template
           Str definitions    Read definitions from FILE
           Str shell          name or path name of shell to use
        -m no  no-fmemopen    Do not use in-mem streams
           Str equate         characters considered equivalent
        -b Str base-name      Specify NAME as the base name for output
           no  source-time    set mod times to latest source
           no  writable       Allow output files to be writable
                                     - disabled as '--not-writable'
           Num loop-limit     Limit on increment loops
                                     - is scalable with a suffix: k/K/m/M/g/G/t/T
                                     - it must lie in one of the ranges:
                                       -1 exactly, or
                                       1 to 16777216
        -t Num timeout        Limit server shell operations to SECONDS
                                     - it must be in the range:
                                       0 to 3600
           KWd trace          tracing level of detail
           Str trace-out      tracing output file or filter
           no  show-defs      Show the definition tree
           no  used-defines   Show the definitions used
        -C no  core           Leave a core dump on a failure exit
        -s Str skip-suffix    Skip the file with this SUFFIX
                                     - prohibits the option 'select-suffix'
                                     - may appear multiple times
        -o Str select-suffix  specify this output suffix
                                     - may appear multiple times
        -D Str define         name to add to definition list
                                     - may appear multiple times
        -U Str undefine       definition list removal pattern
                                     - an alternate for 'define'
        -M opt make-dep       emit make dependency file
                                     - may appear multiple times

     Version, usage and configuration options:

       Flg Arg Option-Name    Description
        -v opt version        output version information and exit
        -? no  help           display extended usage information and exit
        -! no  more-help      extended usage information passed thru pager

     Options are specified by doubled hyphens and their name or by a single
     hyphen and the flag character.
     This program will convert any arbitrary XML file into equivalent AutoGen
     definitions, and invoke AutoGen.

     The valid "trace" option keywords are:
       nothing       debug-message server-shell  templates     block-macros
       expressions   everything
       or an integer from 0 through 6
     The template will be derived from either: * the ``--override-tpl'' command
     line option * a top level XML attribute named, "template"

     The ``base-name'' for the output will similarly be either: * the
     ``--base-name'' command line option * the base name of the .xml file

     Please send bug reports to:  <autogen-users@lists.sourceforge.net>

\1f
File: autogen.info,  Node: xml2ag the-xml2ag-option,  Next: xml2ag autogen-options,  Prev: xml2ag usage,  Up: xml2ag Invocation

8.7.2 the-xml2ag-option options
-------------------------------

All other options are derived from autogen.

output option (-O).
...................

This is the "output file in lieu of autogen processing" option.  This
option takes a string argument 'file'.  By default, the output is handed
to an AutoGen for processing.  However, you may save the definitions to
a file instead.

\1f
File: autogen.info,  Node: xml2ag autogen-options,  Next: xml2ag exit status,  Prev: xml2ag the-xml2ag-option,  Up: xml2ag Invocation

8.7.3 autogen-options options
-----------------------------

All other options.  These options are mostly just passed throug to
'autogen'.  The one exception is '--override-tpl' which replaces the
default template in the output definitions.  It does not get passed
through on the command line.

templ-dirs option (-L).
.......................

This is the "search for templates in 'dir'" option.  This option takes a
string argument 'DIR'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

override-tpl option (-T).
.........................

This is the "use 'tpl-file' for the template" option.  This option takes
a string argument 'TPL-FILE'.  Pass-through AutoGen argument

definitions option.
...................

This is the "read definitions from 'file'" option.  This option takes a
string argument 'FILE'.  Pass-through AutoGen argument

shell option.
.............

This is the "name or path name of shell to use" option.  This option
takes a string argument 'shell'.  Pass-through AutoGen argument

no-fmemopen option (-m).
........................

This is the "do not use in-mem streams" option.  Pass-through AutoGen
argument

equate option.
..............

This is the "characters considered equivalent" option.  This option
takes a string argument 'char-list'.  Pass-through AutoGen argument

base-name option (-b).
......................

This is the "specify 'name' as the base name for output" option.  This
option takes a string argument 'NAME'.  Pass-through AutoGen argument

source-time option.
...................

This is the "set mod times to latest source" option.  Pass-through
AutoGen argument

writable option.
................

This is the "allow output files to be writable" option.

This option has some usage constraints.  It:
   * can be disabled with -not-writable.

   Pass-through AutoGen argument

loop-limit option.
..................

This is the "limit on increment loops" option.  This option takes a
number argument 'lim'.  Pass-through AutoGen argument

timeout option (-t).
....................

This is the "limit server shell operations to 'seconds'" option.  This
option takes a number argument 'SECONDS'.  Pass-through AutoGen argument

trace option.
.............

This is the "tracing level of detail" option.  This option takes a
keyword argument 'level'.

This option has some usage constraints.  It:
   * This option takes a keyword as its argument.  The argument sets an
     enumeration value that can be tested by comparing the option value
     macro (OPT_VALUE_TRACE). The available keywords are:
              nothing       debug-message server-shell
              templates     block-macros  expressions
              everything

     or their numeric equivalent.

   Pass-through AutoGen argument

trace-out option.
.................

This is the "tracing output file or filter" option.  This option takes a
string argument 'file'.  Pass-through AutoGen argument

show-defs option.
.................

This is the "show the definition tree" option.  Pass-through AutoGen
argument

used-defines option.
....................

This is the "show the definitions used" option.  Pass-through AutoGen
argument

core option (-C).
.................

This is the "leave a core dump on a failure exit" option.

This option has some usage constraints.  It:
   * must be compiled in by defining 'HAVE_SYS_RESOURCE_H' during the
     compilation.

   Many systems default to a zero sized core limit.  If the system has
the sys/resource.h header and if this option is supplied, then in the
failure exit path, autogen will attempt to set the soft core limit to
whatever the hard core limit is.  If that does not work, then an
administrator must raise the hard core size limit.

skip-suffix option (-s).
........................

This is the "skip the file with this 'suffix'" option.  This option
takes a string argument 'SUFFIX'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.
   * must not appear in combination with any of the following options:
     select-suffix.

   Pass-through AutoGen argument

select-suffix option (-o).
..........................

This is the "specify this output suffix" option.  This option takes a
string argument 'SUFFIX'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

define option (-D).
...................

This is the "name to add to definition list" option.  This option takes
a string argument 'value'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

undefine option (-U).
.....................

This is the "definition list removal pattern" option.  This option takes
a string argument 'name-pat'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

make-dep option (-M).
.....................

This is the "emit make dependency file" option.  This option takes an
optional string argument 'type'.

This option has some usage constraints.  It:
   * may appear an unlimited number of times.

   Pass-through AutoGen argument

\1f
File: autogen.info,  Node: xml2ag exit status,  Prev: xml2ag autogen-options,  Up: xml2ag Invocation

8.7.4 xml2ag exit status
------------------------

One of the following exit values will be returned:
'0 (EXIT_SUCCESS)'
     Successful program execution.
'1 (EXIT_FAILURE)'
     The operation failed or the command syntax was not valid.

\1f
File: autogen.info,  Node: snprintfv,  Prev: xml2ag Invocation,  Up: Add-Ons

8.8 Replacement for Stdio Formatting Library
============================================

Using the 'printf' formatting routines in a portable fashion has always
been a pain, and this package has been way more pain than anyone ever
imagined.  Hopefully, with this release of snprintfv, the pain is now
over for all time.

   The issues with portable usage are these:

  1. Argument number specifiers are often either not implemented or are
     buggy.  Even GNU libc, version 1 got it wrong.

  2. ANSI/ISO "forgot" to provide a mechanism for computing argument
     lists for vararg procedures.

  3. The argument array version of printf ('printfv()') is not generally
     available, does not work with the native printf, and does not have
     a working argument number specifier in the format specification.
     (Last I knew, anyway.)

  4. You cannot fake varargs by calling 'vprintf()' with an array of
     arguments, because ANSI does not require such an implementation and
     some vendors play funny tricks because they are allowed to.

   These four issues made it impossible for AutoGen to ship without its
own implementation of the 'printf' formatting routines.  Since we were
forced to do this, we decided to make the formatting routines both
better and more complete :-).  We addressed these issues and added the
following features to the common printf API:

  5. The formatted output can be written to

        * a string allocated by the formatting function ('asprintf()').
        * a file descriptor instead of a file stream ('dprintf()').
        * a user specified stream ('stream_printf()').

  6. The formatting functions can be augmented with your own functions.
     These functions are allowed to consume more than one character from
     the format, but must commence with a unique character.  For
     example,

          "%{struct stat}\n"

     might be used with '{' registered to a procedure that would look up
     "struct stat" in a symbol table and do appropriate things,
     consuming the format string through the '}' character.

   Gary V. Vaughan was generous enough to supply this implementation.
Many thanks!!

   For further details, the reader is referred to the snprintfv
documentation.  These functions are also available in the template
processing as 'sprintf' (*note SCM sprintf::), 'printf' (*note SCM
printf::), 'fprintf' (*note SCM fprintf::), and 'shellf' (*note SCM
shellf::).

\1f
File: autogen.info,  Node: Future,  Next: Copying This Manual,  Prev: Add-Ons,  Up: Top

9 Some ideas for the future.
****************************

Here are some things that might happen in the distant future.

   * Fix up current tools that contain miserably complex perl, shell,
     sed, awk and m4 scripts to instead use this tool.

\1f
File: autogen.info,  Node: Copying This Manual,  Next: Concept Index,  Prev: Future,  Up: Top

Appendix A Copying This Manual
******************************

You may copy this manual under the terms of the FDL (the GNU Free
Documentation License (http://gnu.org/licenses/fdl.texi)).

\1f
File: autogen.info,  Node: Concept Index,  Next: Function Index,  Prev: Copying This Manual,  Up: Top

Concept Index
*************

\0\b[index\0\b]
* Menu:

* .:                                     naming values.       (line  23)
* .def file:                             Definitions File.    (line   6)
* .tpl file:                             Template File.       (line   6)
* Alternate Definition:                  Alternate Definition.
                                                              (line   6)
* assert:                                Directives.          (line  26)
* assert directive:                      Directives.          (line  26)
* Augmenting AutoGen:                    Augmenting AutoGen.  (line   6)
* AutoEvents:                            AutoEvents.          (line   6)
* AutoFSM:                               AutoFSM.             (line   6)
* autogen:                               autogen Invocation.  (line   6)
* AutoGen Definition Extraction Tool:    getdefs Invocation.  (line   6)
* autogen help:                          autogen usage.       (line   6)
* autogen-base-name:                     autogen out-handling.
                                                              (line  11)
* autogen-core:                          autogen debug-tpl.   (line 138)
* autogen-define:                        autogen processing.  (line  46)
* autogen-definitions:                   autogen input-select.
                                                              (line  40)
* autogen-equate:                        autogen input-select.
                                                              (line  90)
* autogen-loop-limit:                    autogen debug-tpl.   (line  13)
* autogen-make-dep:                      autogen dep-track.   (line  11)
* autogen-no-abort:                      autogen autoopts-opts.
                                                              (line  11)
* autogen-no-fmemopen:                   autogen input-select.
                                                              (line  74)
* autogen-override-tpl:                  autogen input-select.
                                                              (line  26)
* autogen-select-suffix:                 autogen processing.  (line  31)
* autogen-shell:                         autogen input-select.
                                                              (line  58)
* autogen-show-defs:                     autogen debug-tpl.   (line 106)
* autogen-skip-suffix:                   autogen processing.  (line  13)
* autogen-source-time:                   autogen out-handling.
                                                              (line  33)
* autogen-templ-dirs:                    autogen input-select.
                                                              (line  12)
* autogen-timeout:                       autogen debug-tpl.   (line  23)
* autogen-trace:                         autogen debug-tpl.   (line  40)
* autogen-trace-out:                     autogen debug-tpl.   (line  95)
* autogen-undefine:                      autogen processing.  (line  76)
* autogen-used-defines:                  autogen debug-tpl.   (line 120)
* autogen-writable:                      autogen out-handling.
                                                              (line  47)
* AutoInfo:                              AutoInfo.            (line   6)
* AutoMan pages:                         AutoMan pages.       (line   6)
* automatic options:                     automatic options.   (line   6)
* autoopts:                              AutoOpts.            (line   6)
* autoopts <1>:                          Caveats.             (line  34)
* AutoOpts API:                          AutoOpts API.        (line   6)
* autoopts directives:                   config directives.   (line   6)
* AutoXDR:                               AutoXDR.             (line   6)
* backtrack:                             naming values.       (line  24)
* Columnize Input Text:                  columns Invocation.  (line   6)
* columns:                               columns Invocation.  (line   6)
* columns help:                          columns usage.       (line   6)
* columns-by-columns:                    columns ordering.    (line  11)
* columns-col-width:                     columns dimensions.  (line  29)
* columns-columns:                       columns dimensions.  (line  21)
* columns-ending:                        columns treatment.   (line  89)
* columns-fill:                          columns treatment.   (line  20)
* columns-first-indent:                  columns treatment.   (line  42)
* columns-format:                        columns treatment.   (line  67)
* columns-indent:                        columns treatment.   (line  34)
* columns-input:                         columns input-text.  (line  11)
* columns-line-separation:               columns treatment.   (line  82)
* columns-separation:                    columns treatment.   (line  75)
* columns-sort:                          columns ordering.    (line  19)
* columns-spread:                        columns treatment.   (line  11)
* columns-tab-width:                     columns dimensions.  (line  37)
* columns-width:                         columns dimensions.  (line  11)
* comments:                              Comments.            (line   6)
* Common Option Attributes:              Common Attributes.   (line   6)
* compound definitions:                  Definitions.         (line  43)
* concat-string:                         concat-string.       (line   6)
* conditional emit:                      IF.                  (line   6)
* conditional emit <1>:                  WHILE.               (line   6)
* configuration file:                    opt-attr no-preset.  (line   6)
* configuration file <1>:                automatic options.   (line  67)
* configuration file <2>:                automatic options.   (line  83)
* configuration file <3>:                Option Processing Data.
                                                              (line  40)
* Configuration File:                    config example.      (line   6)
* Configuration File <1>:                Config File Format.  (line   6)
* configuration file <4>:                shell options.       (line   6)
* Configuration File example:            config example.      (line   6)
* configuring:                           configuring.         (line   6)
* define:                                Directives.          (line  41)
* define directive:                      Directives.          (line  41)
* define macro:                          DEFINE.              (line   6)
* Definition Index:                      Index Assignments.   (line   6)
* definitions:                           Definitions.         (line   6)
* definitions file:                      Definitions File.    (line   6)
* design goals:                          Generalities.        (line  11)
* directives:                            Directives.          (line   6)
* diversion:                             output controls.     (line   6)
* documentation attributes:              documentation attributes.
                                                              (line   6)
* Dynamic Definition Text:               Dynamic Text.        (line   6)
* elif:                                  Directives.          (line  49)
* elif directive:                        Directives.          (line  49)
* else:                                  Directives.          (line  53)
* else directive:                        Directives.          (line  53)
* endif:                                 Directives.          (line  58)
* endif directive:                       Directives.          (line  58)
* endmac:                                Directives.          (line  62)
* endmac directive:                      Directives.          (line  62)
* endshell:                              Directives.          (line  65)
* endshell directive:                    Directives.          (line  65)
* environrc:                             environrc.           (line   6)
* error:                                 Directives.          (line  68)
* error directive:                       Directives.          (line  68)
* example, simple AutoGen:               Example Usage.       (line   6)
* example, simple AutoOpts:              Quick Start.         (line   6)
* expression syntax:                     expression syntax.   (line   6)
* features:                              Features.            (line   6)
* finite state machine:                  AutoFSM.             (line   6)
* flags-cant:                            Option Conflict Attributes.
                                                              (line  19)
* flags-must:                            Option Conflict Attributes.
                                                              (line  15)
* fOptState:                             Option Processing Data.
                                                              (line  28)
* for loop:                              FOR.                 (line   6)
* futures:                               Future.              (line   6)
* getdefs:                               getdefs Invocation.  (line   6)
* getdefs help:                          getdefs usage.       (line   6)
* getdefs-agarg:                         getdefs doc-output.  (line  46)
* getdefs-assign:                        getdefs doc-insert.  (line  22)
* getdefs-autogen:                       getdefs doc-output.  (line  23)
* getdefs-base-name:                     getdefs doc-output.  (line  60)
* getdefs-common-assign:                 getdefs doc-insert.  (line  34)
* getdefs-copy:                          getdefs doc-insert.  (line  46)
* getdefs-defs-to-get:                   getdefs def-selection.
                                                              (line  11)
* getdefs-filelist:                      getdefs doc-insert.  (line  11)
* getdefs-first-index:                   getdefs enumerating. (line  27)
* getdefs-input:                         getdefs input-files. (line  11)
* getdefs-linenum:                       getdefs doc-insert.  (line  69)
* getdefs-listattr:                      getdefs def-selection.
                                                              (line  45)
* getdefs-ordering:                      getdefs enumerating. (line  11)
* getdefs-output:                        getdefs doc-output.  (line  11)
* getdefs-srcfile:                       getdefs doc-insert.  (line  58)
* getdefs-subblock:                      getdefs def-selection.
                                                              (line  20)
* getdefs-template:                      getdefs doc-output.  (line  39)
* getopt_long:                           getopt_long.         (line   6)
* gnu:                                   Caveats.             (line  29)
* here-string:                           here-string.         (line   6)
* ident:                                 Directives.          (line  72)
* ident directive:                       Directives.          (line  72)
* identification:                        Identification.      (line   6)
* if:                                    Directives.          (line  75)
* if directive:                          Directives.          (line  75)
* if test:                               IF.                  (line   6)
* ifdef:                                 Directives.          (line  79)
* ifdef directive:                       Directives.          (line  79)
* ifndef:                                Directives.          (line  85)
* ifndef directive:                      Directives.          (line  85)
* immediate action:                      Immediate Action.    (line   6)
* include:                               Directives.          (line  89)
* include directive:                     Directives.          (line  89)
* information attributes:                information attributes.
                                                              (line   6)
* Installing:                            installing.          (line   6)
* Internationalizing AutoOpts:           i18n.                (line   6)
* Internationalizing Options:            Internationalizing Options.
                                                              (line   6)
* Introduction:                          Introduction.        (line   6)
* let:                                   Directives.          (line  94)
* let directive:                         Directives.          (line  94)
* library attributes:                    library attributes.  (line   6)
* Licensing:                             Licensing.           (line   6)
* line:                                  Directives.          (line  97)
* line directive:                        Directives.          (line  97)
* looping, for:                          FOR.                 (line   6)
* m4:                                    Testimonial.         (line  41)
* macdef:                                Directives.          (line 104)
* macdef directive:                      Directives.          (line 104)
* macro syntax:                          AGMacro syntax.      (line   6)
* macro, pseudo:                         Template File.       (line  10)
* main procedure:                        Generated main.      (line   6)
* misuse-usage:                          Caveats.             (line  45)
* named option mode:                     presentation attributes.
                                                              (line  15)
* Naming Conflicts:                      Naming Conflicts.    (line   6)
* naming values:                         naming values.       (line   6)
* native macros:                         native macros.       (line   6)
* no-misuse-usage:                       Caveats.             (line  40)
* optActualIndex:                        Option Processing Data.
                                                              (line  16)
* optActualValue:                        Option Processing Data.
                                                              (line  17)
* optIndex:                              Option Processing Data.
                                                              (line  11)
* option:                                Directives.          (line 110)
* Option Argument Handling:              Option Argument Handling.
                                                              (line   6)
* Option Arguments:                      Option Arguments.    (line   6)
* option attributes:                     option attributes.   (line   6)
* Option Conflict Attributes:            Option Conflict Attributes.
                                                              (line   6)
* Option Definitions:                    Option Definitions.  (line   6)
* option descriptor:                     option descriptor.   (line   6)
* option directive:                      Directives.          (line 110)
* Option Processing Data:                Option Processing Data.
                                                              (line   6)
* optOccCt:                              Option Processing Data.
                                                              (line  22)
* optValue:                              Option Processing Data.
                                                              (line  12)
* pragma:                                Directives.          (line 125)
* pragma directive:                      Directives.          (line 125)
* predefines:                            Predefines.          (line   6)
* program attributes:                    program attributes.  (line   6)
* pseudo macro:                          Template File.       (line  10)
* pseudo macro <1>:                      pseudo macro.        (line   6)
* pzLastArg:                             Option Processing Data.
                                                              (line  80)
* pzProgName:                            Option Processing Data.
                                                              (line  87)
* pzProgPath:                            Option Processing Data.
                                                              (line  91)
* rcfile:                                loading rcfile.      (line   6)
* rcfile <1>:                            config example.      (line   6)
* Redirecting Output:                    output controls.     (line   6)
* remote procedure call:                 AutoXDR.             (line   6)
* Required Attributes:                   Required Attributes. (line   6)
* RPC:                                   AutoXDR.             (line   6)
* rpcgen:                                AutoXDR.             (line   6)
* sample rcfile:                         sample rcfile.       (line   6)
* shell:                                 Directives.          (line 128)
* shell directive:                       Directives.          (line 128)
* shell options:                         Presetting Options.  (line   6)
* shell options <1>:                     shell options.       (line   6)
* shell-generated string:                shell-generated.     (line   6)
* Signal Names:                          signal names.        (line   6)
* simple definitions:                    Definitions.         (line  44)
* standard options:                      standard options.    (line   6)
* string, double quote:                  double-quote-string. (line   6)
* string, shell output:                  shell-generated.     (line   6)
* string, single quote:                  single-quote-string. (line   6)
* template file:                         Identification.      (line  21)
* template file <1>:                     Template File.       (line   6)
* The Automated Program Generator:       autogen Invocation.  (line   6)
* undef:                                 Directives.          (line 136)
* undef directive:                       Directives.          (line 136)
* using AutoOpts:                        Using AutoOpts.      (line   6)
* while test:                            WHILE.               (line   6)
* XDR:                                   AutoXDR.             (line   6)
* XML to AutoGen Definiton Converter:    xml2ag Invocation.   (line   6)
* xml2ag:                                xml2ag Invocation.   (line   6)
* xml2ag help:                           xml2ag usage.        (line   6)
* xml2ag-base-name:                      xml2ag autogen-options.
                                                              (line  55)
* xml2ag-core:                           xml2ag autogen-options.
                                                              (line 125)
* xml2ag-define:                         xml2ag autogen-options.
                                                              (line 164)
* xml2ag-definitions:                    xml2ag autogen-options.
                                                              (line  31)
* xml2ag-equate:                         xml2ag autogen-options.
                                                              (line  49)
* xml2ag-loop-limit:                     xml2ag autogen-options.
                                                              (line  77)
* xml2ag-make-dep:                       xml2ag autogen-options.
                                                              (line 186)
* xml2ag-no-fmemopen:                    xml2ag autogen-options.
                                                              (line  43)
* xml2ag-output:                         xml2ag the-xml2ag-option.
                                                              (line  11)
* xml2ag-override-tpl:                   xml2ag autogen-options.
                                                              (line  25)
* xml2ag-select-suffix:                  xml2ag autogen-options.
                                                              (line 153)
* xml2ag-shell:                          xml2ag autogen-options.
                                                              (line  37)
* xml2ag-show-defs:                      xml2ag autogen-options.
                                                              (line 113)
* xml2ag-skip-suffix:                    xml2ag autogen-options.
                                                              (line 140)
* xml2ag-source-time:                    xml2ag autogen-options.
                                                              (line  61)
* xml2ag-templ-dirs:                     xml2ag autogen-options.
                                                              (line  14)
* xml2ag-timeout:                        xml2ag autogen-options.
                                                              (line  83)
* xml2ag-trace:                          xml2ag autogen-options.
                                                              (line  89)
* xml2ag-trace-out:                      xml2ag autogen-options.
                                                              (line 107)
* xml2ag-undefine:                       xml2ag autogen-options.
                                                              (line 175)
* xml2ag-used-defines:                   xml2ag autogen-options.
                                                              (line 119)
* xml2ag-writable:                       xml2ag autogen-options.
                                                              (line  67)

\1f
File: autogen.info,  Node: Function Index,  Prev: Concept Index,  Up: Top

Function Index
**************

\0\b[index\0\b]
* Menu:

* *=:                                    SCM *=.                (line 6)
* *=*:                                   SCM *=*.               (line 6)
* *==:                                   SCM *==.               (line 6)
* *==*:                                  SCM *==*.              (line 6)
* *~:                                    SCM *~.                (line 6)
* *~*:                                   SCM *~*.               (line 6)
* *~~:                                   SCM *~~.               (line 6)
* *~~*:                                  SCM *~~*.              (line 6)
* =:                                     SCM =.                 (line 6)
* =*:                                    SCM =*.                (line 6)
* ==:                                    SCM ==.                (line 6)
* ==*:                                   SCM ==*.               (line 6)
* ~:                                     SCM ~.                 (line 6)
* ~*:                                    SCM ~*.                (line 6)
* ~~:                                    SCM ~~.                (line 6)
* ~~*:                                   SCM ~~*.               (line 6)
* ag-fprintf:                            SCM ag-fprintf.        (line 6)
* ag-function?:                          SCM ag-function?.      (line 6)
* agpl:                                  SCM agpl.              (line 6)
* ao_string_tokenize:                    libopts-ao_string_tokenize.
                                                                (line 6)
* autogen-version:                       SCM autogen-version.   (line 6)
* base-name:                             SCM base-name.         (line 6)
* BREAK:                                 BREAK.                 (line 6)
* bsd:                                   SCM bsd.               (line 6)
* c-file-line-fmt:                       SCM c-file-line-fmt.   (line 6)
* c-string:                              SCM c-string.          (line 6)
* CASE:                                  CASE.                  (line 6)
* chdir:                                 SCM chdir.             (line 6)
* CLEAR_OPT:                             CLEAR_OPT.             (line 6)
* COMMENT:                               COMMENT.               (line 6)
* configFileLoad:                        libopts-configFileLoad.
                                                                (line 6)
* CONTINUE:                              CONTINUE.              (line 6)
* count:                                 SCM count.             (line 6)
* COUNT_OPT:                             COUNT_OPT.             (line 6)
* DEBUG:                                 DEBUG.                 (line 6)
* def-file:                              SCM def-file.          (line 6)
* def-file-line:                         SCM def-file-line.     (line 6)
* DEFINE:                                DEFINE.                (line 6)
* DESC:                                  DESC.                  (line 6)
* DISABLE_OPT_name:                      DISABLE_OPT_name.      (line 6)
* dne:                                   SCM dne.               (line 6)
* ELIF:                                  ELIF.                  (line 6)
* ELSE:                                  ELSE.                  (line 6)
* emit:                                  SCM emit.              (line 6)
* emit-string-table:                     SCM emit-string-table. (line 6)
* ENABLED_OPT:                           ENABLED_OPT.           (line 6)
* ENDDEF:                                ENDDEF.                (line 6)
* ENDFOR:                                ENDFOR.                (line 6)
* ENDIF:                                 ENDIF.                 (line 6)
* ENDWHILE:                              ENDWHILE.              (line 6)
* error:                                 SCM error.             (line 6)
* error-source-line:                     SCM error-source-line. (line 6)
* ERRSKIP_OPTERR:                        ERRSKIP_OPTERR.        (line 6)
* ERRSTOP_OPTERR:                        ERRSTOP_OPTERR.        (line 6)
* ESAC:                                  ESAC.                  (line 6)
* exist?:                                SCM exist?.            (line 6)
* EXPR:                                  EXPR.                  (line 6)
* extract:                               SCM extract.           (line 6)
* find-file:                             SCM find-file.         (line 6)
* first-for?:                            SCM first-for?.        (line 6)
* FOR:                                   FOR.                   (line 6)
* for-by:                                SCM for-by.            (line 6)
* for-from:                              SCM for-from.          (line 6)
* for-index:                             SCM for-index.         (line 6)
* for-sep:                               SCM for-sep.           (line 6)
* for-to:                                SCM for-to.            (line 6)
* format-arg-count:                      SCM format-arg-count.  (line 6)
* found-for?:                            SCM found-for?.        (line 6)
* fprintf:                               SCM fprintf.           (line 6)
* get:                                   SCM get.               (line 6)
* get-c-name:                            SCM get-c-name.        (line 6)
* get-down-name:                         SCM get-down-name.     (line 6)
* get-up-name:                           SCM get-up-name.       (line 6)
* gperf:                                 SCM gperf.             (line 6)
* gperf-code:                            SCM gperf-code.        (line 6)
* gpl:                                   SCM gpl.               (line 6)
* HAVE_OPT:                              HAVE_OPT.              (line 6)
* hide-email:                            SCM hide-email.        (line 6)
* high-lim:                              SCM high-lim.          (line 6)
* html-escape-encode:                    SCM html-escape-encode.
                                                                (line 6)
* IF:                                    IF.                    (line 6)
* in?:                                   SCM in?.               (line 6)
* INCLUDE:                               INCLUDE.               (line 6)
* insert-file:                           SCM insert-file.       (line 6)
* insert-suspended:                      SCM insert-suspended.  (line 6)
* INVOKE:                                INVOKE.                (line 6)
* ISSEL_OPT:                             ISSEL_OPT.             (line 6)
* ISUNUSED_OPT:                          ISUNUSED_OPT.          (line 6)
* join:                                  SCM join.              (line 6)
* kr-string:                             SCM kr-string.         (line 6)
* last-for?:                             SCM last-for?.         (line 6)
* len:                                   SCM len.               (line 6)
* lgpl:                                  SCM lgpl.              (line 6)
* license:                               SCM license.           (line 6)
* license-description:                   SCM license-description.
                                                                (line 6)
* license-full:                          SCM license-full.      (line 6)
* license-info:                          SCM license-info.      (line 6)
* license-name:                          SCM license-name.      (line 6)
* low-lim:                               SCM low-lim.           (line 6)
* make-gperf:                            SCM make-gperf.        (line 6)
* make-header-guard:                     SCM make-header-guard. (line 6)
* make-tmp-dir:                          SCM make-tmp-dir.      (line 6)
* makefile-script:                       SCM makefile-script.   (line 6)
* match-value?:                          SCM match-value?.      (line 6)
* max:                                   SCM max.               (line 6)
* max-file-time:                         SCM max-file-time.     (line 6)
* min:                                   SCM min.               (line 6)
* mk-gettextable:                        SCM mk-gettextable.    (line 6)
* optionFileLoad:                        libopts-optionFileLoad.
                                                                (line 6)
* optionFindNextValue:                   libopts-optionFindNextValue.
                                                                (line 6)
* optionFindValue:                       libopts-optionFindValue.
                                                                (line 6)
* optionFree:                            libopts-optionFree.    (line 6)
* optionGetValue:                        libopts-optionGetValue.
                                                                (line 6)
* optionLoadLine:                        libopts-optionLoadLine.
                                                                (line 6)
* optionMemberList:                      libopts-optionMemberList.
                                                                (line 6)
* optionNextValue:                       libopts-optionNextValue.
                                                                (line 6)
* optionOnlyUsage:                       libopts-optionOnlyUsage.
                                                                (line 6)
* optionPrintVersion:                    libopts-optionPrintVersion.
                                                                (line 6)
* optionPrintVersionAndReturn:           libopts-optionPrintVersionAndReturn.
                                                                (line 6)
* optionProcess:                         libopts-optionProcess. (line 6)
* optionRestore:                         libopts-optionRestore. (line 6)
* optionSaveFile:                        libopts-optionSaveFile.
                                                                (line 6)
* optionSaveState:                       libopts-optionSaveState.
                                                                (line 6)
* optionUnloadNested:                    libopts-optionUnloadNested.
                                                                (line 6)
* optionVersion:                         libopts-optionVersion. (line 6)
* OPTION_CT:                             OPTION_CT.             (line 6)
* OPT_ARG:                               OPT_ARG.               (line 6)
* OPT_NO_XLAT_CFG_NAMES:                 OPT_NO_XLAT_CFG_NAMES. (line 6)
* OPT_NO_XLAT_OPT_NAMES:                 OPT_NO_XLAT_OPT_NAMES. (line 6)
* OPT_VALUE_name:                        OPT_VALUE_name.        (line 6)
* OPT_XLAT_CFG_NAMES:                    OPT_XLAT_CFG_NAMES.    (line 6)
* OPT_XLAT_OPT_NAMES:                    OPT_XLAT_OPT_NAMES.    (line 6)
* out-delete:                            SCM out-delete.        (line 6)
* out-depth:                             SCM out-depth.         (line 6)
* out-emit-suspended:                    SCM out-emit-suspended.
                                                                (line 6)
* out-line:                              SCM out-line.          (line 6)
* out-move:                              SCM out-move.          (line 6)
* out-name:                              SCM out-name.          (line 6)
* out-pop:                               SCM out-pop.           (line 6)
* out-push-add:                          SCM out-push-add.      (line 6)
* out-push-new:                          SCM out-push-new.      (line 6)
* out-resume:                            SCM out-resume.        (line 6)
* out-suspend:                           SCM out-suspend.       (line 6)
* out-switch:                            SCM out-switch.        (line 6)
* output-file-next-line:                 SCM output-file-next-line.
                                                                (line 6)
* prefix:                                SCM prefix.            (line 6)
* printf:                                SCM printf.            (line 6)
* raw-shell-str:                         SCM raw-shell-str.     (line 6)
* RESTART_OPT:                           RESTART_OPT.           (line 6)
* RETURN:                                RETURN.                (line 6)
* SELECT:                                SELECT.                (line 6)
* set-option:                            SCM set-option.        (line 6)
* set-writable:                          SCM set-writable.      (line 6)
* SET_OPT_name:                          SET_OPT_name.          (line 6)
* shell:                                 SCM shell.             (line 6)
* shell-str:                             SCM shell-str.         (line 6)
* shellf:                                SCM shellf.            (line 6)
* sprintf:                               SCM sprintf.           (line 6)
* stack:                                 SCM stack.             (line 6)
* stack-join:                            SCM stack-join.        (line 6)
* STACKCT_OPT:                           STACKCT_OPT.           (line 6)
* STACKLST_OPT:                          STACKLST_OPT.          (line 6)
* START_OPT:                             START_OPT.             (line 6)
* STATE_OPT:                             STATE_OPT.             (line 6)
* strequate:                             libopts-strequate.     (line 6)
* streqvcmp:                             libopts-streqvcmp.     (line 6)
* streqvmap:                             libopts-streqvmap.     (line 6)
* string->c-name!:                       SCM string->c-name!.   (line 6)
* string->camelcase:                     SCM string->camelcase. (line 6)
* string-capitalize:                     SCM string-capitalize. (line 6)
* string-capitalize!:                    SCM string-capitalize!.
                                                                (line 6)
* string-contains-eqv?:                  SCM *=*.               (line 6)
* string-contains?:                      SCM *==*.              (line 6)
* string-downcase:                       SCM string-downcase.   (line 6)
* string-downcase!:                      SCM string-downcase!.  (line 6)
* string-end-eqv-match?:                 SCM *~.                (line 6)
* string-end-match?:                     SCM *~~.               (line 6)
* string-ends-eqv?:                      SCM *=.                (line 6)
* string-ends-with?:                     SCM *==.               (line 6)
* string-equals?:                        SCM ==.                (line 6)
* string-eqv-match?:                     SCM ~.                 (line 6)
* string-eqv?:                           SCM =.                 (line 6)
* string-has-eqv-match?:                 SCM *~*.               (line 6)
* string-has-match?:                     SCM *~~*.              (line 6)
* string-match?:                         SCM ~~.                (line 6)
* string-start-eqv-match?:               SCM ~*.                (line 6)
* string-start-match?:                   SCM ~~*.               (line 6)
* string-starts-eqv?:                    SCM =*.                (line 6)
* string-starts-with?:                   SCM ==*.               (line 6)
* string-substitute:                     SCM string-substitute. (line 6)
* string-table-add:                      SCM string-table-add.  (line 6)
* string-table-add-ref:                  SCM string-table-add-ref.
                                                                (line 6)
* string-table-new:                      SCM string-table-new.  (line 6)
* string-table-size:                     SCM string-table-size. (line 6)
* string-tr:                             SCM string-tr.         (line 6)
* string-tr!:                            SCM string-tr!.        (line 6)
* string-upcase:                         SCM string-upcase.     (line 6)
* string-upcase!:                        SCM string-upcase!.    (line 6)
* strneqvcmp:                            libopts-strneqvcmp.    (line 6)
* strtransform:                          libopts-strtransform.  (line 6)
* sub-shell-str:                         SCM sub-shell-str.     (line 6)
* suffix:                                SCM suffix.            (line 6)
* sum:                                   SCM sum.               (line 6)
* teOptIndex:                            teOptIndex.            (line 6)
* time-string->number:                   SCM time-string->number.
                                                                (line 6)
* tpl-file:                              SCM tpl-file.          (line 6)
* tpl-file-line:                         SCM tpl-file-line.     (line 6)
* tpl-file-next-line:                    SCM tpl-file-next-line.
                                                                (line 6)
* UNKNOWN:                               UNKNOWN.               (line 6)
* USAGE:                                 USAGE.                 (line 6)
* VALUE_OPT_name:                        VALUE_OPT_name.        (line 6)
* VERSION:                               VERSION.               (line 6)
* version-compare:                       SCM version-compare.   (line 6)
* warn:                                  SCM warn.              (line 6)
* WHICH_IDX_name:                        WHICH_IDX_name.        (line 6)
* WHICH_OPT_name:                        WHICH_OPT_name.        (line 6)
* WHILE:                                 WHILE.                 (line 6)