path: root/doc/autogen.info-2

This is autogen.info, produced by makeinfo version 4.13 from
/old-home/bkorb/ag/ag/doc//agdoc.texi.

This manual is for GNU AutoGen version 5.16, updated August 2012.

   Copyright (C) 1992-2012 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.16.

   AutoGen copyright (C) 1992-2012 Bruce Korb AutoOpts copyright (C)
1992-2012 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/>.


File: autogen.info,  Node: opt-attr default option,  Next: opt-attr documentation,  Prev: opt-attr aliases,  Up: option attributes

7.5.5.9 Default Option
......................

If your program processes its arguments in named option mode (See
`long-opts' in *note program attributes::), then you may select *one*
of your options to be the default option.  Do so by using attribute
`default' with one of the options.  The option so specified must have
an `arg-type' (*note Option Arguments::) specified, but not the
`arg-optional' (*note arg-optional::) attribute.  That is to say, the
option argument must be required.

   If you have done this, then any arguments that do not match an
option name and do not contain an equal sign (`=') will be interpreted
as an option argument to the default option.


File: autogen.info,  Node: opt-attr documentation,  Next: opt-attr translators,  Prev: opt-attr default option,  Up: option attributes

7.5.5.10 Option Sectioning Comment
..................................

This attribute means the option exists for the purpose of separating
option description text in the usage output and texi documentation.
Without this attribute, every option is a separate node in the texi
docs.  With this attribute, the documentation options become texi doc
nodes and the options are collected under them.  Choose the name
attribute carefully because it will appear in the texi documentation.

   Libraries may also choose to make it settable so that the library can
determine which command line option is the first one that pertains to
the library.

   If the `documentation' attribute is present, then all other
attributes are disabled except `settable', `call-proc' and `flag-code'.
`settable' must be and is only specified if `call-proc', `extract-code'
or `flag-code' has been specified.  When present, the `descrip'
attribute will be displayed only when the `--help' option has been
specified.  It will be displayed flush to the left hand margin and may
consist of one or more lines of text, filled to 72 columns.

   The name of the option will not be printed in the help text.  It
will, however, be printed as section headers in the texi documentation.
If the attribute is given a non-empty value, this text will be
reproduced in the man page and texi doc immediately after the `descrip'
text.


File: autogen.info,  Node: opt-attr translators,  Prev: opt-attr documentation,  Up: option attributes

7.5.5.11 Translator Notes
.........................

If you need to give the translators a special note about a particular
option, please use the "`translators'" attribute.  The attribute text
will be emitted into the generated `.c' text where the option related
strings get defined.  To make a general comment about all of the option
code, add comments to an `include' attribute (*note program
attributes::).  Do *not* use this attribute globally, or it will get
emitted into every option definition block.


File: autogen.info,  Node: Option Arguments,  Next: Option Argument Handling,  Prev: option attributes,  Up: Option Definitions

7.5.6 Option Argument Specification
-----------------------------------

Command line options come in three flavors:  options that do not take
arguments, those that do and those that may.  Without an "arg-type"
attribute, AutoOpts will not process an argument to an option.  If
"arg-type" is specified and "arg-optional" is also specified, then the
next command line token will be taken to be an argument, unless it
looks like the name of another option.

   If the argument type is specified to be anything other than
"str[ing]", then AutoOpts will specify a callback procedure to handle
the argument.  Some of these procedures will be created and inserted
into the generated `.c' file, and others are already built into the
`libopts' library.  Therefore, if you write your own callback procedure
(*note Option Argument Handling::), then you must either not specify an
"arg-type" attribute, or else specify it to be of type "str[ing]".  Your
callback function will be able to place its own restrictions on what
that string may contain or represent.

   Option argument handling attributes depend upon the value set for the `arg-type'
attribute.  It specifies the type of argument the option will take.  If
not present, the option cannot take an argument.  If present, it must
be an entry in the following table.  The first three letters is
sufficient.

* Menu:

* arg-type string::         Arg Type String
* arg-type number::         Arg Type Number
* arg-type boolean::        Arg Type Boolean
* arg-type keyword::        Arg Type Keyword
* arg-type set membership:: Arg Type Set Membership
* arg-type hierarchy::      Arg Type Hierarchical
* arg-type file name::      Arg Type File Name
* arg-type time-duration::  Arg Type Time Duration
* arg-type time-date::      Arg Type Time and Date

Supporting attributes for particular argument types:

* arg-keyword::             Keyword list
* arg-optional::            Option Argument Optional
* arg-default::             Default Option Argument Value


File: autogen.info,  Node: arg-type string,  Next: arg-type number,  Up: Option Arguments

7.5.6.1 Arg Type String
.......................

`arg-type = string;'

   The argument may be any arbitrary string, though your program or
option callback procedure may place additional constraints upon it.


File: autogen.info,  Node: arg-type number,  Next: arg-type boolean,  Prev: arg-type string,  Up: Option Arguments

7.5.6.2 Arg Type Number
.......................

`arg-type = number;'

   The argument must be a correctly formed integer, without any
trailing U's or L's.  AutoOpts contains a library procedure to convert
the string to a number.  If you specify range checking with `arg-range'
(see below), then AutoOpts produces a special purpose procedure for
this option.

`scaled'
     `scaled' marks the option so that suffixes of `k', `K', `m', `M',
     `g', `G', `t', and `T' will multiply the given number by a power
     of 1000 or 1024.  Lower case letters scale by a power of 1000 and
     upper case scale by a power of 1024.

`arg-range'
     `arg-range' is used to create a callback procedure for validating
     the range of the option argument.  It must match one of the range
     entries.  Each `arg-range' should consist of either an integer by
     itself or an integer range.  The integer range is specified by one
     or two integers separated by the two character sequence, `->'.  Be
     sure to quote the entire range string.  The definitions parser
     will not accept the range syntax as a single string token.

     The generated procedure imposes the range constraints as follows:
        * A number by itself will match that one value.

        * The high end of the range may not be `INT_MIN', both for
          obvious reasons and because that value is used to indicate a
          single-valued match.

        * An omitted lower value implies a lower bound of INT_MIN.

        * An omitted upper value implies a upper bound of INT_MAX.

        * The argument value is required.  It may not be optional.

        * The value must match one of the entries.  If it can match
          more than one, then you have redundancies, but no harm will
          come of it.


File: autogen.info,  Node: arg-type boolean,  Next: arg-type keyword,  Prev: arg-type number,  Up: Option Arguments

7.5.6.3 Arg Type Boolean
........................

`arg-type = boolean;'

   The argument will be interpreted and always yield either AG_TRUE or
AG_FALSE.  False values are  the empty string, the number zero, or a
string that starts with `f', `F', `n' or `N' (representing False or
No).  Anything else will be interpreted as True.


