This is autogen.info, produced by makeinfo version 4.8 from autogen.texi. This manual is for GNU AutoGen version 5.9, updated July 2007. Copyright (C) 1992-2007 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.9. AutoGen copyright (C) 1992-2007 Bruce Korb AutoOpts copyright (C) 1992-2007 Bruce Korb snprintfv copyright (C) 1999-2000 Gary V. Vaughan AutoGen is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. AutoGen is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program. If not, see .  File: autogen.info, Node: libopts-ao_string_tokenize, Next: libopts-configFileLoad, Up: libopts procedures 7.6.28.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.28.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 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.28.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.28.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.28.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.28.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.28.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. 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.28.8 optionLoadLine ....................... process a string for an option name and value Usage: optionLoadLine( pOpts, pzLine ); Where the arguments are: Name Type Description ---- ---- ------------ pOpts `tOptions*' program options descriptor pzLine `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. 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.28.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.28.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.28.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.28.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.28.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. 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.28.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.28.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.28.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.28.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.28.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.28.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.28.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.28.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.28.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. none.  File: autogen.info, Node: option descriptor, Next: Using AutoOpts, Prev: AutoOpts API, Up: AutoOpts 7.7 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.8 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.8.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: myopts.c -I$prefix/include -L $prefix/lib -lopts These values can be derived from the "autoopts-config" script: myopts.c `autoopts-config cflags` `autoopts-config ldflags`  File: autogen.info, Node: binary not installed, Next: binary pre-installed, Prev: local use, Up: Using AutoOpts 7.8.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. Add the output from the following to your link command: autoopts-config static-libs  File: autogen.info, Node: binary pre-installed, Next: source pre-installed, Prev: binary not installed, Up: Using AutoOpts 7.8.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.8.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.8.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.9 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 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'. * Menu: * config example:: Config file only example  File: autogen.info, Node: loading rcfile, Next: saving rcfile, Up: Presetting Options 7.9.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.9.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.9.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 This will, by default, produce a sample file named, `sample-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-'. It will contain all of the program options not marked as `no-preset'. It will also include information about how they are handled and the text from the `doc' attribute.  File: autogen.info, Node: environrc, Prev: sample rcfile, Up: Presetting Options 7.9.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, Up: Presetting Options 7.9.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 #include #include #include #include #include int main( int argc, char** argv ) { char const* greeting = "Hello"; char const* greeted = "World"; const tOptionValue* 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 (for me): Hello, World! Buzz off, World! Hello, Bruce Korb!  File: autogen.info, Node: Config File Format, Next: shell options, Prev: Presetting Options, Up: AutoOpts 7.10 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 sections:: configuration file sections * config comments:: comments in the configuration file  File: autogen.info, Node: config name/string-value, Next: config integer-values, Up: Config File Format 7.10.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: value 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: `'. `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' Strings are formed and concatenated if, after stripping leading and trailing white space, the text begins and ends with either single (') or double (") quote characters. That processing is identical to the string formation used in AutoGen definition files (*note basic expression::), except that you may not use backquotes. And here is an example of an XML-styled value: "This is\n\tanother multi-line\n" "\tstring example." The string value associated with "name" will be exactly the text enclosed in quotes with the escaped 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.10.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: 1234 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 sections, Prev: config integer-values, Up: Config File Format 7.10.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: [[....]] The ellipsis may be filled with any legal configuration file name/value assignments.  File: autogen.info, Node: config sections, Next: config comments, Prev: config nested-values, Up: Config File Format 7.10.4 configuration file sections ---------------------------------- Configuration files may be sectioned. 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: `[PROG_NAME]' The file is partitioned by lines that contains an square open bracket (`['), the *upper-cased* c-variable-syntax program name and a square close bracket (`]'). For example, if the `prog-name' program had a sectioned configuration file, then a line containing exactly `[PROG_NAME]' would be processed. `' The `'), and unrecognized XML directives. # this is a comment  File: autogen.info, Node: shell options, Next: AutoInfo, Prev: Config File Format, Up: AutoOpts 7.11 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 global attribute: test-main [ = proc-to-call ] ; 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.11.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 test-errors.def cc -o test-errors -L -I \ -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 [ - [] | --[{=| }] ]... 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 -X no another Another option descrip - may appear up to 5 times -? no help Display usage information and exit -! no more-help Extended usage information passed thru pager -> opt save-opts Save the option state to a config file -< Str load-opts Load options from a config file - disabled as --no-load-opts - may appear multiple times Options are specified by doubled hyphens and their name or by a single hyphen and the flag character. Operands and options may be intermixed. They will be reordered. The following option preset mechanisms are supported: - reading file errorsRC Using the invocation, test-errors operand1 -s first operand2 -X -- -s operand3 you get the following output for your shell script to evaluate: OPTION_CT=4 export OPTION_CT TEST_ERRORS_SECOND='first' export TEST_ERRORS_SECOND TEST_ERRORS_ANOTHER=1 # 0x1 export TEST_ERRORS_ANOTHER set -- 'operand1' 'operand2' '-s' 'operand3' OPTION_CT=0  File: autogen.info, Node: script-parser, Prev: binary-parser, Up: shell options 7.11.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 [ - [] | --[{=| }] ]... 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 usage information and exit -! no more-help Extended usage information passed thru pager Options are specified by doubled hyphens and their name or by a single hyphen and the flag character. Note that `shell' is only useful if the output file does not already exist. If it does, then the shell name and optional first argument will be extracted from the script file. If the script file already exists and contains Automated Option Processing text, the second line of the file through the ending tag will be replaced by the newly generated text. The first `#!' line will be regenerated. please send bug reports to: autogen-users@lists.sourceforge.net = = = = = = = = This incarnation of genshell will produce a shell script to parse the options for getdefs: getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4 USAGE: getdefs [ [{=| }] ]... Arg Option-Name Description Str defs-to-get Regexp to look for after the "/*=" opt ordering Alphabetize or use named file Num first-index The first index to apply to groups Str input Input file to search for defs Str subblock subblock definition names Str listattr attribute with list of values 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 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 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''. please send bug reports to: autogen-users@lists.sourceforge.net Resulting in the following script: #! /bin/sh # # # # # # # # # # -- do not modify this marker -- # # DO NOT EDIT THIS SECTION OF ./.ag-dQd8p8/genshellopt.sh # # From here to the next `-- do not modify this marker --', # the text has been generated Saturday July 28, 2007 at 01:04:22 PM PDT # From the GETDEFS option definitions # GETDEFS_LONGUSAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4 USAGE: getdefs [ [{=| }] ]... Arg Option-Name Description Str defs-to-get Regexp to look for after the "/*=" opt ordering Alphabetize or use named file - disabled as --no-ordering - enabled by default Num first-index The first index to apply to groups Str input Input file to search for defs - may appear multiple times - default option for unnamed options Str subblock subblock definition names - may appear multiple times Str listattr attribute with list of values - may appear multiple times opt filelist Insert source file names into defs Definition insertion options Arg Option-Name Description 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 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 and help options: Arg Option-Name Description opt version Output version information and exit no help Display 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 `/*= \n'\'' and `=*/\n'\''. From that, this program creates a definition of the following form: #line nnn "source-file-name" entry_type = { name = entry_name; ... }; The ellipsis '\''...'\'' is filled in by text found between the two delimiters, with everything up through the first sequence of asterisks deleted on every line. There are two special ``entry types'\'''\'': * The entry_type enclosure and the name entry will be omitted and the ellipsis will become top-level definitions. -- The contents of the comment must be a single getdefs option. The option name must follow the double hyphen and its argument will be everything following the name. This is intended for use with the ``subblock'\'''\'' and ``listattr'\'''\'' options. please send bug reports to: autogen-users@lists.sourceforge.net' GETDEFS_USAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4 USAGE: getdefs [ [{=| }] ]... Arg Option-Name Description Str defs-to-get Regexp to look for after the "/*=" opt ordering Alphabetize or use named file Num first-index The first index to apply to groups Str input Input file to search for defs Str subblock subblock definition names Str listattr attribute with list of values 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 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 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'\'''\''. please send bug reports to: autogen-users@lists.sourceforge.net' GETDEFS_DEFS_TO_GET="${GETDEFS_DEFS_TO_GET}" GETDEFS_DEFS_TO_GET_set=false export GETDEFS_DEFS_TO_GET 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 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 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_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 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 ;; '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 ;; 'in' | \ 'inp' | \ 'inpu' | \ 'input' ) GETDEFS_INPUT_CT=`expr ${GETDEFS_INPUT_CT} + 1` OPT_ELEMENT="_${GETDEFS_INPUT_CT}" OPT_NAME='INPUT' 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 ;; '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 ;; '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.12 Automated Info Docs ======================== AutoOpts provides two templates for producing `.texi' documentation. `aginfo.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=' 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 `.menu' file in your document where you wish to reference the `invoking' chapter, section or subsection. 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.12.1 "invoking" info docs --------------------------- Using the option definitions for an AutoOpt client program, the `aginfo.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 -T aginfo.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.12.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 \ 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.13 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.13.1 command line man pages ----------------------------- Using the option definitions for an AutoOpts client program, the `agman1.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 -T agman1.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.13.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.14 Using getopt(3C) ===================== There is a template named, "`getopt.tpl'" that is distributed with AutoOpts. With it, you will have another source file generated for you that will utilize either the standard `getopt(3C)' or the GNU `getopt_long(3GNU)' function for parsing the command line arguments. 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: 1. You cannot automatically take advantage of environment variable options or rc (ini) files. 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. You must specify every option as "settable" because the emitted code depends upon the `SET_OPT_XXX' macros having been defined. 4. 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. 5. For the same reason, the traditional option parsing table code must be emitted before the `getopt.tpl' template gets expanded. 6. The usage text is, therefore, statically defined. 7. 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. This should minimally include the output from running the `autoopts-config cflags' script. `LDFLAGS' Any special flags required to link. This should minimally include the output from running the `autoopts-config ldflags' script. `CC' Set this 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 then invoke autogen twice, in the following order: autogen myprog-opts.def autogen -T getopt.tpl myprog-opts.def and you will have three new files: `myprog-opts.h', `myprog-opts.c', and `getopt-progname.c', where "progname" is the name specified with the global `prog-name' attribute in the option definition file. 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.  File: autogen.info, Node: i18n, Next: Naming Conflicts, Prev: getopt_long, Up: AutoOpts 7.15 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, 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.  File: autogen.info, Node: Naming Conflicts, Prev: i18n, Up: AutoOpts 7.16 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: 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 has no explanation. 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*, the aginfo template and the option descriptions for the `columns' program. It documents the columns usage text and option meanings. This software is released under the GNU General Public License. * Menu: * columns usage:: columns usage help (-?) * columns by-columns:: by-columns option * columns col-width:: col-width option (-w) * columns columns:: columns option (-c) * columns first-indent:: first-indent option * columns format:: format option (-f) * columns indent:: indent option (-I) * columns input:: input option (-i) * columns line-separation:: line-separation option * columns separation:: separation option (-S) * columns sort:: sort option (-s) * columns spread:: spread option * columns tab-width:: tab-width option * columns width:: width option (-W)  File: autogen.info, Node: columns usage, Next: columns by-columns, Up: columns Invocation 8.4.1 columns usage help (-?) ----------------------------- This is the automatically generated usage text for columns: columns (GNU AutoGen) - Columnize Input Text - Ver. 1.1 USAGE: columns [ - [] | --[{=| }] ]... Flg Arg Option-Name Description -W Num width Maximum Line Width -c Num columns Desired number of columns -w Num col-width Set width of each column Num spread maximum spread added to column width -I Str indent Line prefix or indentation Str first-indent First line prefix - requires these options: indent Num tab-width tab width -s opt sort Sort input text -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 no by-columns Print entries in column order -i Str input Input file (if not stdin) -v opt version Output version information and exit -? no help Display 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 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. please send bug reports to: autogen-users@lists.sourceforge.net  File: autogen.info, Node: columns width, Prev: columns tab-width, Up: columns Invocation 8.4.2 width option (-W) ----------------------- This is the "maximum line width" option. 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.  File: autogen.info, Node: columns columns, Next: columns first-indent, Prev: columns col-width, Up: columns Invocation 8.4.3 columns option (-c) ------------------------- This is the "desired number of columns" option. 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.  File: autogen.info, Node: columns col-width, Next: columns columns, Prev: columns by-columns, Up: columns Invocation 8.4.4 col-width option (-w) --------------------------- This is the "set width of each column" option. 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.  File: autogen.info, Node: columns spread, Next: columns tab-width, Prev: columns sort, Up: columns Invocation 8.4.5 spread option ------------------- This is the "maximum spread added to column width" option. 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.  File: autogen.info, Node: columns indent, Next: columns input, Prev: columns format, Up: columns Invocation 8.4.6 indent option (-I) ------------------------ This is the "line prefix or indentation" option. 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.  File: autogen.info, Node: columns first-indent, Next: columns format, Prev: columns columns, Up: columns Invocation 8.4.7 first-indent option ------------------------- This is the "first line prefix" option. 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.  File: autogen.info, Node: columns tab-width, Next: columns width, Prev: columns spread, Up: columns Invocation 8.4.8 tab-width option ---------------------- This is the "tab width" option. 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 sort, Next: columns spread, Prev: columns separation, Up: columns Invocation 8.4.9 sort option (-s) ---------------------- This is the "sort input text" option. 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 format, Next: columns indent, Prev: columns first-indent, Up: columns Invocation 8.4.10 format option (-f) ------------------------- This is the "formatting string for each input" option. 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.  File: autogen.info, Node: columns separation, Next: columns sort, Prev: columns line-separation, Up: columns Invocation 8.4.11 separation option (-S) ----------------------------- This is the "separation string - follows all but last" option. Use this option if, for example, you wish a comma to appear after each entry except the last.  File: autogen.info, Node: columns line-separation, Next: columns separation, Prev: columns input, Up: columns Invocation 8.4.12 line-separation option ----------------------------- This is the "string at end of all lines but last" option. Use this option if, for example, you wish a backslash to appear at the end of every line, except the last.  File: autogen.info, Node: columns by-columns, Next: columns col-width, Prev: columns usage, Up: columns Invocation 8.4.13 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.  File: autogen.info, Node: columns input, Next: columns line-separation, Prev: columns indent, Up: columns Invocation 8.4.14 input option (-i) ------------------------ This is the "input file (if not stdin)" option. 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: 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 `/*= \n' and `=*/\n'. From that, this program creates a definition of the following form: #line nnn "source-file-name" entry_type = { name = entry_name; ... }; The ellipsis "..." is filled in by text found between the two delimiters, using the following rules: 1. Each entry is located by the pattern "\n[^*\n]*\\*[ \t]*([a-z][a-z0-9_]*):". Fundamentally, it finds a line that, after the first asterisk on the line, contains whitespace then a name and is immediately followed by a colon. The name becomes the name of the attribute and what follows, up to the next attribute, is its value. 2. 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. 3. All the leading text on a line is stripped from the value. The leading text is everything before the first asterisk, the asterisk and all the whitespace characters that immediately follow it. 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 `' is followed by a comma, the word `ifdef' (or `ifndef') and a name `if_name', then the above entry will appear as: #ifdef if_name #line nnn "source-file-name" entry_type = { name = entry_name; ... }; #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*, the aginfo template and the option descriptions for the `getdefs' program. It documents the getdefs usage text and option meanings. This software is released under the GNU General Public License. * Menu: * getdefs usage:: getdefs usage help * getdefs agarg:: agarg option * getdefs assign:: assign option * getdefs autogen:: autogen option * getdefs base-name:: base-name option * getdefs common-assign:: common-assign option * getdefs copy:: copy option * getdefs defs-to-get:: defs-to-get option * getdefs filelist:: filelist option * getdefs first-index:: first-index option * getdefs input:: input option * getdefs linenum:: linenum option * getdefs listattr:: listattr option * getdefs ordering:: ordering option * getdefs output:: output option * getdefs srcfile:: srcfile option * getdefs subblock:: subblock option * getdefs template:: template option  File: autogen.info, Node: getdefs usage, Next: getdefs agarg, Up: getdefs Invocation 8.5.1 getdefs usage help ------------------------ This is the automatically generated usage text for getdefs: getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.4 USAGE: getdefs [ [{=| }] ]... Arg Option-Name Description Str defs-to-get Regexp to look for after the "/*=" opt ordering Alphabetize or use named file - disabled as --no-ordering - enabled by default Num first-index The first index to apply to groups Str input Input file to search for defs - may appear multiple times - default option for unnamed options Str subblock subblock definition names - may appear multiple times Str listattr attribute with list of values - may appear multiple times opt filelist Insert source file names into defs Definition insertion options Arg Option-Name Description 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 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 and help options: Arg Option-Name Description opt version Output version information and exit no help Display 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 `/*= \n' and `=*/\n'. From that, this program creates a definition of the following form: #line nnn "source-file-name" entry_type = { name = entry_name; ... }; The ellipsis '...' is filled in by text found between the two delimiters, with everything up through the first sequence of asterisks deleted on every line. There are two special ``entry types'': * The entry_type enclosure and the name entry will be omitted and the ellipsis will become top-level definitions. -- The contents of the comment must be a single getdefs option. The option name must follow the double hyphen and its argument will be everything following the name. This is intended for use with the ``subblock'' and ``listattr'' options. please send bug reports to: autogen-users@lists.sourceforge.net  File: autogen.info, Node: getdefs defs-to-get, Next: getdefs filelist, Prev: getdefs copy, Up: getdefs Invocation 8.5.2 defs-to-get option ------------------------ This is the "regexp to look for after the "/*="" option. 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 `/*='.  File: autogen.info, Node: getdefs ordering, Next: getdefs output, Prev: getdefs listattr, Up: getdefs Invocation 8.5.3 ordering option --------------------- This is the "alphabetize or use named file" option. 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=' if chronological order is important. getdefs will maintain the text content of `file-name'. `file-name' need not exist.  File: autogen.info, Node: getdefs first-index, Next: getdefs input, Prev: getdefs filelist, Up: getdefs Invocation 8.5.4 first-index option ------------------------ This is the "the first index to apply to groups" option. 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 input, Next: getdefs linenum, Prev: getdefs first-index, Up: getdefs Invocation 8.5.5 input option ------------------ This is the "input file to search for defs" option. 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 subblock, Next: getdefs template, Prev: getdefs srcfile, Up: getdefs Invocation 8.5.6 subblock option --------------------- This is the "subblock definition names" option. 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"; };'.  File: autogen.info, Node: getdefs listattr, Next: getdefs ordering, Prev: getdefs linenum, Up: getdefs Invocation 8.5.7 listattr option --------------------- This is the "attribute with list of values" option. 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 filelist, Next: getdefs first-index, Prev: getdefs defs-to-get, Up: getdefs Invocation 8.5.8 filelist option --------------------- This is the "insert source file names into defs" option. 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.  File: autogen.info, Node: getdefs assign, Next: getdefs autogen, Prev: getdefs agarg, Up: getdefs Invocation 8.5.9 assign option ------------------- This is the "global assignments" option. 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.  File: autogen.info, Node: getdefs common-assign, Next: getdefs copy, Prev: getdefs base-name, Up: getdefs Invocation 8.5.10 common-assign option --------------------------- This is the "assignments common to all blocks" option. 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.  File: autogen.info, Node: getdefs copy, Next: getdefs defs-to-get, Prev: getdefs common-assign, Up: getdefs Invocation 8.5.11 copy option ------------------ This is the "file(s) to copy into definitions" option. 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.  File: autogen.info, Node: getdefs srcfile, Next: getdefs subblock, Prev: getdefs output, Up: getdefs Invocation 8.5.12 srcfile option --------------------- This is the "insert source file name into each def" option. 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.  File: autogen.info, Node: getdefs linenum, Next: getdefs listattr, Prev: getdefs input, Up: getdefs Invocation 8.5.13 linenum option --------------------- This is the "insert source line number into each def" option. 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 output, Next: getdefs srcfile, Prev: getdefs ordering, Up: getdefs Invocation 8.5.14 output option -------------------- This is the "output file to open" option. 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.  File: autogen.info, Node: getdefs autogen, Next: getdefs base-name, Prev: getdefs assign, Up: getdefs Invocation 8.5.15 autogen option --------------------- This is the "invoke autogen with defs" option. 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.  File: autogen.info, Node: getdefs template, Prev: getdefs subblock, Up: getdefs Invocation 8.5.16 template option ---------------------- This is the "template name" option. Specifies the template name to be used for generating the final output.  File: autogen.info, Node: getdefs agarg, Next: getdefs assign, Prev: getdefs usage, Up: getdefs Invocation 8.5.17 agarg option ------------------- This is the "autogen argument" option. 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.  File: autogen.info, Node: getdefs base-name, Next: getdefs common-assign, Prev: getdefs autogen, Up: getdefs Invocation 8.5.18 base-name option ----------------------- This is the "base name for output file(s)" option. 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: 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-1 grumble, grumble, grumble. 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*, the aginfo template and the option descriptions for the `xml2ag' program. It documents the xml2ag usage text and option meanings. This software is released under the GNU General Public License. * Menu: * xml2ag usage:: xml2ag usage help (-?) * xml2ag base-name:: base-name option (-b) * xml2ag define:: define option (-D) * xml2ag definitions:: definitions option * xml2ag equate:: equate option * xml2ag lib-template:: lib-template option (-l) * xml2ag load-functions:: load-functions option (-F) * xml2ag load-scheme:: load-scheme option (-S) * xml2ag loop-limit:: loop-limit option * xml2ag no-fmemopen:: no-fmemopen option (-m) * xml2ag output:: output option (-O) * xml2ag override-tpl:: override-tpl option (-T) * xml2ag select-suffix:: select-suffix option (-o) * xml2ag show-defs:: show-defs option * xml2ag skip-suffix:: skip-suffix option (-s) * xml2ag source-time:: source-time option * xml2ag templ-dirs:: templ-dirs option (-L) * xml2ag timeout:: timeout option (-t) * xml2ag trace-out:: trace-out option * xml2ag trace:: trace option * xml2ag undefine:: undefine option (-U) * xml2ag writable:: writable option  File: autogen.info, Node: xml2ag usage, Next: xml2ag base-name, Up: xml2ag Invocation 8.6.1 xml2ag usage help (-?) ---------------------------- This is the automatically generated usage text for xml2ag: xml2ag (GNU AutoGen) - XML to AutoGen Definiton Converter - Ver. 5.9.2 USAGE: xml2ag [ - [] | --[{=| }] ]... [ ] Flg Arg Option-Name Description -O Str output Output file in lieu of AutoGen processing -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 -b Str base-name Base name for output file(s) Str definitions Definitions input file -S Str load-scheme Scheme code file to load -F Str load-functions Load scheme function library -s Str skip-suffix Omit the file with this suffix - may appear multiple times -o opt select-suffix specify this output suffix - may appear multiple times no source-time set mod times to latest source -m no no-fmemopen Do not use in-mem streams Str equate characters considered equivalent no writable Allow output files to be writable - disabled as --not-writable Num loop-limit Limit on increment loops it must lie in one of the ranges: -1 exactly, or 1 to 16777216 -t Num timeout Time limit for servers it must lie 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 -D Str define name to add to definition list - may appear multiple times -U Str undefine definition list removal pattern - an alternate for define -v opt version Output version information and exit -? no help Display 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 server-shell templates block-macros expressions everything The template will be derived from either: * the ``--override-tpl'' command line option * a top level XML attribute named, "template" The ``base-name'' for the output will similarly be either: * the ``--base-name'' command line option * the base name of the .xml file please send bug reports to: autogen-users@lists.sourceforge.net  File: autogen.info, Node: xml2ag output, Next: xml2ag override-tpl, Prev: xml2ag no-fmemopen, Up: xml2ag Invocation 8.6.2 output option (-O) ------------------------ This is the "output file in lieu of autogen processing" option. 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 templ-dirs, Next: xml2ag timeout, Prev: xml2ag source-time, Up: xml2ag Invocation 8.6.3 templ-dirs option (-L) ---------------------------- This is the "template search directory list" option. This option has some usage constraints. It: * may appear an unlimited number of times. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag override-tpl, Next: xml2ag select-suffix, Prev: xml2ag output, Up: xml2ag Invocation 8.6.4 override-tpl option (-T) ------------------------------ This is the "override template file" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag lib-template, Next: xml2ag load-functions, Prev: xml2ag equate, Up: xml2ag Invocation 8.6.5 lib-template option (-l) ------------------------------ This is the "library template file" option. This option has some usage constraints. It: * may appear an unlimited number of times. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag base-name, Next: xml2ag define, Prev: xml2ag usage, Up: xml2ag Invocation 8.6.6 base-name option (-b) --------------------------- This is the "base name for output file(s)" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag definitions, Next: xml2ag equate, Prev: xml2ag define, Up: xml2ag Invocation 8.6.7 definitions option ------------------------ This is the "definitions input file" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag load-scheme, Next: xml2ag loop-limit, Prev: xml2ag load-functions, Up: xml2ag Invocation 8.6.8 load-scheme option (-S) ----------------------------- This is the "scheme code file to load" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag load-functions, Next: xml2ag load-scheme, Prev: xml2ag lib-template, Up: xml2ag Invocation 8.6.9 load-functions option (-F) -------------------------------- This is the "load scheme function library" option. This option has some usage constraints. It: * must be compiled in by defining `HAVE_DLOPEN' during the compilation. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag skip-suffix, Next: xml2ag source-time, Prev: xml2ag show-defs, Up: xml2ag Invocation 8.6.10 skip-suffix option (-s) ------------------------------ This is the "omit the file with this suffix" option. This option has some usage constraints. It: * may appear an unlimited number of times. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag select-suffix, Next: xml2ag show-defs, Prev: xml2ag override-tpl, Up: xml2ag Invocation 8.6.11 select-suffix option (-o) -------------------------------- This is the "specify this output suffix" option. This option has some usage constraints. It: * may appear an unlimited number of times. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag source-time, Next: xml2ag templ-dirs, Prev: xml2ag skip-suffix, Up: xml2ag Invocation 8.6.12 source-time option ------------------------- This is the "set mod times to latest source" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag no-fmemopen, Next: xml2ag output, Prev: xml2ag loop-limit, Up: xml2ag Invocation 8.6.13 no-fmemopen option (-m) ------------------------------ This is the "do not use in-mem streams" option. This option has some usage constraints. It: * must be compiled in by defining `ENABLE_FMEMOPEN' during the compilation. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag equate, Next: xml2ag lib-template, Prev: xml2ag definitions, Up: xml2ag Invocation 8.6.14 equate option -------------------- This is the "characters considered equivalent" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag writable, Prev: xml2ag undefine, Up: xml2ag Invocation 8.6.15 writable option ---------------------- This is the "allow output files to be writable" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag loop-limit, Next: xml2ag no-fmemopen, Prev: xml2ag load-scheme, Up: xml2ag Invocation 8.6.16 loop-limit option ------------------------ This is the "limit on increment loops" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag timeout, Next: xml2ag trace-out, Prev: xml2ag templ-dirs, Up: xml2ag Invocation 8.6.17 timeout option (-t) -------------------------- This is the "time limit for servers" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag trace, Next: xml2ag undefine, Prev: xml2ag trace-out, Up: xml2ag Invocation 8.6.18 trace option ------------------- This is the "tracing level of detail" option. 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 server-shell templates block-macros expressions everything Pass-through AutoGen argument  File: autogen.info, Node: xml2ag trace-out, Next: xml2ag trace, Prev: xml2ag timeout, Up: xml2ag Invocation 8.6.19 trace-out option ----------------------- This is the "tracing output file or filter" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag show-defs, Next: xml2ag skip-suffix, Prev: xml2ag select-suffix, Up: xml2ag Invocation 8.6.20 show-defs option ----------------------- This is the "show the definition tree" option. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag define, Next: xml2ag definitions, Prev: xml2ag base-name, Up: xml2ag Invocation 8.6.21 define option (-D) ------------------------- This is the "name to add to definition list" option. This option has some usage constraints. It: * may appear an unlimited number of times. Pass-through AutoGen argument  File: autogen.info, Node: xml2ag undefine, Next: xml2ag writable, Prev: xml2ag trace, Up: xml2ag Invocation 8.6.22 undefine option (-U) --------------------------- This is the "definition list removal pattern" option. This option has some usage constraints. It: * may appear an unlimited number of times. Pass-through AutoGen argument  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) 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 ************* [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) * .def file: Definitions File. (line 6) * .tpl file: Template File. (line 6) * allow-errors: program attributes. (line 32) * Alternate Definition: Alternate Definition. (line 6) * arg-default: Option Arguments. (line 141) * arg-optional: Option Arguments. (line 130) * arg-range: Option Arguments. (line 157) * arg-type: Option Arguments. (line 23) * argument: program attributes. (line 21) * 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 usage: autogen usage. (line 6) * autogen-base-name: autogen base-name. (line 6) * autogen-define: autogen define. (line 6) * autogen-definitions: autogen definitions. (line 6) * autogen-equate: autogen equate. (line 6) * autogen-lib-template: autogen lib-template. (line 6) * autogen-load-functions: autogen load-functions. (line 6) * autogen-load-scheme: autogen load-scheme. (line 6) * autogen-loop-limit: autogen loop-limit. (line 6) * autogen-no-fmemopen: autogen no-fmemopen. (line 6) * autogen-override-tpl: autogen override-tpl. (line 6) * autogen-select-suffix: autogen select-suffix. (line 6) * autogen-show-defs: autogen show-defs. (line 6) * autogen-skip-suffix: autogen skip-suffix. (line 6) * autogen-source-time: autogen source-time. (line 6) * autogen-templ-dirs: autogen templ-dirs. (line 6) * autogen-timeout: autogen timeout. (line 6) * autogen-trace: autogen trace. (line 6) * autogen-trace-out: autogen trace-out. (line 6) * autogen-undefine: autogen undefine. (line 6) * autogen-writable: autogen writable. (line 6) * AutoInfo: AutoInfo. (line 6) * AutoMan pages: AutoMan pages. (line 6) * automatic options: automatic options. (line 6) * autoopts: AutoOpts. (line 6) * AutoOpts API: AutoOpts API. (line 6) * AutoXDR: AutoXDR. (line 6) * call-proc: Option Argument Handling. (line 39) * Columnize Input Text: columns Invocation. (line 6) * columns: columns Invocation. (line 6) * columns usage: columns usage. (line 6) * columns-by-columns: columns by-columns. (line 6) * columns-col-width: columns col-width. (line 6) * columns-columns: columns columns. (line 6) * columns-first-indent: columns first-indent. (line 6) * columns-format: columns format. (line 6) * columns-indent: columns indent. (line 6) * columns-input: columns input. (line 6) * columns-line-separation: columns line-separation. (line 6) * columns-separation: columns separation. (line 6) * columns-sort: columns sort. (line 6) * columns-spread: columns spread. (line 6) * columns-tab-width: columns tab-width. (line 6) * columns-width: columns width. (line 6) * comments: Comments. (line 6) * Common Option Attributes: Common Attributes. (line 6) * compound definitions: Definitions. (line 35) * concat-string: concat-string. (line 6) * conditional emit <1>: WHILE. (line 6) * conditional emit: IF. (line 6) * config-header: program attributes. (line 38) * 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 49) * configuration file <3>: Special Option Handling. (line 9) * configuration file: program attributes. (line 39) * Configuration File example: config example. (line 6) * configuring: configuring. (line 6) * copyright: information attributes. (line 9) * default: Option Arguments. (line 145) * 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) * descrip: Required Attributes. (line 35) * design goals: Generalities. (line 11) * detail: information attributes. (line 41) * directives: Directives. (line 6) * disable: Common Attributes. (line 32) * diversion: output controls. (line 6) * documentation: Special Option Handling. (line 67) * documentation attributes: documentation attributes. (line 6) * Dynamic Definition Text: Dynamic Text. (line 6) * elif directive: Directives. (line 53) * else directive: Directives. (line 57) * enable: Common Attributes. (line 28) * enabled: Common Attributes. (line 36) * endif directive: Directives. (line 62) * endmac directive: Directives. (line 66) * endshell directive: Directives. (line 70) * environrc <1>: environrc. (line 6) * environrc: program attributes. (line 43) * equivalence: Special Option Handling. (line 20) * error directive: Directives. (line 74) * example, simple AutoGen: Example Usage. (line 6) * example, simple AutoOpts: Quick Start. (line 6) * explain: information attributes. (line 45) * export: program attributes. (line 49) * expression syntax: expression syntax. (line 6) * extract-code: Option Argument Handling. (line 31) * FDL, GNU Free Documentation License: Copying This Manual. (line 9) * features: Features. (line 6) * finite state machine: AutoFSM. (line 6) * flag-code: Option Argument Handling. (line 18) * flag-proc: Option Argument Handling. (line 46) * 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) * full-usage: program attributes. (line 57) * futures: Future. (line 6) * getdefs: getdefs Invocation. (line 6) * getdefs usage: getdefs usage. (line 6) * getdefs-agarg: getdefs agarg. (line 6) * getdefs-assign: getdefs assign. (line 6) * getdefs-autogen: getdefs autogen. (line 6) * getdefs-base-name: getdefs base-name. (line 6) * getdefs-common-assign: getdefs common-assign. (line 6) * getdefs-copy: getdefs copy. (line 6) * getdefs-defs-to-get: getdefs defs-to-get. (line 6) * getdefs-filelist: getdefs filelist. (line 6) * getdefs-first-index: getdefs first-index. (line 6) * getdefs-input: getdefs input. (line 6) * getdefs-linenum: getdefs linenum. (line 6) * getdefs-listattr: getdefs listattr. (line 6) * getdefs-ordering: getdefs ordering. (line 6) * getdefs-output: getdefs output. (line 6) * getdefs-srcfile: getdefs srcfile. (line 6) * getdefs-subblock: getdefs subblock. (line 6) * getdefs-template: getdefs template. (line 6) * getopt_long: getopt_long. (line 6) * gnu-usage: information attributes. (line 84) * guard-option-names: program attributes. (line 80) * here-string: here-string. (line 6) * homerc: program attributes. (line 111) * identification: Identification. (line 6) * if directive: Directives. (line 78) * if test: IF. (line 6) * ifdef directive: Directives. (line 82) * ifndef directive: Directives. (line 88) * immed-disable: Immediate Action. (line 30) * immediate: Immediate Action. (line 23) * immediate action: Immediate Action. (line 6) * include: program attributes. (line 120) * include directive: Directives. (line 93) * information attributes: information attributes. (line 6) * Installing: installing. (line 6) * Internationalizing AutoOpts: i18n. (line 6) * Introduction: Introduction. (line 6) * keyword: Option Arguments. (line 120) * library attributes: library attributes. (line 6) * Licensing: Licensing. (line 6) * line directive: Directives. (line 99) * long-opts: program attributes. (line 124) * 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) * man-doc: documentation attributes. (line 42) * max: Common Attributes. (line 13) * min: Common Attributes. (line 19) * must-set: Common Attributes. (line 24) * name: Required Attributes. (line 8) * named option mode: program attributes. (line 124) * Naming Conflicts: Naming Conflicts. (line 6) * naming values: naming values. (line 6) * native macros: native macros. (line 6) * no-preset: Special Option Handling. (line 8) * 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 argument name: documentation attributes. (line 26) * 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 documentation: documentation attributes. (line 11) * Option Processing Data: Option Processing Data. (line 6) * optOccCt: Option Processing Data. (line 24) * opts-ptr: information attributes. (line 63) * optValue: Option Processing Data. (line 12) * package: information attributes. (line 49) * predefines: Predefines. (line 6) * prefix: program attributes. (line 142) * preserve-case: information attributes. (line 55) * prog-desc: information attributes. (line 62) * prog-info-descrip: documentation attributes. (line 32) * prog-man-descrip: documentation attributes. (line 32) * prog-name: program attributes. (line 14) * prog-title: program attributes. (line 18) * 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 <2>: loading rcfile. (line 6) * rcfile: program attributes. (line 147) * Redirecting Output: output controls. (line 6) * remote procedure call: AutoXDR. (line 6) * reorder-args: information attributes. (line 93) * Required Attributes: Required Attributes. (line 6) * RPC: AutoXDR. (line 6) * rpcgen: AutoXDR. (line 6) * sample rcfile: sample rcfile. (line 6) * sectioned config file: config sections. (line 6) * settable: Special Option Handling. (line 12) * 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) * short-usage: program attributes. (line 152) * Signal Names: signal names. (line 6) * simple definitions: Definitions. (line 35) * Special Option Handling: Special Option Handling. (line 6) * stack-arg: Option Argument Handling. (line 50) * 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) * unstack-arg: Option Argument Handling. (line 62) * usage: information attributes. (line 76) * using AutoOpts: Using AutoOpts. (line 6) * value: Common Attributes. (line 9) * version: program attributes. (line 157) * while test: WHILE. (line 6) * XDR: AutoXDR. (line 6) * XML to AutoGen Definiton Converter: xml2ag Invocation. (line 6) * xml2ag: xml2ag Invocation. (line 6) * xml2ag usage: xml2ag usage. (line 6) * xml2ag-base-name: xml2ag base-name. (line 6) * xml2ag-define: xml2ag define. (line 6) * xml2ag-definitions: xml2ag definitions. (line 6) * xml2ag-equate: xml2ag equate. (line 6) * xml2ag-lib-template: xml2ag lib-template. (line 6) * xml2ag-load-functions: xml2ag load-functions. (line 6) * xml2ag-load-scheme: xml2ag load-scheme. (line 6) * xml2ag-loop-limit: xml2ag loop-limit. (line 6) * xml2ag-no-fmemopen: xml2ag no-fmemopen. (line 6) * xml2ag-output: xml2ag output. (line 6) * xml2ag-override-tpl: xml2ag override-tpl. (line 6) * xml2ag-select-suffix: xml2ag select-suffix. (line 6) * xml2ag-show-defs: xml2ag show-defs. (line 6) * xml2ag-skip-suffix: xml2ag skip-suffix. (line 6) * xml2ag-source-time: xml2ag source-time. (line 6) * xml2ag-templ-dirs: xml2ag templ-dirs. (line 6) * xml2ag-timeout: xml2ag timeout. (line 6) * xml2ag-trace: xml2ag trace. (line 6) * xml2ag-trace-out: xml2ag trace-out. (line 6) * xml2ag-undefine: xml2ag undefine. (line 6) * xml2ag-writable: xml2ag writable. (line 6)  File: autogen.info, Node: Function Index, Prev: Concept Index, Up: Top Function Index ************** [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) * ao_string_tokenize: libopts-ao_string_tokenize. (line 6) * autogen-version: SCM autogen-version. (line 6) * base-name: SCM base-name. (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) * count: SCM count. (line 6) * COUNT_OPT: COUNT_OPT. (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) * 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) * low-lim: SCM low-lim. (line 6) * make-gperf: SCM make-gperf. (line 6) * make-header-guard: SCM make-header-guard. (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_VALUE_name: OPT_VALUE_name. (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-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) * 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) * 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) * 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-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) * tpl-file: SCM tpl-file. (line 6) * tpl-file-line: SCM tpl-file-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)