diff options
Diffstat (limited to 'doc/autogen.info-2')
| -rw-r--r-- | doc/autogen.info-2 | 7195 |
1 files changed, 7195 insertions, 0 deletions
diff --git a/doc/autogen.info-2 b/doc/autogen.info-2 new file mode 100644 index 0000000..ae59b42 --- /dev/null +++ b/doc/autogen.info-2 @@ -0,0 +1,7195 @@ +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 +================================= + + +* Menu: + +* allow-errors: presentation attributes. + (line 9) +* arg-default: arg-default. (line 6) +* arg-name: documentation attributes. + (line 12) +* arg-optional: arg-optional. (line 6) +* arg-range: arg-type number. (line 21) +* arg-type: Option Arguments. (line 23) +* argument: program attributes. (line 22) +* author: information attributes. + (line 29) +* before-guile-boot: main guile. (line 9) +* call-proc: Option Argument Handling. + (line 63) +* comment-char: main for-each. (line 127) +* config-header <1>: programming attributes. + (line 10) +* config-header: program attributes. (line 33) +* copyright: information attributes. + (line 10) +* date: information attributes. + (line 13) +* default: opt-attr default option. + (line 6) +* deprecated: Common Attributes. (line 29) +* descrip: Required Attributes. (line 36) +* detail <1>: documentation attributes. + (line 164) +* detail: information attributes. + (line 44) +* die-code: programming attributes. + (line 43) +* disable: Common Attributes. (line 34) +* disable-load: config attributes. (line 13) +* disable-save: config attributes. (line 13) +* doc: documentation attributes. + (line 18) +* doc-section: documentation attributes. + (line 37) +* documentation <1>: opt-attr documentation. + (line 17) +* documentation: lib and program. (line 17) +* eaddr: information attributes. + (line 32) +* enable: Common Attributes. (line 47) +* enabled: Common Attributes. (line 51) +* environrc: config attributes. (line 17) +* equivalence: opt-attr equivalence. + (line 6) +* exit-desc: programming attributes. + (line 16) +* exit-name: programming attributes. + (line 16) +* explain: information attributes. + (line 48) +* export: programming attributes. + (line 54) +* extra-code: arg-keyword. (line 15) +* extract-code: Option Argument Handling. + (line 52) +* file-exists: arg-type file name. (line 13) +* file-mode: arg-type file name. (line 29) +* flag-code: Option Argument Handling. + (line 27) +* flag-proc: Option Argument Handling. + (line 70) +* full-usage: usage attributes. (line 10) +* gnu-usage <1>: information attributes. + (line 87) +* gnu-usage: usage attributes. (line 39) +* guard-option-names: programming attributes. + (line 62) +* guile-main: main guile. (line 15) +* handler-proc: main for-each. (line 20) +* handler-type: main for-each. (line 45) +* help-value: automatic options. (line 18) +* homerc: config attributes. (line 26) +* ifdef: Common Attributes. (line 58) +* ifndef: Common Attributes. (line 58) +* immed-disable: Immediate Action. (line 31) +* immediate: Immediate Action. (line 24) +* include: programming attributes. + (line 93) +* keyword: arg-keyword. (line 6) +* lib-name: lib and program. (line 27) +* library: lib and program. (line 7) +* load-opts-value: automatic options. (line 15) +* long-opts: presentation attributes. + (line 15) +* main: Generated main. (line 8) +* main-fini: main for-each. (line 123) +* main-init: main for-each. (line 119) +* main-type: Generated main. (line 12) +* max: Common Attributes. (line 14) +* min: Common Attributes. (line 20) +* more-help-value: automatic options. (line 15) +* must-set: Common Attributes. (line 25) +* MYHANDLER-code: main for-each. (line 95) +* name: Required Attributes. (line 9) +* no-command: Common Attributes. (line 94) +* no-libopts: programming attributes. + (line 97) +* no-misuse-usage: usage attributes. (line 53) +* no-preset: opt-attr no-preset. (line 6) +* no-xlate: presentation attributes. + (line 38) +* omitted-usage: Common Attributes. (line 58) +* open-file: arg-type file name. (line 23) +* option-code: main main. (line 7) +* option-info: documentation attributes. + (line 33) +* opts-ptr: information attributes. + (line 66) +* owner: information attributes. + (line 15) +* package: information attributes. + (line 51) +* prefix: programming attributes. + (line 104) +* prefix-enum: arg-type keyword. (line 38) +* preserve-case: information attributes. + (line 57) +* prog-desc: information attributes. + (line 66) +* prog-group: usage attributes. (line 61) +* prog-info-descrip: documentation attributes. + (line 160) +* prog-man-descrip: documentation attributes. + (line 160) +* prog-name: program attributes. (line 15) +* prog-title: program attributes. (line 19) +* rcfile: config attributes. (line 58) +* reorder-args <1>: information attributes. + (line 96) +* reorder-args: presentation attributes. + (line 56) +* reset-value: automatic options. (line 15) +* resettable: presentation attributes. + (line 73) +* save-opts-value: automatic options. (line 19) +* scaled: arg-type number. (line 15) +* settable: opt-attr settable. (line 6) +* short-usage: usage attributes. (line 34) +* stack-arg: Option Argument Handling. + (line 74) +* text: information attributes. + (line 26) +* translators: opt-attr translators. + (line 6) +* type: information attributes. + (line 17) +* unstack-arg: Option Argument Handling. + (line 87) +* usage <1>: information attributes. + (line 79) +* usage: usage attributes. (line 69) +* usage-message: programming attributes. + (line 33) +* usage-opt <1>: usage attributes. (line 47) +* usage-opt: Features. (line 57) +* usage-value: automatic options. (line 15) +* value: Common Attributes. (line 10) +* vendor-opt: config attributes. (line 63) +* version: usage attributes. (line 86) +* version-proc: automatic options. (line 23) +* version-value: automatic options. (line 15) + + +File: autogen.info, Node: Add-Ons, Next: Future, Prev: AutoOpts, Up: Top + +8 Add-on packages for AutoGen +***************************** + +This chapter includes several programs that either work closely with +AutoGen (extracting definitions or providing special formatting +functions), or leverage off of AutoGen technology. There is also a +formatting library that helps make AutoGen possible. + + AutoOpts ought to appear in this list as well, but since it is the +primary reason why many people would even look into AutoGen at all, I +decided to leave it in the list of chapters. + +* Menu: + +* AutoFSM:: Automated Finite State Machine. +* AutoXDR:: Combined RPC Marshalling. +* AutoEvents:: Automated Event Management. +* columns Invocation:: Invoking columns. +* getdefs Invocation:: Invoking getdefs. +* xml2ag Invocation:: Invoking xml2ag. +* snprintfv:: The extensible format printing library. + + +File: autogen.info, Node: AutoFSM, Next: AutoXDR, Up: Add-Ons + +8.1 Automated Finite State Machine +================================== + +The templates to generate a finite state machine in C or C++ is included +with AutoGen. The documentation is not. The documentation is in HTML +format for viewing (http://www.gnu.org/software/autogen/autofsm.html), +or you can download FSM (http://download.sourceforge.net/autogen/). + + +File: autogen.info, Node: AutoXDR, Next: AutoEvents, Prev: AutoFSM, Up: Add-Ons + +8.2 Combined RPC Marshalling +============================ + +The templates and NFSv4 definitions are not included with AutoGen in +any way. The folks that designed NFSv4 noticed that much time and +bandwidth was wasted sending queries and responses when many of them +could be bundled. The protocol bundles the data, but there is no +support for it in rpcgen. That means you have to write your own code +to do that. Until now. Download this and you will have a large, +complex example of how to use `AutoXDR' for generating the marshaling +and unmarshaling of combined RPC calls. There is a brief example on +the web (http://www.gnu.org/software/autogen/xdr/index.html), but you +should download AutoXDR (http://download.sourceforge.net/autogen/). + + +File: autogen.info, Node: AutoEvents, Next: columns Invocation, Prev: AutoXDR, Up: Add-Ons + +8.3 Automated Event Management +============================== + +Large software development projects invariably have a need to manage +the distribution and display of state information and state changes. +In other words, they need to manage their software events. Generally, +each such project invents its own way of accomplishing this and then +struggles to get all of its components to play the same way. It is a +difficult process and not always completely successful. This project +helps with that. + + AutoEvents completely separates the tasks of supplying the data +needed for a particular event from the methods used to manage the +distribution and display of that event. Consequently, the programmer +writing the code no longer has to worry about that part of the problem. +Likewise the persons responsible for designing the event management and +distribution no longer have to worry about getting programmers to write +conforming code. + + This is a work in progress. See my web page +(http://www.gnu.org/software/autogen/autoevents.html) on the subject, +if you are interested. I have some useful things put together, but it +is not ready to call a product. + + +File: autogen.info, Node: columns Invocation, Next: getdefs Invocation, Prev: AutoEvents, Up: Add-Ons + +8.4 Invoking columns +==================== + +This program was designed for the purpose of generating compact, +columnized tables. It will read a list of text items from standard in +or a specified input file and produce a columnized listing of all the +non-blank lines. Leading white space on each line is preserved, but +trailing white space is stripped. Methods of applying per-entry and +per-line embellishments are provided. See the formatting and +separation arguments below. + + This program is used by AutoGen to help clean up and organize its +output. + + See `autogen/agen5/fsm.tpl' and the generated output `pseudo-fsm.h'. + + This function was not implemented as an expression function because +either it would have to be many expression functions, or a provision +would have to be added to provide options to expression functions. +Maybe not a bad idea, but it is not being implemented at the moment. + + A side benefit is that you can use it outside of `autogen' to +columnize input, a la the `ls' command. + + This section was generated by *AutoGen*, using the `agtexi-cmd' +template and the option descriptions for the `columns' program. This +software is released under the GNU General Public License, version 3 or +later. + +* Menu: + +* columns usage:: columns help/usage (`--help') +* columns dimensions:: dimensions options +* columns treatment:: treatment options +* columns ordering:: ordering options +* columns input-text:: input-text options +* columns config:: presetting/configuring columns +* columns exit status:: exit status +* columns See Also:: See Also + + +File: autogen.info, Node: columns usage, Next: columns dimensions, Up: columns Invocation + +8.4.1 columns help/usage (`--help') +----------------------------------- + +This is the automatically generated usage text for columns. + + The text printed is the same whether selected with the `help' option +(`--help') or the `more-help' option (`--more-help'). `more-help' will +print the usage text by passing it through a pager program. +`more-help' is disabled on platforms without a working `fork(2)' +function. The `PAGER' environment variable is used to select the +program, defaulting to `more'. Both will exit with a status code of 0. + +columns (GNU AutoGen) - Columnize Input Text - Ver. 1.2 +USAGE: columns [ -<flag> [<val>] | --<name>[{=| }<val>] ]... + +Specify the output dimensions: + + Flg Arg Option-Name Description + -W Num width Maximum Line Width + - It must be in the range: + 16 to 4095 + -c Num columns Desired number of columns + - It must be in the range: + 1 to 2048 + -w Num col-width Set width of each column + - It must be in the range: + 1 to 2048 + Num tab-width tab width + +Specify how to lay out the text: + + Flg Arg Option-Name Description + Num spread maximum spread added to column width + - It must be in the range: + 1 to 1024 + no fill Fill lines with input + - prohibits these options: + spread + col-width + by-columns + -I Str indent Line prefix or indentation + Str first-indent First line prefix + - requires these options: + indent + -f Str format Formatting string for each input + -S Str separation Separation string - follows all but last + Str line-separation string at end of all lines but last + Str ending string at end of last line + +Specify the ordering of the entries: + + Flg Arg Option-Name Description + no by-columns Print entries in column order + -s opt sort Sort input text + +Redirecting stdin to an alternate file: + + Flg Arg Option-Name Description + -i Str input Input file (if not stdin) + +version, usage and configuration options: + + Flg Arg Option-Name Description + -v opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + -> opt save-opts Save the option state to a config file + -< Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +The following option preset mechanisms are supported: + - reading file ./.columnsrc + - reading file $HOME/.columnsrc + - examining environment variables named COLUMNS_* +Packaged by Bruce (2012-08-11) +Report columns bugs to bkorb@gnu.org + + +File: autogen.info, Node: columns dimensions, Next: columns treatment, Prev: columns usage, Up: columns Invocation + +8.4.2 dimensions options +------------------------ + +Specify the output dimensions. + +width option (-W). +.................. + +This is the "maximum line width" option. This option takes an argument +number `num'. This option specifies the full width of the output line, +including any start-of-line indentation. The output will fill each +line as completely as possible, unless the column width has been +explicitly specified. If the maximum width is less than the length of +the widest input, you will get a single column of output. + +columns option (-c). +.................... + +This is the "desired number of columns" option. This option takes an +argument number `count'. Use this option to specify exactly how many +columns to produce. If that many columns will not fit within +LINE_WIDTH, then the count will be reduced to the number that fit. + +col-width option (-w). +...................... + +This is the "set width of each column" option. This option takes an +argument number `num'. Use this option to specify exactly how many +characters are to be allocated for each column. If it is narrower than +the widest entry, it will be over-ridden with the required width. + +tab-width option. +................. + +This is the "tab width" option. This option takes an argument number +`num'. If an indentation string contains tabs, then this value is used +to compute the ending column of the prefix string. + + +File: autogen.info, Node: columns treatment, Next: columns ordering, Prev: columns dimensions, Up: columns Invocation + +8.4.3 treatment options +----------------------- + +Specify how to lay out the text. + +spread option. +.............. + +This is the "maximum spread added to column width" option. This option +takes an argument number `num'. Use this option to specify exactly how +many characters may be added to each column. It allows you to prevent +columns from becoming too far apart. Without this option, `columns' +will attempt to widen columns to fill the full width. + +fill option. +............ + +This is the "fill lines with input" option. + +This option has some usage constraints. It: + * must not appear in combination with any of the following options: + spread, col_width, by_columns. + + Instead of columnizing the input text, fill the output lines with +the input lines. Blank lines on input will cause a blank line in the +output, unless the output is sorted. With sorted output, blank lines +are ignored. + +indent option (-I). +................... + +This is the "line prefix or indentation" option. This option takes an +argument string `l-pfx'. If a number, then this many spaces will be +inserted at the start of every line. Otherwise, it is a line prefix +that will be inserted at the start of every line. + +first-indent option. +.................... + +This is the "first line prefix" option. This option takes an argument +string `l-pfx'. + +This option has some usage constraints. It: + * must appear in combination with the following options: indent. + + If a number, then this many spaces will be inserted at the start of +the first line. Otherwise, it is a line prefix that will be inserted +at the start of that line. If its length exceeds "indent", then it +will be emitted on a line by itself, suffixed by any line separation +string. For example: + + $ columns --first='#define TABLE' -c 2 -I4 --line=' \' <<_EOF_ + one + two + three + four + _EOF_ + #define TABLE \ + one two \ + three four + +format option (-f). +................... + +This is the "formatting string for each input" option. This option +takes an argument string `fmt-str'. If you need to reformat each input +text, the argument to this option is interpreted as an `sprintf(3)' +format that is used to produce each output entry. + +separation option (-S). +....................... + +This is the "separation string - follows all but last" option. This +option takes an argument string `sep-str'. Use this option if, for +example, you wish a comma to appear after each entry except the last. + +line-separation option. +....................... + +This is the "string at end of all lines but last" option. This option +takes an argument string `sep-str'. Use this option if, for example, +you wish a backslash to appear at the end of every line, except the +last. + +ending option. +.............. + +This is the "string at end of last line" option. This option takes an +argument string `end-str'. This option puts the specified string at +the end of the output. + + +File: autogen.info, Node: columns ordering, Next: columns input-text, Prev: columns treatment, Up: columns Invocation + +8.4.4 ordering options +---------------------- + +Specify the ordering of the entries. + +by-columns option. +.................. + +This is the "print entries in column order" option. Normally, the +entries are printed out in order by rows and then columns. This option +will cause the entries to be ordered within columns. The final column, +instead of the final row, may be shorter than the others. + +sort option (-s). +................. + +This is the "sort input text" option. This option takes an optional +argument string `key-pat'. Causes the input text to be sorted. If an +argument is supplied, it is presumed to be a pattern and the sort is +based upon the matched text. If the pattern starts with or consists of +an asterisk (`*'), then the sort is case insensitive. + + +File: autogen.info, Node: columns input-text, Next: columns config, Prev: columns ordering, Up: columns Invocation + +8.4.5 input-text options +------------------------ + +Redirecting stdin to an alternate file. + +input option (-i). +.................. + +This is the "input file (if not stdin)" option. This option takes an +argument string `file'. This program normally runs as a `filter', +reading from standard input, columnizing and writing to standard out. +This option redirects input to a file. + + +File: autogen.info, Node: columns config, Next: columns exit status, Prev: columns input-text, Up: columns Invocation + +8.4.6 presetting/configuring columns +------------------------------------ + +Any option that is not marked as not presettable may be preset by +loading values from configuration ("rc" or "ini") files, and values +from environment variables named `COLUMNS' and `COLUMNS_<OPTION_NAME>'. +`<OPTION_NAME>' must be one of the options listed above in upper case +and segmented with underscores. The `COLUMNS' variable will be +tokenized and parsed like the command line. The remaining variables +are tested for existence and their values are treated like option +arguments. + +`libopts' will search in 2 places for configuration files: + * $PWD + + * $HOME + The environment variables `PWD', and `HOME' are expanded and +replaced when `columns' runs. For any of these that are plain files, +they are simply processed. For any that are directories, then a file +named `.columnsrc' is searched for within that directory and processed. + + Configuration files may be in a wide variety of formats. The basic +format is an option name followed by a value (argument) on the same +line. Values may be separated from the option name with a colon, equal +sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + + Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: + [COLUMNS] + or by + <?program columns> + Do not mix these styles within one configuration file. + + Compound values and carefully constructed string values may also be +specified using XML syntax: + <option-name> + <sub-opt>...<...>...</sub-opt> + </option-name> + yielding an `option-name.sub-opt' string value of + "...<...>..." + `AutoOpts' does not track suboptions. You simply note that it is a +hierarchicly valued option. `AutoOpts' does provide a means for +searching the associated name/value pair list (see: optionFindValue). + + The command line options relating to configuration and/or usage help +are: + +version (-v) +............ + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much +licensing detail to provide. The default is to print just the version. +The licensing infomation may be selected with an option argument. Only +the first letter of the argument is examined: + +`version' + Only print the version. This is the default. + +`copyright' + Name the copyright usage licensing terms. + +`verbose' + Print the full copyright usage licensing terms. + + +File: autogen.info, Node: columns exit status, Next: columns See Also, Prev: columns config, Up: columns Invocation + +8.4.7 columns exit status +------------------------- + +One of the following exit values will be returned: +`0 (EXIT_SUCCESS)' + Successful program execution. + +`1 (EXIT_FAILURE)' + The operation failed or the command syntax was not valid. + +`66 (EX_NOINPUT)' + A specified configuration file could not be loaded. + +`70 (EX_SOFTWARE)' + libopts had an internal operational error. Please report it to + autogen-users@lists.sourceforge.net. Thank you. + + +File: autogen.info, Node: columns See Also, Prev: columns exit status, Up: columns Invocation + +8.4.8 columns See Also +---------------------- + +This program is documented more fully in the Columns section of the +Add-On chapter in the `AutoGen' Info system documentation. + + +File: autogen.info, Node: getdefs Invocation, Next: xml2ag Invocation, Prev: columns Invocation, Up: Add-Ons + +8.5 Invoking getdefs +==================== + +If no `input' argument is provided or is set to simply "-", and if +`stdin' is not a `tty', then the list of input files will be read from +`stdin'. This program extracts AutoGen definitions from a list of +source files. Definitions are delimited by `/*=<entry-type> +<entry-name>\n' and `=*/\n'. From that, this program creates a +definition of the following form: + + #line nnn "source-file-name" + entry_type = { + name = entry_name; + ... + }; + + 1. The ellipsis `...' is filled in by text found between the two + delimiters. Each line of text is stripped of anything before the + first asterisk, then leading asterisks, then any leading or + trailing white space. + + 2. If what is left starts with what looks like a name followed by a + colon, then it is interpreted as a name followed by a value. + + 3. If the first character of the value is either a single or double + quote, then you are responsible for quoting the text as it gets + inserted into the output definitions. So, if you want whitespace + at the beginnings of the lines of text, you must do something like + this: + + * mumble: + * " this is some\n" + * " indented text." + + 4. If the `<entry-name>' is followed by a comma, the word `ifdef' (or + `ifndef') and a name `if_name', then the above entry will be under + `ifdef' control. + + /*=group entry_name, ifdef FOO + * attr: attribute value + =*/ + + Will produce the following: + + #ifdef FOO + #line nnn "source-file-name" + group = { + name = entry_name; + attr = 'attribute value'; + }; + #endif + + 5. If you use of the `subblock' option, you can specify a nested + value, *Note getdefs subblock::. That is, this text: + + * arg: int, this, what-it-is + + with the `--subblock=arg=type,name,doc' option would yield: + + arg = { type = int; name = this; doc = what-it-is; }; + + This section was generated by *AutoGen*, using the `agtexi-cmd' +template and the option descriptions for the `getdefs' program. This +software is released under the GNU General Public License, version 3 or +later. + +* Menu: + +* getdefs usage:: getdefs help/usage (`help') +* getdefs def-selection:: def-selection options +* getdefs enumerating:: enumerating options +* getdefs doc-insert:: doc-insert options +* getdefs input-files:: input-files options +* getdefs doc-output:: doc-output options +* getdefs config:: presetting/configuring getdefs +* getdefs exit status:: exit status +* getdefs See Also:: See Also + + +File: autogen.info, Node: getdefs usage, Next: getdefs def-selection, Up: getdefs Invocation + +8.5.1 getdefs help/usage (`help') +--------------------------------- + +This is the automatically generated usage text for getdefs. + + The text printed is the same whether selected with the `help' option +(`help') or the `more-help' option (`more-help'). `more-help' will +print the usage text by passing it through a pager program. +`more-help' is disabled on platforms without a working `fork(2)' +function. The `PAGER' environment variable is used to select the +program, defaulting to `more'. Both will exit with a status code of 0. + +getdefs (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 + + +File: autogen.info, Node: getdefs def-selection, Next: getdefs enumerating, Prev: getdefs usage, Up: getdefs Invocation + +8.5.2 def-selection options +--------------------------- + +Specify which definitions are of interest and what to say about them. + +defs-to-get option. +................... + +This is the "regexp to look for after the "/*="" option. This option +takes an argument string `reg-ex'. If you want definitions only from a +particular category, or even with names matching particular patterns, +then specify this regular expression for the text that must follow the +`/*='. + +subblock option. +................ + +This is the "subblock definition names" option. This option takes an +argument string `sub-def'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + This option is used to create shorthand entries for nested +definitions. For example, with: +using subblock thus + `--subblock=arg=argname,type,null' + +and defining an `arg' thus + `arg: this, char *' + +will then expand to: + `arg = { argname = this; type = "char *"; };' + The "this, char *" string is separated at the commas, with the white +space removed. You may use characters other than commas by starting +the value string with a punctuation character other than a single or +double quote character. You may also omit intermediate values by +placing the commas next to each other with no intervening white space. +For example, "+mumble++yes+" will expand to: +`arg = { argname = mumble; null = "yes"; };'. + +listattr option. +................ + +This is the "attribute with list of values" option. This option takes +an argument string `def'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + This option is used to create shorthand entries for definitions that +generally appear several times. That is, they tend to be a list of +values. For example, with: +`listattr=foo' defined, the text: +`foo: this, is, a, multi-list' will then expand to: +`foo = 'this', 'is', 'a', 'multi-list';' +The texts are separated by the commas, with the white space removed. +You may use characters other than commas by starting the value string +with a punctuation character other than a single or double quote +character. + + +File: autogen.info, Node: getdefs enumerating, Next: getdefs doc-insert, Prev: getdefs def-selection, Up: getdefs Invocation + +8.5.3 enumerating options +------------------------- + +specify how to number the definitions. + +ordering option. +................ + +This is the "alphabetize or use named file" option. This option takes +an optional argument string `file-name'. + +This option has some usage constraints. It: + * is enabled by default. + + By default, ordering is alphabetical by the entry name. Use, +`no-ordering' if order is unimportant. Use `ordering' with no argument +to order without case sensitivity. Use `ordering=<file-name>' if +chronological order is important. getdefs will maintain the text +content of `file-name'. `file-name' need not exist. + +first-index option. +................... + +This is the "the first index to apply to groups" option. This option +takes an argument number `first-index'. By default, the first +occurrence of a named definition will have an index of zero. +Sometimes, that needs to be a reserved value. Provide this option to +specify a different starting point. + + +File: autogen.info, Node: getdefs doc-insert, Next: getdefs input-files, Prev: getdefs enumerating, Up: getdefs Invocation + +8.5.4 doc-insert options +------------------------ + +Definition insertion options. + +filelist option. +................ + +This is the "insert source file names into defs" option. This option +takes an optional argument string `file'. Inserts the name of each +input file into the output definitions. If no argument is supplied, +the format will be: + infile = '%s'; + If an argument is supplied, that string will be used for the entry +name instead of INFILE. + +assign option. +.............. + +This is the "global assignments" option. This option takes an argument +string `ag-def'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + The argument to each copy of this option will be inserted into the +output definitions, with only a semicolon attached. + +common-assign option. +..................... + +This is the "assignments common to all blocks" option. This option +takes an argument string `ag-def'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + The argument to each copy of this option will be inserted into each +output definition, with only a semicolon attached. + +copy option. +............ + +This is the "file(s) to copy into definitions" option. This option +takes an argument string `file'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + The content of each file named by these options will be inserted into +the output definitions. + +srcfile option. +............... + +This is the "insert source file name into each def" option. This +option takes an optional argument string `file'. Inserts the name of +the input file where a definition was found into the output definition. +If no argument is supplied, the format will be: + srcfile = '%s'; + If an argument is supplied, that string will be used for the entry +name instead of SRCFILE. + +linenum option. +............... + +This is the "insert source line number into each def" option. This +option takes an optional argument string `def-name'. Inserts the line +number in the input file where a definition was found into the output +definition. If no argument is supplied, the format will be: + linenum = '%s'; + If an argument is supplied, that string will be used for the entry +name instead of LINENUM. + + +File: autogen.info, Node: getdefs input-files, Next: getdefs doc-output, Prev: getdefs doc-insert, Up: getdefs Invocation + +8.5.5 input-files options +------------------------- + +specify which files to search for markers. + +input option. +............. + +This is the "input file to search for defs" option. This option takes +an argument string `src-file'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + All files that are to be searched for definitions must be named on +the command line or read from `stdin'. If there is only one `input' +option and it is the string, "-", then the input file list is read from +`stdin'. If a command line argument is not an option name and does not +contain an assignment operator (`='), then it defaults to being an +input file name. At least one input file must be specified. + + +File: autogen.info, Node: getdefs doc-output, Next: getdefs config, Prev: getdefs input-files, Up: getdefs Invocation + +8.5.6 doc-output options +------------------------ + +Definition output disposition options:. + +output option. +.............. + +This is the "output file to open" option. This option takes an +argument string `file'. + +This option has some usage constraints. It: + * is a member of the autogen class of options. + + If you are not sending the output to an AutoGen process, you may +name an output file instead. + +autogen option. +............... + +This is the "invoke autogen with defs" option. This option takes an +optional argument string `ag-cmd'. + +This option has some usage constraints. It: + * is enabled by default. + + * is a member of the autogen class of options. + + This is the default output mode. Specifying `no-autogen' is +equivalent to `output=-'. If you supply an argument to this option, +that program will be started as if it were AutoGen and its standard in +will be set to the output definitions of this program. + +template option. +................ + +This is the "template name" option. This option takes an argument +string `file'. Specifies the template name to be used for generating +the final output. + +agarg option. +............. + +This is the "autogen argument" option. This option takes an argument +string `ag-opt'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + * must not appear in combination with any of the following options: + output. + + This is a pass-through argument. It allows you to specify any +arbitrary argument to be passed to AutoGen. + +base-name option. +................. + +This is the "base name for output file(s)" option. This option takes +an argument string `name'. + +This option has some usage constraints. It: + * must not appear in combination with any of the following options: + output. + + When output is going to AutoGen, a base name must either be supplied +or derived. If this option is not supplied, then it is taken from the +`template' option. If that is not provided either, then it is set to +the base name of the current directory. + + +File: autogen.info, Node: getdefs config, Next: getdefs exit status, Prev: getdefs doc-output, Up: getdefs Invocation + +8.5.7 presetting/configuring getdefs +------------------------------------ + +Any option that is not marked as not presettable may be preset by +loading values from configuration ("rc" or "ini") files. + +`libopts' will search in `/dev/null' for configuration (option) data. +If this is a plain file, it is simply processed. If it is a directory, +then a file named `.getdefsrc' is searched for within that directory. + + Configuration files may be in a wide variety of formats. The basic +format is an option name followed by a value (argument) on the same +line. Values may be separated from the option name with a colon, equal +sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + + Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: + [GETDEFS] + or by + <?program getdefs> + Do not mix these styles within one configuration file. + + Compound values and carefully constructed string values may also be +specified using XML syntax: + <option-name> + <sub-opt>...<...>...</sub-opt> + </option-name> + yielding an `option-name.sub-opt' string value of + "...<...>..." + `AutoOpts' does not track suboptions. You simply note that it is a +hierarchicly valued option. `AutoOpts' does provide a means for +searching the associated name/value pair list (see: optionFindValue). + + The command line options relating to configuration and/or usage help +are: + +version +....... + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much +licensing detail to provide. The default is to print just the version. +The licensing infomation may be selected with an option argument. Only +the first letter of the argument is examined: + +`version' + Only print the version. This is the default. + +`copyright' + Name the copyright usage licensing terms. + +`verbose' + Print the full copyright usage licensing terms. + + +File: autogen.info, Node: getdefs exit status, Next: getdefs See Also, Prev: getdefs config, Up: getdefs Invocation + +8.5.8 getdefs exit status +------------------------- + +One of the following exit values will be returned: +`0 (EXIT_SUCCESS)' + Successful program execution. + +`1 (EXIT_FAILURE)' + The operation failed or the command syntax was not valid. + +`66 (EX_NOINPUT)' + A specified configuration file could not be loaded. + +`70 (EX_SOFTWARE)' + libopts had an internal operational error. Please report it to + autogen-users@lists.sourceforge.net. Thank you. + + +File: autogen.info, Node: getdefs See Also, Prev: getdefs exit status, Up: getdefs Invocation + +8.5.9 getdefs See Also +---------------------- + +This program is documented more fully in the Getdefs section of the +Add-On chapter in the `AutoGen' Info system documentation. + + +File: autogen.info, Node: xml2ag Invocation, Next: snprintfv, Prev: getdefs Invocation, Up: Add-Ons + +8.6 Invoking xml2ag +=================== + +This program will convert any arbitrary XML file into equivalent +AutoGen definitions, and invoke AutoGen. The template used will be +derived from either: + * The *-override-tpl* command line option + + * A top level XML attribute named, "`template'" + One or the other *must* be provided, or the program will exit with a +failure message. + + The _base-name_ for the output will similarly be either: + * The *-base-name* command line option. + + * The base name of the `.xml' file. + + The definitions derived from XML generally have an extra layer of +definition. Specifically, this XML input: + <mumble attr="foo"> + mumble-1 + <grumble> + grumble, grumble, grumble. + </grumble>mumble, mumble + </mumble> + Will get converted into this: + mumble = { + grumble = { + text = 'grumble, grumble, grumble'; + }; + text = 'mumble-1'; + text = 'mumble, mumble'; + }; + Please notice that some information is lost. AutoGen cannot tell +that "grumble" used to lie between the mumble texts. Also please note +that you cannot assign: + grumble = 'grumble, grumble, grumble.'; + because if another "grumble" has an attribute or multiple texts, it +becomes impossible to have the definitions be the same type (compound +or text values). + + This section was generated by *AutoGen*, using the `agtexi-cmd' +template and the option descriptions for the `xml2ag' program. This +software is released under the GNU General Public License, version 3 or +later. + +* Menu: + +* xml2ag usage:: xml2ag help/usage (`--help') +* xml2ag the-xml2ag-option:: the-xml2ag-option options +* xml2ag autogen-options:: autogen-options options +* xml2ag exit status:: exit status + + +File: autogen.info, Node: xml2ag usage, Next: xml2ag the-xml2ag-option, Up: xml2ag Invocation + +8.6.1 xml2ag help/usage (`--help') +---------------------------------- + +This is the automatically generated usage text for xml2ag. + + The text printed is the same whether selected with the `help' option +(`--help') or the `more-help' option (`--more-help'). `more-help' will +print the usage text by passing it through a pager program. +`more-help' is disabled on platforms without a working `fork(2)' +function. The `PAGER' environment variable is used to select the +program, defaulting to `more'. Both will exit with a status code of 0. + +xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.16.2 +USAGE: xml2ag [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ] + +All other options are derived from autogen: + + Flg Arg Option-Name Description + -O Str output Output file in lieu of AutoGen processing + +All other options: + + Flg Arg Option-Name Description + -L Str templ-dirs Template search directory list + - may appear multiple times + -T Str override-tpl Override template file + -l Str lib-template Library template file + - may appear multiple times + Str definitions Definitions input file + -S Str load-scheme Scheme code file to load + -F Str load-functions Load scheme function library + Str shell name or path name of shell to use + -m no no-fmemopen Do not use in-mem streams + Str equate characters considered equivalent + -b Str base-name Base name for output file(s) + no source-time set mod times to latest source + no writable Allow output files to be writable + - disabled as --not-writable + Num loop-limit Limit on increment loops + - is scalable with a suffix: k/K/m/M/g/G/t/T + - It must lie in one of the ranges: + -1 exactly, or + 1 to 16777216 + -t Num timeout Time limit for server shell + - It must be in the range: + 0 to 3600 + KWd trace tracing level of detail + Str trace-out tracing output file or filter + no show-defs Show the definition tree + no used-defines Show the definitions used + -C no core Leave a core dump on a failure exit + -s Str skip-suffix Omit the file with this suffix + - prohibits these options: + select-suffix + - may appear multiple times + -o Str select-suffix specify this output suffix + - may appear multiple times + -D Str define name to add to definition list + - may appear multiple times + -U Str undefine definition list removal pattern + - an alternate for define + -M opt make-dep emit make dependency file + - may appear multiple times + +version, usage and configuration options: + + Flg Arg Option-Name Description + -v opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +This program will convert any arbitrary XML file into equivalent AutoGen +definitions, and invoke AutoGen. + +The valid "trace" option keywords are: + nothing debug-message server-shell templates block-macros + expressions everything + or an integer from 0 through 6 + +The template will be derived from either: * the ``--override-tpl'' command +line option * a top level XML attribute named, "template" + +The ``base-name'' for the output will similarly be either: * the +``--base-name'' command line option * the base name of the .xml file +Packaged by Bruce (2012-08-11) +Report xml2ag bugs to bkorb@gnu.org + + +File: autogen.info, Node: xml2ag the-xml2ag-option, Next: xml2ag autogen-options, Prev: xml2ag usage, Up: xml2ag Invocation + +8.6.2 the-xml2ag-option options +------------------------------- + +All other options are derived from autogen. + +output option (-O). +................... + +This is the "output file in lieu of autogen processing" option. This +option takes an argument string `file'. By default, the output is +handed to an AutoGen for processing. However, you may save the +definitions to a file instead. + + +File: autogen.info, Node: xml2ag autogen-options, Next: xml2ag exit status, Prev: xml2ag the-xml2ag-option, Up: xml2ag Invocation + +8.6.3 autogen-options options +----------------------------- + +All other options. These options are mostly just passed throug to +`autogen'. The one exception is `--override-tpl' which replaces the +default template in the output definitions. It does not get passed +through on the command line. + +templ-dirs option (-L). +....................... + +This is the "template search directory list" option. This option takes +an argument string `dir'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + Pass-through AutoGen argument + +override-tpl option (-T). +......................... + +This is the "override template file" option. This option takes an +argument string `tpl-file'. Pass-through AutoGen argument + +lib-template option (-l). +......................... + +This is the "library template file" option. This option takes an +argument string `tpl-file'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + Pass-through AutoGen argument + +definitions option. +................... + +This is the "definitions input file" option. This option takes an +argument string `file'. Pass-through AutoGen argument + +load-scheme option (-S). +........................ + +This is the "scheme code file to load" option. This option takes an +argument string `file'. Pass-through AutoGen argument + +load-functions option (-F). +........................... + +This is the "load scheme function library" option. This option takes +an argument string `file'. + +This option has some usage constraints. It: + * must be compiled in by defining `HAVE_DLOPEN' during the + compilation. + + Pass-through AutoGen argument + +shell option. +............. + +This is the "name or path name of shell to use" option. This option +takes an argument string `shell'. Pass-through AutoGen argument + +no-fmemopen option (-m). +........................ + +This is the "do not use in-mem streams" option. Pass-through AutoGen +argument + +equate option. +.............. + +This is the "characters considered equivalent" option. This option +takes an argument string `char-list'. Pass-through AutoGen argument + +base-name option (-b). +...................... + +This is the "base name for output file(s)" option. This option takes +an argument string `name'. Pass-through AutoGen argument + +source-time option. +................... + +This is the "set mod times to latest source" option. Pass-through +AutoGen argument + +writable option. +................ + +This is the "allow output files to be writable" option. Pass-through +AutoGen argument + +loop-limit option. +.................. + +This is the "limit on increment loops" option. This option takes an +argument number `lim'. Pass-through AutoGen argument + +timeout option (-t). +.................... + +This is the "time limit for server shell" option. This option takes an +argument number `time-lim'. Pass-through AutoGen argument + +trace option. +............. + +This is the "tracing level of detail" option. This option takes an +argument keyword `level'. + +This option has some usage constraints. It: + * This option takes a keyword as its argument. The argument sets an + enumeration value that can be tested by comparing the option value + macro (OPT_VALUE_TRACE). The available keywords are: + nothing debug-message server-shell + templates block-macros expressions + everything + + or their numeric equivalent. + + Pass-through AutoGen argument + +trace-out option. +................. + +This is the "tracing output file or filter" option. This option takes +an argument string `file'. Pass-through AutoGen argument + +show-defs option. +................. + +This is the "show the definition tree" option. Pass-through AutoGen +argument + +used-defines option. +.................... + +This is the "show the definitions used" option. Pass-through AutoGen +argument + +core option (-C). +................. + +This is the "leave a core dump on a failure exit" option. + +This option has some usage constraints. It: + * must be compiled in by defining `HAVE_SYS_RESOURCE_H' during the + compilation. + + Many systems default to a zero sized core limit. If the system has +the sys/resource.h header and if this option is supplied, then in the +failure exit path, autogen will attempt to set the soft core limit to +whatever the hard core limit is. If that does not work, then an +administrator must raise the hard core size limit. + +skip-suffix option (-s). +........................ + +This is the "omit the file with this suffix" option. This option takes +an argument string `suffix'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + * must not appear in combination with any of the following options: + select-suffix. + + Pass-through AutoGen argument + +select-suffix option (-o). +.......................... + +This is the "specify this output suffix" option. This option takes an +argument string `suffix'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + Pass-through AutoGen argument + +define option (-D). +................... + +This is the "name to add to definition list" option. This option takes +an argument string `value'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + Pass-through AutoGen argument + +undefine option (-U). +..................... + +This is the "definition list removal pattern" option. This option +takes an argument string `name-pat'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + Pass-through AutoGen argument + +make-dep option (-M). +..................... + +This is the "emit make dependency file" option. This option takes an +optional argument string `type'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + Pass-through AutoGen argument + + +File: autogen.info, Node: xml2ag exit status, Prev: xml2ag autogen-options, Up: xml2ag Invocation + +8.6.4 xml2ag exit status +------------------------ + +One of the following exit values will be returned: +`0 (EXIT_SUCCESS)' + Successful program execution. + +`1 (EXIT_OPTION_ERROR)' + The command options were misconfigured. + +`2 (EXIT_BAD_TEMPLATE)' + An error was encountered processing the template. + +`3 (EXIT_BAD_DEFINITIONS)' + The definitions could not be deciphered. + +`4 (EXIT_LOAD_ERROR)' + An error was encountered during the load phase. + +`5 (EXIT_SIGNAL)' + Program exited due to catching a signal. If your template includes + string formatting, a number argument to a "%s" formatting element + will trigger a segmentation fault. Autogen will catch the seg + fault signal and exit with `AUTOGEN_EXIT_SIGNAL(5)'. + Alternatively, AutoGen may have been interrupted with a `kill(2)' + signal. + + +File: autogen.info, Node: snprintfv, Prev: xml2ag Invocation, Up: Add-Ons + +8.7 Replacement for Stdio Formatting Library +============================================ + +Using the `printf' formatting routines in a portable fashion has always +been a pain, and this package has been way more pain than anyone ever +imagined. Hopefully, with this release of snprintfv, the pain is now +over for all time. + + The issues with portable usage are these: + + 1. Argument number specifiers are often either not implemented or are + buggy. Even GNU libc, version 1 got it wrong. + + 2. ANSI/ISO "forgot" to provide a mechanism for computing argument + lists for vararg procedures. + + 3. The argument array version of printf (`printfv()') is not + generally available, does not work with the native printf, and + does not have a working argument number specifier in the format + specification. (Last I knew, anyway.) + + 4. You cannot fake varargs by calling `vprintf()' with an array of + arguments, because ANSI does not require such an implementation + and some vendors play funny tricks because they are allowed to. + + These four issues made it impossible for AutoGen to ship without its +own implementation of the `printf' formatting routines. Since we were +forced to do this, we decided to make the formatting routines both +better and more complete :-). We addressed these issues and added the +following features to the common printf API: + + 5. The formatted output can be written to + + * a string allocated by the formatting function (`asprintf()'). + + * a file descriptor instead of a file stream (`dprintf()'). + + * a user specified stream (`stream_printf()'). + + 6. The formatting functions can be augmented with your own functions. + These functions are allowed to consume more than one character + from the format, but must commence with a unique character. For + example, + + "%{struct stat}\n" + + might be used with '{' registered to a procedure that would look + up "struct stat" in a symbol table and do appropriate things, + consuming the format string through the '}' character. + + Gary V. Vaughan was generous enough to supply this implementation. +Many thanks!! + + For further details, the reader is referred to the snprintfv +documentation. These functions are also available in the template +processing as `sprintf' (*note SCM sprintf::), `printf' (*note SCM +printf::), `fprintf' (*note SCM fprintf::), and `shellf' (*note SCM +shellf::). + + +File: autogen.info, Node: Future, Next: Copying This Manual, Prev: Add-Ons, Up: Top + +9 Some ideas for the future. +**************************** + +Here are some things that might happen in the distant future. + + * Fix up current tools that contain miserably complex perl, shell, + sed, awk and m4 scripts to instead use this tool. + + +File: autogen.info, Node: Copying This Manual, Next: Concept Index, Prev: Future, Up: Top + +Appendix A Copying This Manual +****************************** + +You may copy this manual under the terms of the FDL (the GNU Free +Documentation License (http://gnu.org/licenses/fdl.texi)). + + Version 1.2, November 2002 + + Copyright (C) 2000,2001,2002 Free Software Foundation, Inc. + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. + We recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it + can be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You + accept the license if you copy, modify or distribute the work in a + way requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in + the notice that says that the Document is released under this + License. If a section does not fit the above definition of + Secondary then it is not allowed to be designated as Invariant. + The Document may contain zero Invariant Sections. If the Document + does not identify any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images + composed of pixels) generic paint programs or (for drawings) some + widely available drawing editor, and that is suitable for input to + text formatters or for automatic translation to a variety of + formats suitable for input to text formatters. A copy made in an + otherwise Transparent file format whose markup, or absence of + markup, has been arranged to thwart or discourage subsequent + modification by readers is not Transparent. An image format is + not Transparent if used for any substantial amount of text. A + copy that is not "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and + standard-conforming simple HTML, PostScript or PDF designed for + human modification. Examples of transparent image formats include + PNG, XCF and JPG. Opaque formats include proprietary formats that + can be read and edited only by proprietary word processors, SGML or + XML for which the DTD and/or processing tools are not generally + available, and the machine-generated HTML, PostScript or PDF + produced by some word processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow + the conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the + title equally prominent and visible. You may add other material + on the covers in addition. Copying with changes limited to the + covers, as long as they preserve the title of the Document and + satisfy these conditions, can be treated as verbatim copying in + other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a + machine-readable Transparent copy along with each Opaque copy, or + state in or with each Opaque copy a computer-network location from + which the general network-using public has access to download + using public-standard network protocols a complete Transparent + copy of the Document, free of added material. If you use the + latter option, you must take reasonably prudent steps, when you + begin distribution of Opaque copies in quantity, to ensure that + this Transparent copy will remain thus accessible at the stated + location until at least one year after the last time you + distribute an Opaque copy (directly or through your agents or + retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of + copies, to give them a chance to provide you with an updated + version of the Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with + the Modified Version filling the role of the Document, thus + licensing distribution and modification of the Modified Version to + whoever possesses a copy of it. In addition, you must do these + things in the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of + previous versions (which should, if there were any, be listed + in the History section of the Document). You may use the + same title as a previous version if the original publisher of + that version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on + the Title Page. If there is no section Entitled "History" in + the Document, create one stating the title, year, authors, + and publisher of the Document as given on its Title Page, + then add an item describing the Modified Version as stated in + the previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in + the "History" section. You may omit a network location for a + work that was published at least four years before the + Document itself, or if the original publisher of the version + it refers to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the + section all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, + unaltered in their text and in their titles. Section numbers + or the equivalent are not considered part of the section + titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option + designate some or all of these sections as invariant. To do this, + add their titles to the list of Invariant Sections in the Modified + Version's license notice. These titles must be distinct from any + other section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end + of the list of Cover Texts in the Modified Version. Only one + passage of Front-Cover Text and one of Back-Cover Text may be + added by (or through arrangements made by) any one entity. If the + Document already includes a cover text for the same cover, + previously added by you or by arrangement made by the same entity + you are acting on behalf of, you may not add another; but you may + replace the old one, on explicit permission from the previous + publisher that added the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination + all of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the + documents in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow + this License in all other respects regarding verbatim copying of + that document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of + a storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided for under this License. Any other + attempt to copy, modify, sublicense or distribute the Document is + void, and will automatically terminate your rights under this + License. However, parties who have received copies, or rights, + from you under this License will not have their licenses + terminated so long as such parties remain in full compliance. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + `http://www.gnu.org/copyleft/'. + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If + the Document does not specify a version number of this License, + you may choose any version ever published (not as a draft) by the + Free Software Foundation. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + copyright (c) 1992-2012 by Bruce Korb - all rights reserved + 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. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, to +permit their use in free software. + + +File: autogen.info, Node: Concept Index, Next: Function Index, Prev: Copying This Manual, Up: Top + +Concept Index +************* + + +* Menu: + +* #assert: Directives. (line 31) +* #define: Directives. (line 45) +* #elif: Directives. (line 53) +* #else: Directives. (line 57) +* #endif: Directives. (line 62) +* #endmac: Directives. (line 66) +* #endshell: Directives. (line 70) +* #error: Directives. (line 74) +* #if: Directives. (line 78) +* #ifdef: Directives. (line 82) +* #ifndef: Directives. (line 88) +* #include: Directives. (line 93) +* #line: Directives. (line 99) +* #macdef: Directives. (line 106) +* #option: Directives. (line 111) +* #shell: Directives. (line 126) +* #undef: Directives. (line 132) +* .: naming values. (line 24) +* .def file: Definitions File. (line 6) +* .tpl file: Template File. (line 6) +* Alternate Definition: Alternate Definition. + (line 6) +* assert directive: Directives. (line 31) +* Augmenting AutoGen: Augmenting AutoGen. (line 6) +* AutoEvents: AutoEvents. (line 6) +* AutoFSM: AutoFSM. (line 6) +* autogen: autogen Invocation. (line 6) +* AutoGen Definition Extraction Tool: getdefs Invocation. (line 6) +* autogen help: autogen usage. (line 6) +* autogen-base-name: autogen out-handling. + (line 11) +* autogen-core: autogen debug-tpl. (line 139) +* autogen-define: autogen processing. (line 49) +* autogen-definitions: autogen input-select. + (line 53) +* autogen-equate: autogen input-select. + (line 129) +* autogen-lib-template: autogen input-select. + (line 40) +* autogen-load-functions: autogen input-select. + (line 82) +* autogen-load-scheme: autogen input-select. + (line 71) +* autogen-loop-limit: autogen debug-tpl. (line 13) +* autogen-make-dep: autogen dep-track. (line 11) +* autogen-no-fmemopen: autogen input-select. + (line 112) +* autogen-override-tpl: autogen input-select. + (line 26) +* autogen-select-suffix: autogen processing. (line 33) +* autogen-shell: autogen input-select. + (line 96) +* autogen-show-defs: autogen debug-tpl. (line 106) +* autogen-skip-suffix: autogen processing. (line 13) +* autogen-source-time: autogen out-handling. + (line 33) +* autogen-templ-dirs: autogen input-select. + (line 12) +* autogen-timeout: autogen debug-tpl. (line 23) +* autogen-trace: autogen debug-tpl. (line 40) +* autogen-trace-out: autogen debug-tpl. (line 95) +* autogen-undefine: autogen processing. (line 83) +* autogen-used-defines: autogen debug-tpl. (line 121) +* autogen-writable: autogen out-handling. + (line 43) +* AutoInfo: AutoInfo. (line 6) +* AutoMan pages: AutoMan pages. (line 6) +* automatic options: automatic options. (line 6) +* autoopts <1>: Caveats. (line 26) +* autoopts: AutoOpts. (line 6) +* AutoOpts API: AutoOpts API. (line 6) +* autoopts directives: config directives. (line 6) +* AutoXDR: AutoXDR. (line 6) +* backtrack: naming values. (line 25) +* Columnize Input Text: columns Invocation. (line 6) +* columns: columns Invocation. (line 6) +* columns help: columns usage. (line 6) +* columns-by-columns: columns ordering. (line 11) +* columns-col-width: columns dimensions. (line 29) +* columns-columns: columns dimensions. (line 21) +* columns-ending: columns treatment. (line 90) +* columns-fill: columns treatment. (line 20) +* columns-first-indent: columns treatment. (line 42) +* columns-format: columns treatment. (line 67) +* columns-indent: columns treatment. (line 34) +* columns-input: columns input-text. (line 11) +* columns-line-separation: columns treatment. (line 82) +* columns-separation: columns treatment. (line 75) +* columns-sort: columns ordering. (line 19) +* columns-spread: columns treatment. (line 11) +* columns-tab-width: columns dimensions. (line 37) +* columns-width: columns dimensions. (line 11) +* comments: Comments. (line 6) +* Common Option Attributes: Common Attributes. (line 6) +* compound definitions: Definitions. (line 44) +* concat-string: concat-string. (line 6) +* conditional emit <1>: WHILE. (line 6) +* conditional emit: IF. (line 6) +* configuration file: shell options. (line 6) +* Configuration File <1>: Config File Format. (line 6) +* Configuration File: config example. (line 6) +* configuration file <1>: Option Processing Data. + (line 42) +* configuration file <2>: automatic options. (line 57) +* configuration file: opt-attr no-preset. (line 6) +* Configuration File example: config example. (line 6) +* configuring: configuring. (line 6) +* define directive: Directives. (line 45) +* define macro: DEFINE. (line 6) +* Definition Index: Index Assignments. (line 6) +* definitions: Definitions. (line 6) +* definitions file: Definitions File. (line 6) +* design goals: Generalities. (line 11) +* directives: Directives. (line 6) +* diversion: output controls. (line 6) +* documentation attributes: documentation attributes. + (line 6) +* Dynamic Definition Text: Dynamic Text. (line 6) +* elif directive: Directives. (line 53) +* else directive: Directives. (line 57) +* endif directive: Directives. (line 62) +* endmac directive: Directives. (line 66) +* endshell directive: Directives. (line 70) +* environrc: environrc. (line 6) +* error directive: Directives. (line 74) +* example, simple AutoGen: Example Usage. (line 6) +* example, simple AutoOpts: Quick Start. (line 6) +* expression syntax: expression syntax. (line 6) +* FDL, GNU Free Documentation License: Copying This Manual. (line 9) +* features: Features. (line 6) +* finite state machine: AutoFSM. (line 6) +* flags-cant: Option Conflict Attributes. + (line 19) +* flags-must: Option Conflict Attributes. + (line 15) +* fOptState: Option Processing Data. + (line 30) +* for loop: FOR. (line 6) +* futures: Future. (line 6) +* getdefs: getdefs Invocation. (line 6) +* getdefs help: getdefs usage. (line 6) +* getdefs-agarg: getdefs doc-output. (line 46) +* getdefs-assign: getdefs doc-insert. (line 22) +* getdefs-autogen: getdefs doc-output. (line 23) +* getdefs-base-name: getdefs doc-output. (line 61) +* getdefs-common-assign: getdefs doc-insert. (line 34) +* getdefs-copy: getdefs doc-insert. (line 46) +* getdefs-defs-to-get: getdefs def-selection. + (line 11) +* getdefs-filelist: getdefs doc-insert. (line 11) +* getdefs-first-index: getdefs enumerating. (line 26) +* getdefs-input: getdefs input-files. (line 11) +* getdefs-linenum: getdefs doc-insert. (line 69) +* getdefs-listattr: getdefs def-selection. + (line 47) +* getdefs-ordering: getdefs enumerating. (line 11) +* getdefs-output: getdefs doc-output. (line 11) +* getdefs-srcfile: getdefs doc-insert. (line 58) +* getdefs-subblock: getdefs def-selection. + (line 20) +* getdefs-template: getdefs doc-output. (line 39) +* getopt_long: getopt_long. (line 6) +* gnu: Caveats. (line 21) +* here-string: here-string. (line 6) +* identification: Identification. (line 6) +* if directive: Directives. (line 78) +* if test: IF. (line 6) +* ifdef directive: Directives. (line 82) +* ifndef directive: Directives. (line 88) +* immediate action: Immediate Action. (line 6) +* include directive: Directives. (line 93) +* information attributes: information attributes. + (line 6) +* Installing: installing. (line 6) +* Internationalizing AutoOpts: i18n. (line 6) +* Internationalizing Options: Internationalizing Options. + (line 6) +* Introduction: Introduction. (line 6) +* library attributes: library attributes. (line 6) +* Licensing: Licensing. (line 6) +* line directive: Directives. (line 99) +* looping, for: FOR. (line 6) +* m4: Testimonial. (line 42) +* macdef directive: Directives. (line 106) +* macro syntax: AGMacro syntax. (line 6) +* macro, pseudo: Template File. (line 10) +* main procedure: Generated main. (line 6) +* misuse-usage: Caveats. (line 34) +* named option mode: presentation attributes. + (line 15) +* Naming Conflicts: Naming Conflicts. (line 6) +* naming values: naming values. (line 6) +* native macros: native macros. (line 6) +* no-misuse-usage: Caveats. (line 30) +* optActualIndex: Option Processing Data. + (line 17) +* optActualValue: Option Processing Data. + (line 18) +* optIndex: Option Processing Data. + (line 11) +* Option Argument Handling: Option Argument Handling. + (line 6) +* Option Arguments: Option Arguments. (line 6) +* option attributes: option attributes. (line 6) +* Option Conflict Attributes: Option Conflict Attributes. + (line 6) +* Option Definitions: Option Definitions. (line 6) +* option descriptor: option descriptor. (line 6) +* option directive: Directives. (line 111) +* Option Processing Data: Option Processing Data. + (line 6) +* optOccCt: Option Processing Data. + (line 24) +* optValue: Option Processing Data. + (line 12) +* predefines: Predefines. (line 6) +* program attributes: program attributes. (line 6) +* pseudo macro <1>: pseudo macro. (line 6) +* pseudo macro: Template File. (line 10) +* pzLastArg: Option Processing Data. + (line 83) +* pzProgName: Option Processing Data. + (line 90) +* pzProgPath: Option Processing Data. + (line 94) +* rcfile <1>: config example. (line 6) +* rcfile: loading rcfile. (line 6) +* Redirecting Output: output controls. (line 6) +* remote procedure call: AutoXDR. (line 6) +* Required Attributes: Required Attributes. (line 6) +* RPC: AutoXDR. (line 6) +* rpcgen: AutoXDR. (line 6) +* sample rcfile: sample rcfile. (line 6) +* shell directive: Directives. (line 126) +* shell options <1>: shell options. (line 6) +* shell options: Presetting Options. (line 6) +* shell-generated string: shell-generated. (line 6) +* Signal Names: signal names. (line 6) +* simple definitions: Definitions. (line 44) +* standard options: standard options. (line 6) +* string, double quote: double-quote-string. (line 6) +* string, shell output: shell-generated. (line 6) +* string, single quote: single-quote-string. (line 6) +* template file <1>: Template File. (line 6) +* template file: Identification. (line 21) +* The Automated Program Generator: autogen Invocation. (line 6) +* undef directive: Directives. (line 132) +* using AutoOpts: Using AutoOpts. (line 6) +* while test: WHILE. (line 6) +* XDR: AutoXDR. (line 6) +* XML to AutoGen Definiton Converter: xml2ag Invocation. (line 6) +* xml2ag: xml2ag Invocation. (line 6) +* xml2ag help: xml2ag usage. (line 6) +* xml2ag-base-name: xml2ag autogen-options. + (line 84) +* xml2ag-core: xml2ag autogen-options. + (line 150) +* xml2ag-define: xml2ag autogen-options. + (line 190) +* xml2ag-definitions: xml2ag autogen-options. + (line 42) +* xml2ag-equate: xml2ag autogen-options. + (line 78) +* xml2ag-lib-template: xml2ag autogen-options. + (line 31) +* xml2ag-load-functions: xml2ag autogen-options. + (line 54) +* xml2ag-load-scheme: xml2ag autogen-options. + (line 48) +* xml2ag-loop-limit: xml2ag autogen-options. + (line 102) +* xml2ag-make-dep: xml2ag autogen-options. + (line 212) +* xml2ag-no-fmemopen: xml2ag autogen-options. + (line 72) +* xml2ag-output: xml2ag the-xml2ag-option. + (line 11) +* xml2ag-override-tpl: xml2ag autogen-options. + (line 25) +* xml2ag-select-suffix: xml2ag autogen-options. + (line 179) +* xml2ag-shell: xml2ag autogen-options. + (line 66) +* xml2ag-show-defs: xml2ag autogen-options. + (line 138) +* xml2ag-skip-suffix: xml2ag autogen-options. + (line 165) +* xml2ag-source-time: xml2ag autogen-options. + (line 90) +* xml2ag-templ-dirs: xml2ag autogen-options. + (line 14) +* xml2ag-timeout: xml2ag autogen-options. + (line 108) +* xml2ag-trace: xml2ag autogen-options. + (line 114) +* xml2ag-trace-out: xml2ag autogen-options. + (line 132) +* xml2ag-undefine: xml2ag autogen-options. + (line 201) +* xml2ag-used-defines: xml2ag autogen-options. + (line 144) +* xml2ag-writable: xml2ag autogen-options. + (line 96) + + +File: autogen.info, Node: Function Index, Prev: Concept Index, Up: Top + +Function Index +************** + + +* Menu: + +* *=: SCM *=. (line 6) +* *=*: SCM *=*. (line 6) +* *==: SCM *==. (line 6) +* *==*: SCM *==*. (line 6) +* *~: SCM *~. (line 6) +* *~*: SCM *~*. (line 6) +* *~~: SCM *~~. (line 6) +* *~~*: SCM *~~*. (line 6) +* =: SCM =. (line 6) +* =*: SCM =*. (line 6) +* ==: SCM ==. (line 6) +* ==*: SCM ==*. (line 6) +* ag-fprintf: SCM ag-fprintf. (line 6) +* ag-function?: SCM ag-function?. (line 6) +* agpl: SCM agpl. (line 6) +* ao_string_tokenize: libopts-ao_string_tokenize. + (line 6) +* autogen-version: SCM autogen-version. (line 6) +* base-name: SCM base-name. (line 6) +* BREAK: BREAK. (line 6) +* bsd: SCM bsd. (line 6) +* c-file-line-fmt: SCM c-file-line-fmt. (line 6) +* c-string: SCM c-string. (line 6) +* CASE: CASE. (line 6) +* chdir: SCM chdir. (line 6) +* CLEAR_OPT: CLEAR_OPT. (line 6) +* COMMENT: COMMENT. (line 6) +* configFileLoad: libopts-configFileLoad. + (line 6) +* CONTINUE: CONTINUE. (line 6) +* count: SCM count. (line 6) +* COUNT_OPT: COUNT_OPT. (line 6) +* DEBUG: DEBUG. (line 6) +* def-file: SCM def-file. (line 6) +* def-file-line: SCM def-file-line. (line 6) +* DEFINE: DEFINE. (line 6) +* DESC: DESC. (line 6) +* DISABLE_OPT_name: DISABLE_OPT_name. (line 6) +* dne: SCM dne. (line 6) +* ELIF: ELIF. (line 6) +* ELSE: ELSE. (line 6) +* emit: SCM emit. (line 6) +* emit-string-table: SCM emit-string-table. (line 6) +* ENABLED_OPT: ENABLED_OPT. (line 6) +* ENDDEF: ENDDEF. (line 6) +* ENDFOR: ENDFOR. (line 6) +* ENDIF: ENDIF. (line 6) +* ENDWHILE: ENDWHILE. (line 6) +* error: SCM error. (line 6) +* error-source-line: SCM error-source-line. (line 6) +* ERRSKIP_OPTERR: ERRSKIP_OPTERR. (line 6) +* ERRSTOP_OPTERR: ERRSTOP_OPTERR. (line 6) +* ESAC: ESAC. (line 6) +* exist?: SCM exist?. (line 6) +* EXPR: EXPR. (line 6) +* extract: SCM extract. (line 6) +* find-file: SCM find-file. (line 6) +* first-for?: SCM first-for?. (line 6) +* FOR: FOR. (line 6) +* for-by: SCM for-by. (line 6) +* for-from: SCM for-from. (line 6) +* for-index: SCM for-index. (line 6) +* for-sep: SCM for-sep. (line 6) +* for-to: SCM for-to. (line 6) +* format-arg-count: SCM format-arg-count. (line 6) +* fprintf: SCM fprintf. (line 6) +* get: SCM get. (line 6) +* get-c-name: SCM get-c-name. (line 6) +* get-down-name: SCM get-down-name. (line 6) +* get-up-name: SCM get-up-name. (line 6) +* gperf: SCM gperf. (line 6) +* gperf-code: SCM gperf-code. (line 6) +* gpl: SCM gpl. (line 6) +* HAVE_OPT: HAVE_OPT. (line 6) +* hide-email: SCM hide-email. (line 6) +* high-lim: SCM high-lim. (line 6) +* html-escape-encode: SCM html-escape-encode. + (line 6) +* IF: IF. (line 6) +* in?: SCM in?. (line 6) +* INCLUDE: INCLUDE. (line 6) +* INVOKE: INVOKE. (line 6) +* ISSEL_OPT: ISSEL_OPT. (line 6) +* ISUNUSED_OPT: ISUNUSED_OPT. (line 6) +* join: SCM join. (line 6) +* kr-string: SCM kr-string. (line 6) +* last-for?: SCM last-for?. (line 6) +* len: SCM len. (line 6) +* lgpl: SCM lgpl. (line 6) +* license: SCM license. (line 6) +* license-description: SCM license-description. + (line 6) +* license-full: SCM license-full. (line 6) +* license-info: SCM license-info. (line 6) +* license-name: SCM license-name. (line 6) +* low-lim: SCM low-lim. (line 6) +* make-gperf: SCM make-gperf. (line 6) +* make-header-guard: SCM make-header-guard. (line 6) +* make-tmp-dir: SCM make-tmp-dir. (line 6) +* makefile-script: SCM makefile-script. (line 6) +* match-value?: SCM match-value?. (line 6) +* max: SCM max. (line 6) +* min: SCM min. (line 6) +* OPT_ARG: OPT_ARG. (line 6) +* OPT_NO_XLAT_CFG_NAMES: OPT_NO_XLAT_CFG_NAMES. (line 6) +* OPT_NO_XLAT_OPT_NAMES: OPT_NO_XLAT_OPT_NAMES. (line 6) +* OPT_VALUE_name: OPT_VALUE_name. (line 6) +* OPT_XLAT_CFG_NAMES: OPT_XLAT_CFG_NAMES. (line 6) +* OPT_XLAT_OPT_NAMES: OPT_XLAT_OPT_NAMES. (line 6) +* OPTION_CT: OPTION_CT. (line 6) +* optionFileLoad: libopts-optionFileLoad. + (line 6) +* optionFindNextValue: libopts-optionFindNextValue. + (line 6) +* optionFindValue: libopts-optionFindValue. + (line 6) +* optionFree: libopts-optionFree. (line 6) +* optionGetValue: libopts-optionGetValue. + (line 6) +* optionLoadLine: libopts-optionLoadLine. + (line 6) +* optionNextValue: libopts-optionNextValue. + (line 6) +* optionOnlyUsage: libopts-optionOnlyUsage. + (line 6) +* optionProcess: libopts-optionProcess. (line 6) +* optionRestore: libopts-optionRestore. (line 6) +* optionSaveFile: libopts-optionSaveFile. + (line 6) +* optionSaveState: libopts-optionSaveState. + (line 6) +* optionUnloadNested: libopts-optionUnloadNested. + (line 6) +* optionVersion: libopts-optionVersion. (line 6) +* out-delete: SCM out-delete. (line 6) +* out-depth: SCM out-depth. (line 6) +* out-emit-suspended: SCM out-emit-suspended. + (line 6) +* out-line: SCM out-line. (line 6) +* out-move: SCM out-move. (line 6) +* out-name: SCM out-name. (line 6) +* out-pop: SCM out-pop. (line 6) +* out-push-add: SCM out-push-add. (line 6) +* out-push-new: SCM out-push-new. (line 6) +* out-resume: SCM out-resume. (line 6) +* out-suspend: SCM out-suspend. (line 6) +* out-switch: SCM out-switch. (line 6) +* output-file-next-line: SCM output-file-next-line. + (line 6) +* pathfind: libopts-pathfind. (line 6) +* prefix: SCM prefix. (line 6) +* printf: SCM printf. (line 6) +* raw-shell-str: SCM raw-shell-str. (line 6) +* RESTART_OPT: RESTART_OPT. (line 6) +* RETURN: RETURN. (line 6) +* SELECT: SELECT. (line 6) +* set-option: SCM set-option. (line 6) +* set-writable: SCM set-writable. (line 6) +* SET_OPT_name: SET_OPT_name. (line 6) +* shell: SCM shell. (line 6) +* shell-str: SCM shell-str. (line 6) +* shellf: SCM shellf. (line 6) +* sprintf: SCM sprintf. (line 6) +* stack: SCM stack. (line 6) +* stack-join: SCM stack-join. (line 6) +* STACKCT_OPT: STACKCT_OPT. (line 6) +* STACKLST_OPT: STACKLST_OPT. (line 6) +* START_OPT: START_OPT. (line 6) +* STATE_OPT: STATE_OPT. (line 6) +* strequate: libopts-strequate. (line 6) +* streqvcmp: libopts-streqvcmp. (line 6) +* streqvmap: libopts-streqvmap. (line 6) +* string->c-name!: SCM string->c-name!. (line 6) +* string->camelcase: SCM string->camelcase. (line 6) +* string-capitalize: SCM string-capitalize. (line 6) +* string-capitalize!: SCM string-capitalize!. + (line 6) +* string-contains-eqv?: SCM *=*. (line 6) +* string-contains?: SCM *==*. (line 6) +* string-downcase: SCM string-downcase. (line 6) +* string-downcase!: SCM string-downcase!. (line 6) +* string-end-eqv-match?: SCM *~. (line 6) +* string-end-match?: SCM *~~. (line 6) +* string-ends-eqv?: SCM *=. (line 6) +* string-ends-with?: SCM *==. (line 6) +* string-equals?: SCM ==. (line 6) +* string-eqv-match?: SCM ~. (line 6) +* string-eqv?: SCM =. (line 6) +* string-has-eqv-match?: SCM *~*. (line 6) +* string-has-match?: SCM *~~*. (line 6) +* string-match?: SCM ~~. (line 6) +* string-start-eqv-match?: SCM ~*. (line 6) +* string-start-match?: SCM ~~*. (line 6) +* string-starts-eqv?: SCM =*. (line 6) +* string-starts-with?: SCM ==*. (line 6) +* string-substitute: SCM string-substitute. (line 6) +* string-table-add: SCM string-table-add. (line 6) +* string-table-add-ref: SCM string-table-add-ref. + (line 6) +* string-table-new: SCM string-table-new. (line 6) +* string-table-size: SCM string-table-size. (line 6) +* string-tr: SCM string-tr. (line 6) +* string-tr!: SCM string-tr!. (line 6) +* string-upcase: SCM string-upcase. (line 6) +* string-upcase!: SCM string-upcase!. (line 6) +* strneqvcmp: libopts-strneqvcmp. (line 6) +* strtransform: libopts-strtransform. (line 6) +* sub-shell-str: SCM sub-shell-str. (line 6) +* suffix: SCM suffix. (line 6) +* sum: SCM sum. (line 6) +* teOptIndex: teOptIndex. (line 6) +* time-string->number: SCM time-string->number. + (line 6) +* tpl-file: SCM tpl-file. (line 6) +* tpl-file-line: SCM tpl-file-line. (line 6) +* tpl-file-next-line: SCM tpl-file-next-line. + (line 6) +* UNKNOWN: UNKNOWN. (line 6) +* USAGE: USAGE. (line 6) +* VALUE_OPT_name: VALUE_OPT_name. (line 6) +* VERSION: VERSION. (line 6) +* version-compare: SCM version-compare. (line 6) +* WHICH_IDX_name: WHICH_IDX_name. (line 6) +* WHICH_OPT_name: WHICH_OPT_name. (line 6) +* WHILE: WHILE. (line 6) +* ~: SCM ~. (line 6) +* ~*: SCM ~*. (line 6) +* ~~: SCM ~~. (line 6) +* ~~*: SCM ~~*. (line 6) + + |