File: autogen.info,  Node: arg-type keyword,  Next: arg-type set membership,  Prev: arg-type boolean,  Up: Option Arguments

7.5.6.4 Arg Type Keyword
........................

`arg-type = keyword;'

   The argument must match a specified list of strings (*note
arg-keyword::).  Assuming you have named the option, `optn-name', the
strings will be converted into an enumeration of type `te_Optn_Name'
with the values `OPTN_NAME_KEYWORD'.*  If you have *not* specified a
default value, the value `OPTN_NAME_UNDEFINED' will be inserted with
the value zero.  The option will be initialized to that value.  You may
now use this in your code as follows:

    te_Optn_Name opt = OPT_VALUE_OPTN_NAME;
    switch (opt) {
    case OPTN_NAME_UNDEFINED:  /* undefined things */ break;
    case OPTN_NAME_KEYWORD:    /* `keyword' things */ break;
    default: /* utterly impossible */ ;
    }

   AutoOpts produces a special purpose procedure for this option.  You
may not specify an alternate handling procedure.

   If you have need for the string name of the selected keyword, you
may obtain this with the macro, `OPT_OPTN_NAME_VAL2STR(val)'.  The
value you pass would normally be `OPT_VALUE_OPTN_NAME', but anything
with numeric value that is legal for `te_Optn_Name' may be passed.
Anything out of range will result in the string, `"*INVALID*"' being
returned.  The strings are read only.  It may be used as in:

    te_Optn_Name opt = OPT_VALUE_OPTN_NAME;
    printf( "you selected the %s keyword\n",
            OPT_OPTN_NAME_VAL2STR(opt) );

   * Note: you may replace the `OPTN_NAME' enumeration prefix with
another prefix by specifying a `prefix-enum' attribute.

   Finally, users may specify the argument either by name or by number.
Since the numeric equivalents change by having new entries inserted
into the keyword list, this would not be a recommended practice.
However, either `-1' or `~0' will always be equivalent to specifying
the last keyword.


File: autogen.info,  Node: arg-type set membership,  Next: arg-type hierarchy,  Prev: arg-type keyword,  Up: Option Arguments

7.5.6.5 Arg Type Set Membership
...............................

`arg-type = set;'

   The argument must be a list of names each of which must match the
strings "`all'", "`none'" or one of the keywords (*note arg-keyword::)
specified for this option.  `all' will turn on all membership bits and
`none' will turn them all off.  Specifying one of the keywords will turn
on the corresponding set membership bit.  Literal numbers may also be
used and may, thereby, set or clear more than one bit.  Preceding a
keyword or literal number with a bang (`!'  - exclamation point) will
turn the bit(s) off.  The number of keywords allowed is constrained by
the number of bits in a pointer, as the bit set is kept in a `void*'.

   If, for example, you specified `first' in your list of keywords,
then you can use the following code to test to see if either `first' or
`all' was specified:

    uintptr_t opt = OPT_VALUE_OPTN_NAME;
    if (opt & OPTN_NAME_FIRST)
        /* OPTN_NAME_FIRST bit was set */ ;

   AutoOpts produces a special purpose procedure for this option.  To
set multiple bits as the default (initial) value, you must specify an
initial numeric value (which might become inaccurate over time), or
else specify `arg-default' multiple times.  Do not specify a series of
names conjoined with `+' symbols as the value for any of the
`arg-default' attributes.  That works for option parsing, but not for
the option code generation.


File: autogen.info,  Node: arg-type hierarchy,  Next: arg-type file name,  Prev: arg-type set membership,  Up: Option Arguments

7.5.6.6 Arg Type Hierarchical
.............................

`arg-type = hierarchy;'
`arg-type = nested;'

   This denotes an option with a structure-valued argument, a.k.a.
"subopts" in `getopts' terminology.  The argument is parsed and the
values made available to the program via the find and find next calls
(*Note libopts-optionFindValue::, *Note libopts-optionGetValue::, and
*note libopts-optionFindNextValue::).

    tOptionValue * val = optionGetValue(VALUE_OPT_OPTN_NAME, "name");
    while (val != NULL) {
      process(val);
      val = optionNextValue(VALUE_OPT_OPTN_NAME, val);
      if (wrong_name(val, "name"))
        break;
    }


File: autogen.info,  Node: arg-type file name,  Next: arg-type time-duration,  Prev: arg-type hierarchy,  Up: Option Arguments

7.5.6.7 Arg Type File Name
..........................

`arg-type = file;'

   This argument type will have some validations on the argument and,
optionally, actually open the file.  You must specify several additonal
attributes for the option:

`file-exists'
     If not specified or empty, then the directory portion of the name
     is checked.  The directory must exist or the argument is rejected
     and the usage procedure is invoked.

     Otherwise, both the directory as above and the full name is tested
     for existence.  If the value begins with the two letters "no",
     then the file must not pre-exist.  Otherwise, the file is expected
     to exist.

`open-file'
     If not specified or empty, the file is left alone.  If the value
     begins with the four letters "desc"[riptor], then `open(2)' is
     used and `optArg.argFd' is set.  Otherwise, the file is opened
     with `fopen' and `optArg.argFp' is set.

`file-mode'
     If "open-file" is set and not empty, then you must specify the
     open mode.  Set the value to the flag bits or mode string as
     appropriate for the open type.


File: autogen.info,  Node: arg-type time-duration,  Next: arg-type time-date,  Prev: arg-type file name,  Up: Option Arguments

7.5.6.8 Arg Type Time Duration
..............................

`arg-type = time-duration;'

   The argument will be converted into a number of seconds.  It may be
a multi-part number with different parts being multiplied into a seconds
value and added into the final result.  Valid forms are in the table
below.  Upper cased letters represent numbers that must be used in the
expressions.

`[[HH:]MM:]SS'
     `HH' is multiplied by `3600' and `MM' multiplied by `60' before
     they are added to `SS'.  This time specification may not be
     followed by any other time specs.  `HH' and `MM' are both optional,
     though `HH' cannot be specified without `MM'.

`DAYS d'
     `DAYS' is multiplied by the number of seconds in a day.  This
     value may be followed by (and added to) values specified by
     `HH:MM:SS' or the suffixed values below.  If present, it must
     always be first.

`HRS h'
     `HRS' is multiplied by the number of seconds in an hour.  This
     value may be followed by (and added to) values specified by
     `MM:SS' or the suffixed values below.

`MINS m'
     `MINS' is multiplied by the number of seconds in a minute.  This
     value may be followed by (and added to) a count of seconds.

`SECS s'
     This value can only be the last value in a time specification.
     The `s' suffix is optional.

       5 d 1:10:05    ==> 5 days + 1 hour 10 minutes and 5 seconds
       5 d 1 h 10 m 5 ==> yields: 436205 seconds
       5d1h10m5s      ==> same result -- spaces are optional.

   When saved into a config file, the value will be stored as a simple
count of seconds.  There are actually more (many) accepted time
duration strings.  The full documentation can be found with ISO-8601
documentation and the more extedded documentation when
"parse_duration()" becomes more widely available.


File: autogen.info,  Node: arg-type time-date,  Next: arg-keyword,  Prev: arg-type time-duration,  Up: Option Arguments

7.5.6.9 Arg Type Time and Date
..............................

`arg-type = time-date;'

   The argument will be converted into the number of seconds since the
epoch.  The conversion rules are very complicated, please see the
`getdate_r(3GNU)' man page.  There are some additional restrictions:

  1. Your project must be compiled with `PKGDATADIR' defined and naming
     a valid directory.

  2. The `DATEMSK' environment variable will be set to the `datemsk'
     file within that directory.

   If that file is not accessible for any reason, the string will be
parsed as a time duration (*note arg-type time-duration::) instead of a
specific date and time.


File: autogen.info,  Node: arg-keyword,  Next: arg-optional,  Prev: arg-type time-date,  Up: Option Arguments

7.5.6.10 Keyword list
.....................

If the `arg-type' is `keyword' (*note arg-type keyword::) or
`set-membership' (*note arg-type set membership::), then you must
specify the list of keywords by a series of `keyword' entries.  The
interface file will contain values for `<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').


File: autogen.info,  Node: arg-optional,  Next: arg-default,  Prev: arg-keyword,  Up: Option Arguments

7.5.6.11 Option Argument Optional
.................................

This attribute indicates that the user does not have to supply an
argument for the option.  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.

   This is overridden and the options are required if the libopts
library gets configured with `--disable-optional-args'.


File: autogen.info,  Node: arg-default,  Prev: arg-optional,  Up: Option Arguments

7.5.6.12 Default Option Argument Value
......................................

This specifies the default option argument value to be used when the
option is not specified or preset.  You may specify multiple
`arg-default' values if the argument type is `set membership'.


File: autogen.info,  Node: Option Argument Handling,  Next: Internationalizing Options,  Prev: Option Arguments,  Up: Option Definitions

7.5.7 Option Argument Handling
------------------------------

AutoOpts will either specify or automatically generate callback
procedures for options that take specialized arguments.  The only
option argument types that are not specialized are plain string
arguments and no argument at all.  For options that fall into one of
those two categories, you may specify your own callback function, as
specified below.  If you do this and if you specify that options are
resettable (*note automatic options::), then your option handling code
*must* look for the `OPTST_RESET' bit in the `fOptState' field of the
option descriptor.

   If the option takes a string argument, then you may specify that the
option is to be handled by the `libopts' library procedures
`stackOptArg()' or `unstackOptArg()' (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.


File: autogen.info,  Node: Internationalizing Options,  Next: documentation attributes,  Prev: Option Argument Handling,  Up: Option Definitions

7.5.8 Internationalizing Options
--------------------------------

Normally, AutoOpts produces usage text that is difficult to translate.
It is pieced together on the fly using words and phrases scattered
around here and there, piecing together toe document.  This does not
translate well.

   Incorporated into this package are some ways around the problem.
First, you should specify the `full-usage' and `short-usage' program
attributes (*note program attributes::).  This will enable your
translators to translate the usage text as a whole.

   Your translators will also be able to translate long option names.
The option name translations will then become the names searched for
both on the command line and in configuration files.  However, it will
not affect the names of environment variable names used to configure
your program.

   If it is considered desireable to keep configuration files in the "C"
locale, then several macros are available to suppress or delay the
translations of option names at run time.  These are all disabled if
`ENABLE_NLS' is not defined at compile time or if `no-xlate' has been
set to the value _anything_.  These macros *must* be invoked before the
first invocation of `optionProcess'.

`OPT_NO_XLAT_CFG_NAMES;'
`OPT_XLAT_CFG_NAMES;'
     Disable (or enable) the translations of option names for
     configuration files.  If you enable translation for config files,
     then they will be translated for command line options.

`OPT_NO_XLAT_OPT_NAMES;'
`OPT_XLAT_OPT_NAMES;'
     Disable (or enable) the translations of option names for command
     line processing.  If you disable the translation for command line
     processing, you will also disable it for configuration file
     processing.  Once translated, the option names will remain
     translated.


File: autogen.info,  Node: documentation attributes,  Next: automatic options,  Prev: Internationalizing Options,  Up: Option Definitions

7.5.9 Man and Info doc Attributes
---------------------------------

AutoOpts includes AutoGen templates for producing abbreviated man pages
and for producing the invoking section of an info document.  To take
advantage of these templates, you must add several attributes to your
option definitions.

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

`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-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 have been 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'.

    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.

     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_;
         };

`prog-man-descrip'
`prog-info-descrip'
     These attributes are now deprecated.  Please use a `doc-section'
     stanza with a `ds-type' attribute set to `DESCRIPTION' instead.

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


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

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

`reset-option -R'
     This option takes the name of an option for the current program
     and resets its state such that it is set back to its original,
     compile-time initialized value.  If the option state is
     subsequently stored (via `--save-opts'), the named option will not
     appear in that file.

     This option is activated by specifying the `resettable' attribute.

     *BEWARE*:  If the `resettable' attribute is specified, all option
     callbacks *must* look for the `OPTST_RESET' bit in the `fOptState'
     field of the option descriptor.  If set, the `optCookie' and
     `optArg' fields will be unchanged from their last setting.  When
     the callback returns, these fields will be set to their original
     values.  If you use this feature and you have allocated data
     hanging off of the cookie, you need to deallocate it.


File: autogen.info,  Node: standard options,  Prev: automatic options,  Up: Option Definitions

7.5.11 Library of Standard Options
----------------------------------

AutoOpts has developed a set of standardized options.  You may
incorporate these options in your program simply by _first_ adding a
`#define' for the options you want, and then the line,

    #include stdoptions.def

in your option definitions.  The supported options are specified thus:

    #define DEBUG
    #define DIRECTORY
    #define DRY_RUN
    #define INPUT
    #define INTERACTIVE
    #define OUTPUT
    #define WARN

    #define SILENT
    #define QUIET
    #define BRIEF
    #define VERBOSE

   By default, only the long form of the option will be available.  To
specify the short (flag) form, suffix these names with `_FLAG'.  e.g.,

    #define DEBUG_FLAG

   `--silent', `--quiet', `--brief' and `--verbose' are related in that
they all indicate some level of diagnostic output.  These options are
all designed to conflict with each other.  Instead of four different
options, however, several levels can be incorporated by `#define'-ing
`VERBOSE_ENUM'.  In conjunction with `VERBOSE', it incorporates the
notion of 5 levels in an enumeration: `silent', `quiet', `brief',
`informative' and `verbose'; with the default being `brief'.

   Here is an example program that uses the following set of
definitions:

    AutoGen Definitions options;

    prog-name  = default-test;
    prog-title = 'Default Option Example';
    homerc     = '$$/../share/default-test', '$HOME', '.';
    environrc;
    long-opts;
    gnu-usage;
    usage-opt;
    version    = '1.0';
    main = {
      main-type = shell-process;
    };
    #define DEBUG_FLAG
    #define WARN_FLAG
    #define WARN_LEVEL
    #define VERBOSE_FLAG
    #define VERBOSE_ENUM
    #define DRY_RUN_FLAG
    #define OUTPUT_FLAG
    #define INPUT_FLAG
    #define DIRECTORY_FLAG
    #define INTERACTIVE_FLAG
    #include stdoptions.def

Running a few simple commands on that definition file:

    autogen default-test.def
    copts="-DTEST_DEFAULT_TEST_OPTS `autoopts-config cflags`"
    lopts="`autoopts-config ldflags`"
    cc -o default-test ${copts} default-test.c ${lopts}

Yields a program which, when run with `--help', prints out:

    default-test - Default Option Example - Ver. 1.0
    USAGE:  default-test [ -<flag> [<val>] | --<name>[{=| }<val>] ]...


    The following options are commonly used and are provided and supported
    by AutoOpts:

       -D, --debug                run program with debugging info
       -V, --verbose=KWd          run program with progress info
       -w, --warn=num             specify a warning-level threshhold
                                    - disabled as --no-warn
       -R, --dry-run              program will make no changes
       -I, --interactive=str      prompt for confirmation
       -i, --input=str            redirect input from file
       -o, --output=str           redirect output to file
       -d, --directory=str        use specified dir for I/O

    version, usage and configuration options:

       -v, --version[=arg]        Output version information and exit
       -?, --help                 Display extended usage information and exit
       -!, --more-help            Extended usage information passed thru pager
       -u, --usage                Abbreviated usage to stdout
       ->, --save-opts[=arg]      Save the option state to a config file
       -<, --load-opts=str        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 $$/../share/default-test
     - reading file $HOME/.default_testrc
     - reading file ./.default_testrc
     - examining environment variables named DEFAULT_TEST_*

    The valid "verbose" option keywords are:
      silent quiet brief informative verbose
      or an integer from 0 through 4
    Packaged by Bruce (2012-08-11)
    Report default_test bugs to bkorb@gnu.org


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


File: autogen.info,  Node: Option Processing Data,  Next: CLEAR_OPT,  Up: AutoOpts API

7.6.1 Data for Option Processing
--------------------------------

This section describes the data that may be accessed from within the
option processing callback routines.  The following fields may be used
in the following ways and may be used for read only.  The first set is
addressed from the `tOptDesc*' pointer:

`optIndex'

`optValue'
     These may be used by option procedures to determine which option
     they are working on (in case they handle several options).

`optActualIndex'

`optActualValue'
     These may be used by option procedures to determine which option
     was used to set the current option.  This may be different from
     the above if the options are members of an equivalence class.

`optOccCt'
     If AutoOpts is processing command line arguments, then this value
     will contain the current occurrence count.  During the option
     preset phase (reading configuration files and examining
     environment variables), the value is zero.

`fOptState'
     The field may be tested for the following bit values (prefix each
     name with `OPTST_', e.g. `OPTST_INIT'):

    `INIT'
          Initial compiled value.  As a bit test, it will always yield
          FALSE.

    `SET'
          The option was set via the `SET_OPT()' macro.

    `PRESET'
          The option was set via a configuration file.

    `DEFINED'
          The option was set via a command line option.

    `SET_MASK'
          This is a mask of flags that show the set state, one of the
          above four values.

    `EQUIVALENCE'
          This bit is set when the option was selected by an
          equivalenced option.

    `DISABLED'
          This bit is set if the option is to be disabled.  (Meaning it
          was a long option prefixed by the disablement prefix, or the
          option has not been specified yet and initializes as
          `disabled'.)

     As an example of how this might be used, in AutoGen I want to allow
     template writers to specify that the template output can be left
     in a writable or read-only state.  To support this, there is a
     Guile function named `set-writable' (*note SCM set-writable::).
     Also, I provide for command options `--writable' and
     `--not-writable'.  I give precedence to command line and RC file
     options, thus:

         switch (STATE_OPT( WRITABLE )) {
         case OPTST_DEFINED:
         case OPTST_PRESET:
             fprintf(stderr, zOverrideWarn, pCurTemplate->pzFileName,
                     pCurMacro->lineNo);
             break;

         default:
             if (gh_boolean_p( set ) && (set == SCM_BOOL_F))
                 CLEAR_OPT( WRITABLE );
             else
                 SET_OPT_WRITABLE;
         }

`pzLastArg'
     Pointer to the latest argument string.  BEWARE If the argument type
     is numeric, an enumeration or a bit mask, then this will be the
     argument *value* and not a pointer to a string.

   The following two fields are addressed from the `tOptions*' pointer:

`pzProgName'
     Points to a NUL-terminated string containing the current program
     name, as retrieved from the argument vector.

`pzProgPath'
     Points to a NUL-terminated string containing the full path of the
     current program, as retrieved from the argument vector.  (If
     available on your system.)


   Note  these fields get filled in during the first call to
`optionProcess()'.  All other fields are private, for the exclusive use
of AutoOpts code and are subject to change.


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

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

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


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

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


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.


File: autogen.info,  Node: DISABLE_OPT_name,  Next: ENABLED_OPT,  Prev: DESC,  Up: AutoOpts API

7.6.5 DISABLE_OPT_name - Disable an option
------------------------------------------

This macro is emitted if it is both settable and it can be disabled.
If it cannot be disabled, it may always be CLEAR-ed (see above).

   The form of the macro will actually depend on whether the option is
equivalenced to another, and/or has an assigned handler procedure.
Unlike the `SET_OPT' macro, this macro does not allow an option
argument.

    DISABLE_OPT_NAME;


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

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


File: autogen.info,  Node: ERRSKIP_OPTERR,  Next: ERRSTOP_OPTERR,  Prev: ENABLED_OPT,  Up: AutoOpts API

7.6.7 ERRSKIP_OPTERR - Ignore Option Errors
-------------------------------------------

When it is necessary to continue (return to caller) on option errors,
invoke this option.  It is reversible.  *Note ERRSTOP_OPTERR::.


File: autogen.info,  Node: ERRSTOP_OPTERR,  Next: HAVE_OPT,  Prev: ERRSKIP_OPTERR,  Up: AutoOpts API

7.6.8 ERRSTOP_OPTERR - Stop on Errors
-------------------------------------

After invoking this macro, if `optionProcess()' encounters an error, it
will call `exit(1)' rather than return.  This is the default processing
mode.  It can be overridden by specifying `allow-errors' in the
definitions file, or invoking the macro *Note ERRSKIP_OPTERR::.


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

7.6.9 HAVE_OPT( <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>;
    }


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.


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.


File: autogen.info,  Node: OPTION_CT,  Next: OPT_ARG,  Prev: ISUNUSED_OPT,  Up: AutoOpts API

7.6.12 OPTION_CT - Full Count of Options
----------------------------------------

The full count of all options, both those defined and those generated
automatically by AutoOpts.  This is primarily used to initialize the
program option descriptor structure.


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

7.6.13 OPT_ARG( <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>;
    }


File: autogen.info,  Node: OPT_NO_XLAT_CFG_NAMES,  Next: OPT_NO_XLAT_OPT_NAMES,  Prev: OPT_ARG,  Up: AutoOpts API

7.6.14 OPT_NO_XLAT_CFG_NAMES - option name xlation
--------------------------------------------------

Invoking this macro will disable the translation of option names only
while processing configuration files and environment variables.  This
must be invoked before the first call to `optionProcess'..  You need
not invoke this if your option definition file contains the attribute
assignment, "`no-xlate = opt-cfg;'".


File: autogen.info,  Node: OPT_NO_XLAT_OPT_NAMES,  Next: OPT_VALUE_name,  Prev: OPT_NO_XLAT_CFG_NAMES,  Up: AutoOpts API

7.6.15 OPT_NO_XLAT_OPT_NAMES - option name xlation
--------------------------------------------------

Invoking this macro will completely disable the translation of option
names.  This must be invoked before the first call to `optionProcess'.
You need not invoke this if your option definition file contains the
attribute assignment, "`no-xlate = opt;'".


File: autogen.info,  Node: OPT_VALUE_name,  Next: OPT_XLAT_CFG_NAMES,  Prev: OPT_NO_XLAT_OPT_NAMES,  Up: AutoOpts API

7.6.16 OPT_VALUE_name - Option Argument Value
---------------------------------------------

This macro gets emitted only for options that take numeric, keyword or
set membership arguments.  The macro yields a word-sized integer
containing the enumeration, bit set or numeric value for the option
argument.

    int opt_val = OPT_VALUE_name;


File: autogen.info,  Node: OPT_XLAT_CFG_NAMES,  Next: OPT_XLAT_OPT_NAMES,  Prev: OPT_VALUE_name,  Up: AutoOpts API

7.6.17 OPT_XLAT_CFG_NAMES - option name xlation
-----------------------------------------------

If `ENABLE_NLS' is defined and `no-xlate' has been not set to the value
_anything_, this macro will cause the translation of option names to
happen before starting the processing of configuration files and
environment variables.  This will change the recognition of options
within the `$PROGRAMNAME' environment variable, but will not alter the
names used for setting options via `$PROGRAMNAME_name' environment
variables.

   This must be invoked before the first call to `optionProcess'.  You
might need to use this macro if your option definition file contains
the attribute assignment, "`no-xlate = opt;'" or "`no-xlate =
opt-cfg;'", and you have determined in some way that you wish to
override that.


File: autogen.info,  Node: OPT_XLAT_OPT_NAMES,  Next: RESTART_OPT,  Prev: OPT_XLAT_CFG_NAMES,  Up: AutoOpts API

7.6.18 OPT_XLAT_OPT_NAMES - option name xlation
-----------------------------------------------

If `ENABLE_NLS' is defined and `no-xlate' has been not set to the value
_anything_, translate the option names before processing the command
line options.  Long option names may thus be localized.  (If the names
were translated before configuration processing, they will not be
re-translated.)

   This must be invoked before the first call to `optionProcess'.  You
might need to use this macro if your option definition file contains
the attribute assignment, "`no-xlate = opt;'" and you have determined
in some way that you wish to override that.


File: autogen.info,  Node: RESTART_OPT,  Next: SET_OPT_name,  Prev: OPT_XLAT_OPT_NAMES,  Up: AutoOpts API

7.6.19 RESTART_OPT( n ) - Resume Option Processing
--------------------------------------------------

If option processing has stopped (either because of an error or
something was encountered that looked like a program argument), it can
be resumed by providing this macro with the index `n' of the next
option to process and calling `optionProcess()' again.


File: autogen.info,  Node: SET_OPT_name,  Next: STACKCT_OPT,  Prev: RESTART_OPT,  Up: AutoOpts API

7.6.20 SET_OPT_name - Force an option to be set
-----------------------------------------------

This macro gets emitted only when the given option has the `settable'
attribute specified.

   The form of the macro will actually depend on whether the option is
equivalenced to another, has an option argument and/or has an assigned
handler procedure.  If the option has an argument, then this macro will
too.  Beware that the argument is not reallocated, so the value must not
be on the stack or deallocated in any other way for as long as the value
might get referenced.

   If you have supplied at least one `homerc' file (*note program
attributes::), this macro will be emitted for the `--save-opts' option.

    SET_OPT_SAVE_OPTS( "filename" );

*Note automatic options::, for a discussion of the implications of using
this particular example.


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

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


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);
    }


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::.)


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 :)
    }


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.


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;
    }


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


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;
    }


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;
    }


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;
    }


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.


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-optionNextValue::   optionNextValue
* libopts-optionOnlyUsage::   optionOnlyUsage
* libopts-optionProcess::     optionProcess
* libopts-optionRestore::     optionRestore
* libopts-optionSaveFile::    optionSaveFile
* libopts-optionSaveState::   optionSaveState
* libopts-optionUnloadNested:: optionUnloadNested
* libopts-optionVersion::     optionVersion
* libopts-pathfind::          pathfind
* 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.


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.


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( pzFile );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pzFile      `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.


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( pOpts, pzProg );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOpts       `tOptions*'    program options descriptor
     pzProg      `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.


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( pOptDesc, pPrevVal, name, value );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOptDesc    `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.


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( pOptDesc, name, value );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOptDesc    `const         an option with a nested arg type
                 tOptDesc*'     
     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 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.


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.


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.


File: autogen.info,  Node: libopts-optionLoadLine,  Next: libopts-optionNextValue,  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.


File: autogen.info,  Node: libopts-optionNextValue,  Next: libopts-optionOnlyUsage,  Prev: libopts-optionLoadLine,  Up: libopts procedures

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


File: autogen.info,  Node: libopts-optionOnlyUsage,  Next: libopts-optionProcess,  Prev: libopts-optionNextValue,  Up: libopts procedures

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


File: autogen.info,  Node: libopts-optionProcess,  Next: libopts-optionRestore,  Prev: libopts-optionOnlyUsage,  Up: libopts procedures

7.6.32.11 optionProcess
.......................

this is the main option processing routine

Usage:
    int res = optionProcess( pOpts, argc, argv );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOpts       `tOptions*'    program options descriptor
     argc        `int'          program arg count
     argv        `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.


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

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


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

7.6.32.13 optionSaveFile
........................

saves the option state to a file

Usage:
    optionSaveFile( pOpts );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     pOpts       `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.


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

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


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

7.6.32.15 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::).


File: autogen.info,  Node: libopts-optionVersion,  Next: libopts-pathfind,  Prev: libopts-optionUnloadNested,  Up: libopts procedures

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


File: autogen.info,  Node: libopts-pathfind,  Next: libopts-strequate,  Prev: libopts-optionVersion,  Up: libopts procedures

7.6.32.17 pathfind
..................

fild a file in a list of directories

Usage:
    char* res = pathfind( path, file, mode );
   Where the arguments are:
     Name        Type           Description
     ----        ----           ------------
     path        `char const*'  colon separated list of search
                                directories
     file        `char const*'  the name of the file to look for
     mode        `char const*'  the mode bits that must be set to match
     returns     char*          the path to the located file

   pathfind looks for a a file with name "FILE" and "MODE" access along
colon delimited "PATH", and returns the full pathname as a string, or
NULL if not found.  If "FILE" contains a slash, then it is treated as a
relative or absolute path and "PATH" is ignored.

   *NOTE*: this function is compiled into `libopts' only if it is not
natively supplied.

   The "MODE" argument is a string of option letters chosen from the
list below:
    Letter    Meaning
    r         readable
    w         writable
    x         executable
    f         normal file       (NOT IMPLEMENTED)
    b         block special     (NOT IMPLEMENTED)
    c         character special (NOT IMPLEMENTED)
    d         directory         (NOT IMPLEMENTED)
    p         FIFO (pipe)       (NOT IMPLEMENTED)
    u         set user ID bit   (NOT IMPLEMENTED)
    g         set group ID bit  (NOT IMPLEMENTED)
    k         sticky bit        (NOT IMPLEMENTED)
    s         size nonzero      (NOT IMPLEMENTED)

   returns NULL if the file is not found.


File: autogen.info,  Node: libopts-strequate,  Next: libopts-streqvcmp,  Prev: libopts-pathfind,  Up: libopts procedures

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


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

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


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

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


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

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


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

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


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.


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.


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


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


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`


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


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


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.


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


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.


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.


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-2012 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


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.


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!


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


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


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.


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.


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.

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


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 ;->


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


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
    Packaged by Bruce (2012-08-11)
    Report test_errors bugs to bkorb@gnu.org

   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


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.
    Packaged by Bruce (2012-08-11)
    Report genshellopt bugs to bkorb@gnu.org

    = = = = = = = =

    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)
       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

    All arguments are named options.

    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''.
    Packaged by Bruce (2012-08-11)
    Report getdefs bugs to bkorb@gnu.org

Resulting in the following script:
    #! /bin/sh
    # # # # # # # # # # -- do not modify this marker --
    #
    #  DO NOT EDIT THIS SECTION OF /old-home/bkorb/ag/ag/doc/ag-texi-30133.d/.ag-eFukQW/genshellopt.sh
    #
    #  From here to the next `-- do not modify this marker --',
    #  the text has been generated Saturday August 11, 2012 at 09:42:46 AM PDT
    #  From the GETDEFS option definitions
    #
    GETDEFS_LONGUSAGE_TEXT='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 these options:
                                    output
                                    - may appear multiple times
       Str base-name      Base name for output file(s)
                                    - prohibits these options:
                                    output

    version, usage and configuration options:

       Arg Option-Name    Description
       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

    All arguments are named options.

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

    The following option preset mechanisms are supported:
     - reading file /dev/null

    This program extracts AutoGen definitions from a list of source files.
    Definitions are delimited by ``/*=<entry-type> <entry-name>\n'\'''\'' and
    ``=*/\n'\'''\''.
    Packaged by Bruce (2012-08-11)
    Report getdefs bugs to bkorb@gnu.org'

    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)
       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

    All arguments are named options.

    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'\'''\''.
    Packaged by Bruce (2012-08-11)
    Report getdefs bugs to bkorb@gnu.org'


    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
    else
      GETDEFS_SUBBLOCK_CT=1
      GETDEFS_SUBBLOCK_1=${GETDEFS_SUBBLOCK}
    fi
    export GETDEFS_SUBBLOCK_CT
    if test -z "${GETDEFS_LISTATTR}"
    then
      GETDEFS_LISTATTR_CT=0
    else
      GETDEFS_LISTATTR_CT=1
      GETDEFS_LISTATTR_1=${GETDEFS_LISTATTR}
    fi
    export GETDEFS_LISTATTR_CT
    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
    else
      GETDEFS_ASSIGN_CT=1
      GETDEFS_ASSIGN_1=${GETDEFS_ASSIGN}
    fi
    export GETDEFS_ASSIGN_CT
    if test -z "${GETDEFS_COMMON_ASSIGN}"
    then
      GETDEFS_COMMON_ASSIGN_CT=0
    else
      GETDEFS_COMMON_ASSIGN_CT=1
      GETDEFS_COMMON_ASSIGN_1=${GETDEFS_COMMON_ASSIGN}
    fi
    export GETDEFS_COMMON_ASSIGN_CT
    if test -z "${GETDEFS_COPY}"
    then
      GETDEFS_COPY_CT=0
    else
      GETDEFS_COPY_CT=1
      GETDEFS_COPY_1=${GETDEFS_COPY}
    fi
    export GETDEFS_COPY_CT
    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
    else
      GETDEFS_INPUT_CT=1
      GETDEFS_INPUT_1=${GETDEFS_INPUT}
    fi
    export GETDEFS_INPUT_CT
    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
    else
      GETDEFS_AGARG_CT=1
      GETDEFS_AGARG_1=${GETDEFS_AGARG}
    fi
    export GETDEFS_AGARG_CT
    GETDEFS_BASE_NAME=${GETDEFS_BASE_NAME}
    GETDEFS_BASE_NAME_set=false
    export GETDEFS_BASE_NAME

    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 >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                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
                ;;

            '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 >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_ORDERING_set=true
                OPT_NAME='ORDERING'
                eval GETDEFS_ORDERING${OPT_ELEMENT}=true
                export GETDEFS_ORDERING${OPT_ELEMENT}
                OPT_ARG_NEEDED=OK
                ;;

            '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' >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_ORDERING_set=true
                GETDEFS_ORDERING='no'
                export GETDEFS_ORDERING
                OPT_NAME='ORDERING'
                OPT_ARG_NEEDED=NO
                ;;

            '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 >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_FIRST_INDEX_set=true
                OPT_NAME='FIRST_INDEX'
                OPT_ARG_NEEDED=YES
                ;;

            'fil' | \
            'file' | \
            'filel' | \
            'fileli' | \
            'filelis' | \
            'filelist' )
                if [ -n "${GETDEFS_FILELIST}" ] && ${GETDEFS_FILELIST_set} ; then
                    echo Error:  duplicate FILELIST option >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                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
                ;;

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

            '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 >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                GETDEFS_SRCFILE_set=true
                OPT_NAME='SRCFILE'
                eval GETDEFS_SRCFILE${OPT_ELEMENT}=true
                export GETDEFS_SRCFILE${OPT_ELEMENT}
                OPT_ARG_NEEDED=OK
                ;;

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

            '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' >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                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 >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                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 >&2
                    echo "$GETDEFS_USAGE_TEXT"
                    exit 1 ; fi
                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-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"
                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 >&2
                        echo "$GETDEFS_USAGE_TEXT"
                        exit 1
                    fi
                    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
    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_'


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


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.


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


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::).

* Menu:

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


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

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

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.


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

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

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.


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.

* Menu:

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


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. Generated `main()' procedures will not work.

  5. Option coordination with external libraries will not work.

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

  7. You must specify a main procedure of type "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.

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

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


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


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.

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


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.


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.

    aliases          allow-errors  arg-default
    arg-optional     arg-range     arg-type
    argument         call-proc     code
    config-header    copyright     default
    deprecated       descrip       detail
    disable          documentation eaddr
    enable           enabled       environrc
    equivalence      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
    help-value       homerc        ifdef
    ifndef           immed-disable immediate
    include          lib-name      library
    long-opts        main          main-text
    main-type        max           min
    more-help-value  must-set      name
    no-command       no-libopts    no-misuse-usage
    no-preset        no-xlate      nomem-fail-code
    omitted-usage    package       prefix
    prefix-enum      preserve-case prog-name
    prog-title       reorder-args  resettable
    scaled           settable      short-usage
    stack-arg        std-value     test-main
    translators      unstack-arg   usage
    usage-message    usage-opt     usage-type
    val-name         val-upname    value
    version


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

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