diff options
Diffstat (limited to 'doc/autogen-texi.txt')
| -rw-r--r-- | doc/autogen-texi.txt | 5768 |
1 files changed, 5768 insertions, 0 deletions
diff --git a/doc/autogen-texi.txt b/doc/autogen-texi.txt new file mode 100644 index 0000000..2df421c --- /dev/null +++ b/doc/autogen-texi.txt @@ -0,0 +1,5768 @@ +@c -*- Mode: texinfo -*- +@setfilename autogen.info +@ignore +This file serves two purposes: + +1) it provides that stupid (at)setfilename so that automake will + deign to produce the documentation + +2) a text repository for documentation that would make the doc + template more confusing. + + + This file is part of AutoGen. + AutoGen Copyright (c) 1992-2012 by Bruce Korb - all rights reserved + + AutoGen is free software: you can redistribute it and/or modify it + under the terms of the GNU General Public License as published by the + Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + AutoGen is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. + See the GNU General Public License for more details. + + You should have received a copy of the GNU General Public License along + with this program. If not, see <http://www.gnu.org/licenses/>. +@end ignore + +@ignore +START == COMMENTS == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +Resume input from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node Predefines +@section Pre-defined Names +@cindex predefines + +When AutoGen starts, it tries to determine several names from the +operating environment and put them into environment variables for use in +both @code{#ifdef} tests in the definitions files and in shell scripts +with environment variable tests. @code{__autogen__} is always defined. +For other names, AutoGen will first try to use the POSIX version of the +@code{sysinfo(2)} system call. Failing that, it will try for the POSIX +@code{uname(2)} call. If neither is available, then only +"@code{__autogen__}" will be inserted into the environment. +In all cases, the associated names are converted to lower case, surrounded +by doubled underscores and non-symbol characters are replaced with +underscores. + +With Solaris on a sparc platform, @code{sysinfo(2)} is available. +The following strings are used: + +@itemize @bullet +@item +@code{SI_SYSNAME} (e.g., "__sunos__") +@item +@code{SI_HOSTNAME} (e.g., "__ellen__") +@item +@code{SI_ARCHITECTURE} (e.g., "__sparc__") +@item +@code{SI_HW_PROVIDER} (e.g., "__sun_microsystems__") +@item +@code{SI_PLATFORM} (e.g., "__sun_ultra_5_10__") +@item +@code{SI_MACHINE} (e.g., "__sun4u__") +@end itemize + +For Linux and other operating systems that only support the +@code{uname(2)} call, AutoGen will use these values: + +@itemize @bullet +@item +@code{sysname} (e.g., "__linux__") +@item +@code{machine} (e.g., "__i586__") +@item +@code{nodename} (e.g., "__bach__") +@end itemize + +By testing these pre-defines in my definitions, you can select +pieces of the definitions without resorting to writing shell +scripts that parse the output of @code{uname(1)}. You can also +segregate real C code from autogen definitions by testing for +"@code{__autogen__}". + +@example +#ifdef __bach__ + location = home; +#else + location = work; +#endif +@end example + +@c === SECTION MARKER + +@node Comments +@section Commenting Your Definitions +@cindex comments + +The definitions file may contain C and C++ style comments. + +@example +/* + * This is a comment. It continues for several lines and closes + * when the characters '*' and '/' appear together. + */ +// this comment is a single line comment +@end example + +@c === SECTION MARKER + +@node Example +@section What it all looks like. + +@noindent +This is an extended example: + +@example +autogen definitions @samp{template-name}; +/* + * This is a comment that describes what these + * definitions are all about. + */ +global = "value for a global text definition."; + +/* + * Include a standard set of definitions + */ +#include standards.def + +a_block = @{ + a_field; + a_subblock = @{ + sub_name = first; + sub_field = "sub value."; + @}; + +#ifdef FEATURE + a_subblock = @{ + sub_name = second; + @}; +#endif + +@}; +@end example + +@ignore +END == COMMENTS == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == TEMPLATE == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node Alternate Definition +@section Alternate Definition Forms +@cindex Alternate Definition + +There are several methods for supplying data values for templates. + +@table @samp +@item no definitions +It is entirely possible to write a template that does not depend upon +external definitions. Such a template would likely have an unvarying +output, but be convenient nonetheless because of an external library +of either AutoGen or Scheme functions, or both. This can be accommodated +by providing the @code{--override-tpl} and @code{--no-definitions} +options on the command line. @xref{autogen Invocation}. + +@item CGI +AutoGen behaves as a CGI server if the definitions input is from stdin +and the environment variable @code{REQUEST_METHOD} is defined +and set to either "GET" or "POST", @xref{AutoGen CGI}. Obviously, +all the values are constrained to strings because there is no way +to represent nested values. + +@item XML +AutoGen comes with a program named, @code{xml2ag}. Its output can +either be redirected to a file for later use, or the program can +be used as an AutoGen wrapper. @xref{xml2ag Invocation}. + +The introductory template example (@pxref{Example Usage}) can be rewritten +in XML as follows: + +@example +<EXAMPLE template="list.tpl"> +<LIST list_element="alpha" + list_info="some alpha stuff"/> +<LIST list_info="more beta stuff" + list_element="beta"/> +<LIST list_element="omega" + list_info="final omega stuff"/> +</EXAMPLE> +@end example + +A more XML-normal form might look like this: +@example +<EXAMPLE template="list.tpl"> +<LIST list_element="alpha">some alpha stuff</LIST> +<LIST list_element="beta" >more beta stuff</LIST> +<LIST list_element="omega">final omega stuff</LIST> +</EXAMPLE> +@end example +@noindent +but you would have to change the template @code{list_info} references +into @code{text} references. + +@item standard AutoGen definitions +Of course. :-) + +@end table + +@ignore +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +@end ignore +@page +@node Template File +@chapter Template File +@cindex template file +@cindex .tpl file + +The AutoGen template file defines the content of the output text. +It is composed of two parts. The first part consists of a pseudo +macro invocation and commentary. It is followed by the template proper. + +@cindex pseudo macro +@cindex macro, pseudo +This pseudo macro is special. It is used to identify the file as a +AutoGen template file, fixing the starting and ending marks for +the macro invocations in the rest of the file, specifying the list +of suffixes to be generated by the template and, optionally, the +shell to use for processing shell commands embedded in the template. + +AutoGen-ing a file consists of copying text from the template to the +output file until a start macro marker is found. The text from the +start marker to the end marker constitutes the macro text. AutoGen +macros may cause sections of the template to be skipped or processed +several times. The process continues until the end of the template is +reached. The process is repeated once for each suffix specified in the +pseudo macro. + +This chapter describes the format of the AutoGen template macros +and the usage of the AutoGen native macros. Users may augment +these by defining their own macros, @xref{DEFINE}. + +@menu +* pseudo macro:: Format of the Pseudo Macro +* naming values:: Naming a value +* expression syntax:: Macro Expression Syntax +* AutoGen Functions:: AutoGen Scheme Functions +* Common Functions:: Common Scheme Functions +* native macros:: AutoGen Native Macros +* output controls:: Redirecting Output +@end menu + +@c === SECTION MARKER + +@node pseudo macro +@section Format of the Pseudo Macro +@cindex pseudo macro + +The pseudo macro is used to tell AutoGen how to process a template. +It tells autogen: + +@enumerate +@item +The start macro marker. It consists of punctuation characters used to +demarcate the start of a macro. It may be up to seven characters long and +must be the first non-whitespace characters in the file. + +@noindent +It is generally a good idea to use some sort of opening +bracket in the starting macro and closing bracket in the ending +macro (e.g. @code{@{}, @code{(}, @code{[}, or even @code{<} +in the starting macro). It helps both visually and with editors +capable of finding a balancing parenthesis. + +@item +That start marker must be immediately followed by the identifier strings +"AutoGen5" and then "template", though capitalization is not important. +@end enumerate + +@noindent +The next several components may be intermingled: + +@enumerate 3 +@item +Zero, one or more suffix specifications tell AutoGen how many times to +process the template file. No suffix specifications mean that it is to +be processed once and that the generated text is to be written to +@file{stdout}. The current suffix for each pass can be determined with the +@code{(suffix)} scheme function (@pxref{SCM suffix}). + +The suffix specification consists of a sequence of POSIX compliant file name +characters and, optionally, an equal sign and a file name formatting +specification. That specification may be either an ordinary sequence of +file name characters with zero, one or two "%s" formatting sequences in it, +or else it may be a Scheme expression that, when evaluated, produces such a +string. The Scheme result may not be empty. The two string arguments +allowed for that string are the base name of the definition file, and the +current suffix (that being the text to the left of the equal sign). (Note: +"POSIX compliant file name characters" consist of alphanumerics plus the +period (@code{.}), hyphen (@code{-}) and underscore (@code{_}) characters.) + +If the suffix begins with one of these three latter characters and +a formatting string is not specified, then that character is presumed to +be the suffix separator. Otherwise, without a specified format string, +a single period will separate the suffix from the base name in constructing +the output file name. + +@item +Shell specification: to specify that the template was written expecting a +particular shell to run the shell commands. By default, the shell used is the +autoconf-ed @code{CONFIG_SHELL}. This will usually be @file{/bin/sh}. The +shell is specified by a hash mark (@code{#}) followed by an exclamation mark +(@code{!}) followed by a full-path file name (e.g. @file{/usr/xpg4/bin/sh} on +Solaris): +@example +[= Autogen5 Template c +#!/usr/xpg4/bin/sh +=] +@end example + +@item +Comments: blank lines, lines starting with a hash mark (@code{#}) and not +specifying a shell, and edit mode markers (text between pairs of @code{-*-} +strings) are all treated as comments. + +@item +Some scheme expressions may be inserted in order to make configuration +changes before template processing begins. ``@i{before template +processing begins}'' means that there is no current output file, no current +suffix and, basically, none of the AutoGen specific functions +(@pxref{AutoGen Functions}) may be invoked. + +The scheme expression can also be used, for example, to save a pre-existing +output file for later text extraction (@pxref{SCM extract}). + +@example +(shellf "mv -f %1$s.c %1$s.sav" (base-name)) +@end example +@end enumerate + +@noindent +After these must come the end macro marker: + +@enumerate 6 +@item +The punctuation characters used to demarcate the end of a macro. +Like the start marker, it must consist of seven or fewer punctuation +characters. +@end enumerate + +The ending macro marker has a few constraints on its content. Some of +them are just advisory, though. There is no special check for advisory +restrictions. + +@itemize @bullet +@item +It must not begin with a POSIX file name character (hyphen @code{-}, +underscore @code{_} or period @code{.}), the backslash (@code{\}) or +open parenthesis (@code{(}). These are used to identify a suffix +specification, indicate Scheme code and trim white space. + +@item +If it begins with an equal sign, then it +must be separated from any suffix specification by white space. + +@item +The closing marker may not begin with an open parenthesis, as that is used +to enclose a scheme expression. + +@item +It cannot begin with a backslash, as that is used to indicate white +space trimming after the end macro mark. If, in the body of the template, +you put the backslash character (@code{\}) before the end macro mark, then +any white space characters after the mark and through the newline character +are trimmed. + +@item +It is also helpful to avoid using the comment marker (@code{#}). +It might be seen as a comment within the pseudo macro. + +@item +You should avoid using any of the quote characters@: double, +single or back-quote. It won't confuse AutoGen, but it might well +confuse you and/or your editor. +@end itemize + +As an example, assume we want to use @code{[+} and @code{+]} as the start +and end macro markers, and we wish to produce a @file{.c} and a @file{.h} +file, then the pseudo macro might look something like this: + +@example +[+ AutoGen5 template -*- Mode: emacs-mode-of-choice -*- +h=chk-%s.h +c +# make sure we don't use csh: +(setenv "SHELL" "/bin/sh") +] +@end example + +The template proper starts after the pseudo-macro. The starting +character is either the first non-whitespace character or the first +character after the newline that follows the end macro marker. + +@c === SECTION MARKER + +@node naming values +@section Naming a value +@cindex naming values + +When an AutoGen value is specified in a template, it is specified by name. +The name may be a simple name, or a compound name of several components. +Since each named value in AutoGen is implicitly an array of one or more +values, each component may have an index associated with it. + +@noindent +It looks like this: + +@example +comp-name-1 . comp-name-2 [ 2 ] +@end example + +Note that if there are multiple components to a name, each component +name is separated by a dot (@code{.}). Indexes follow a component name, +enclosed in square brackets (@code{[} and @code{]}). The index may be +either an integer or an integer-valued define name. The first component +of the name is searched for in the current definition level. If not +found, higher levels will be searched until either a value is found, +or there are no more definition levels. Subsequent components of the +name must be found within the context of the newly-current definition +level. Also, if the named value is prefixed by a dot (@code{.}), +@cindex . +then the value search is started in the current context only. +Backtracking +@cindex backtrack +into other definition levels is prevented. + +If someone rewrites this, I'll incorporate it. :-) + +@c === SECTION MARKER + +@node expression syntax +@section Macro Expression Syntax +@cindex expression syntax + +AutoGen has two types of expressions: full expressions and basic ones. +A full AutoGen expression can appear by itself, or as the argument +to certain AutoGen built-in macros: CASE, IF, ELIF, INCLUDE, +INVOKE (explicit invocation, @pxref{INVOKE}), and WHILE. +If it appears by itself, the result is inserted into the output. +If it is an argument to one of these macros, the macro code +will act on it sensibly. + +You are constrained to basic expressions only when passing +arguments to user defined macros, @xref{DEFINE}. + +The syntax of a full AutoGen expression is: + +@example +[[ <apply-code> ] <value-name> ] [ <basic-expr-1> [ <basic-expr-2> ]] +@end example + +How the expression is evaluated depends upon the presence or absence +of the apply code and value name. The "value name" is the name of +an AutoGen defined value, or not. If it does not name such a value, +the expression result is generally the empty string. All expressions +must contain either a @code{value-name} or a @code{basic-expr}. + +@menu +* apply code:: Apply Code +* basic expression:: Basic Expression +@end menu + +@node apply code +@subsection Apply Code + +The "apply code" selected determines the method of evaluating the +expression. There are five apply codes, including the non-use +of an apply code. + +@table @samp +@item no apply code +This is the most common expression type. +Expressions of this sort come in three flavors: + +@table @samp +@item <value-name> +The result is the value of @code{value-name}, if defined. +Otherwise it is the empty string. + +@item <basic-expr> +The result of the basic expression is the result of the full expression, +@xref{basic expression}. + +@item <value-name> <basic-expr> +If there is a defined value for @code{value-name}, then the @code{basic-expr} +is evaluated. Otherwise, the result is the empty string. +@end table + +@item % <value-name> <basic-expr> +If @code{value-name} is defined, use @code{basic-expr} as a format +string for sprintf. Then, if the @code{basic-expr} is either a back-quoted +string or a parenthesized expression, then hand the result to the +appropriate interpreter for further evaluation. Otherwise, for single +and double quote strings, the result is the result of the sprintf operation. +Naturally, if @code{value-name} is not defined, the result is the empty +string. + +For example, assume that @code{fumble} had the string value, @code{stumble}: +@example +[+ % fumble `printf '%%x\\n' $%s` +] +@end example +This would cause the shell to evaluate "@code{printf '%x\n' $stumble}". +Assuming that the shell variable @code{stumble} had a numeric value, +the expression result would be that number, in hex. Note the need +for doubled percent characters and backslashes. + +@item ? <value-name> <basic-expr-1> <basic-expr-2> +Two @code{basic-expr}-s are required. If the @code{value-name} is +defined, then the first @code{basic-expr-1} is evaluated, otherwise +@code{basic-expr-2} is. + +@item - <value-name> <basic-expr> +Evaluate @code{basic-expr} only if @code{value-name} is @i{not} defined. + +@item ?% <value-name> <basic-expr-1> <basic-expr-2> +This combines the functions of @samp{?} and @samp{%}. If @code{value-name} is +defined, it behaves exactly like @samp{%}, above, using @code{basic-expr-1}. +If not defined, then @code{basic-expr-2} is evaluated. + +For example, assume again that @code{fumble} had the string value, @code{stumble}: +@example +[+ ?% fumble `cat $%s` `pwd` +] +@end example +This would cause the shell to evaluate "@code{cat $stumble}". +If @code{fumble} were not defined, then the result would be the name +of our current directory. +@end table + +@node basic expression +@subsection Basic Expression + +A basic expression can have one of the following forms: + +@table @samp +@item 'STRING' +A single quoted string. Backslashes can be used to protect single +quotes (@code{'}), hash characters (@code{#}), or backslashes (@code{\}) +in the string. All other characters of STRING are output as-is when the +single quoted string is evaluated. Backslashes are processed before the hash +character for consistency with the definition syntax. It is needed there +to avoid preprocessing conflicts. + +@item "STRING" +A double quoted string. This is a cooked text string as in C, +except that they are not concatenated with adjacent strings. +Evaluating "@code{STRING}" will output STRING with all +backslash sequences interpreted. + +@item `STRING` +A back quoted string. When this expression is evaluated, STRING +is first interpreted as a cooked string (as in `"STRING"') and +evaluated as a shell expression by the AutoGen server shell. This +expression is replaced by the @file{stdout} output of +the shell. + +@item (STRING) +A parenthesized expression. It will be passed to the Guile +interpreter for evaluation and replaced by the resulting value. +If there is a Scheme error in this expression, Guile 1.4 and Guile 1.6 +will report the template line number where the error occurs. Guile 1.7 +has lost this capability. + +Guile has the capability of creating and manipulating variables that +can be referenced later on in the template processing. If you define +such a variable, it is invisible to AutoGen. To reference its value, +you must use a Guile expression. For example, +@example +[+ (define my-var "some-string-value") +] +@end example +can have that string inserted later, but only as in: +@example +[+ (. my-var) +] +@end example + +Additionally, other than in the @code{%} and @code{?%} expressions, the +Guile expressions may be introduced with the Guile comment character +(@code{;}) and you may put a series of Guile expressions within a single +macro. They will be implicitly evaluated as if they were arguments +to the @code{(begin ...)} expression. The result will be the +result of the last Guile expression evaluated. +@end table + +@ignore +END == TEMPLATE == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == MACROS == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node native macros +@section AutoGen Native Macros +@cindex native macros + +This section describes the various AutoGen natively defined macros. +Unlike the Scheme functions, some of these macros are "block macros" +with a scope that extends through a terminating macro. Block macros +must not overlap. That is to say, a block macro started within the +scope of an encompassing block macro must have its matching end macro +appear before the encompassing block macro is either ended or subdivided. + +The block macros are these: + +@table @code +@item CASE +This macro has scope through the @code{ESAC} macro. +The scope is subdivided by @code{SELECT} macros. +You must have at least one @code{SELECT} macro. + +@item DEFINE +This macro has scope through the @code{ENDDEF} macro. The defined +user macro can never be a block macro. This macro is extracted from +the template @i{before} the template is processed. Consequently, you +cannot select a definition based on context. You can, however, place +them all at the end of the file. + +@item FOR +This macro has scope through the @code{ENDFOR} macro. + +@item IF +This macro has scope through the @code{ENDIF} macro. +The scope may be subdivided by @code{ELIF} and @code{ELSE} +macros. Obviously, there may be only one @code{ELSE} macro +and it must be the last of these subdivisions. + +@item INCLUDE +This macro has the scope of the included file. +It is a block macro in the sense that the included +file must not contain any incomplete block macros. + +@item WHILE +This macro has scope through the @code{ENDWHILE} macro. +@end table +@ignore +END == MACROS == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AUGMENTING == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node output controls +@section Redirecting Output +@cindex Redirecting Output +@cindex diversion + +AutoGen provides a means for redirecting the template output to different +files or, in @file{M4} parlance, to various diversions. It is accomplished +by providing a set of Scheme functions named @code{out-*} +(@pxref{AutoGen Functions}). + +@table @samp +@item out-push-new (@pxref{SCM out-push-new}) +This allows you to logically "push" output files onto a stack. +If you supply a string name, then a file by that name is created +to hold the output. If you do not supply a name, then the text is +written to a scratch pad and retrieved by passing a ``@code{#t}'' argument +to the @code{out-pop} (@pxref{SCM out-pop}) function. + +@item out-pop (@pxref{SCM out-pop}) +This function closes the current output file and resumes output to the next +one in the stack. At least one output must have been pushed onto the output +stack with the @code{out-push-new} (@pxref{SCM out-push-new}) function. If +``@code{#t}'' is passed in as an argument, then the entire contents of the +diversion (or file) is returned. + +@item out-suspend (@pxref{SCM out-suspend}) +This function does not close the current output, but instead sets it aside +for resumption by the given name with @code{out-resume}. The current output +must have been pushed on the output queue with @code{out-push-new} +(@pxref{SCM out-push-new}). + +@item out-resume (@pxref{SCM out-resume}) +This will put a named file descriptor back onto the top of +stack so that it becomes the current output again. + +@item out-switch (@pxref{SCM out-switch}) +This closes the current output and creates a new file, +purging any preexisting one. This is a shortcut for "pop" +followed by "push", but this can also be done at the base level. + +@item out-move (@pxref{SCM out-move}) +Renames the current output file without closing it. +@end table + +There are also several functions for determining the output +status. @xref{AutoGen Functions}. + +@ignore + +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + +@end ignore + +@page +@node Augmenting AutoGen +@chapter Augmenting AutoGen Features +@cindex Augmenting AutoGen + +AutoGen was designed to be simple to enhance. You can do it by +providing shell commands, Guile/Scheme macros or callout functions +that can be invoked as a Guile macro. Here is how you do these. + +@menu +* shell commands:: Shell Output Commands +* guile macros:: Guile Macros +* guile callouts:: Guile Callout Functions +* AutoGen macros:: AutoGen Macros +@end menu + +@c === SECTION MARKER + +@node shell commands +@section Shell Output Commands + +Shell commands are run inside of a server process. This means that, +unlike @file{make}, context is kept from one command to the next. +Consequently, you can define a shell function in one place inside of +your template and invoke it in another. You may also store values +in shell variables for later reference. If you load functions from +a file containing shell functions, they will remain until AutoGen exits. + +If your shell script should determine that AutoGen should stop +processing, the recommended method for stopping AutoGen is: +@example +die "some error text" +@end example + +@noindent +That is a shell function added by AutoGen. It will send a SIGTERM +to autogen and exit from the "persistent" shell. + +@c === SECTION MARKER + +@node guile macros +@section Guile Macros + +Guile also maintains context from one command to the next. This means you may +define functions and variables in one place and reference them elsewhere. +You also may load Guile macro definitions from a Scheme file by using the +@code{--load-scheme} command line option (@pxref{autogen load-scheme}). +Beware, however, that the AutoGen specific scheme functions have not been +loaded at this time, so though you may define functions that reference them, +do not invoke the AutoGen functions at this time. + +If your Scheme script should determine that AutoGen should stop +processing, the recommended method for stopping AutoGen is: +@example +(error "some error text") +@end example + +@c === SECTION MARKER + +@node guile callouts +@section Guile Callout Functions + +Callout functions must be registered with Guile to work. This can +be accomplished either by putting your routines into a shared library +that contains a @code{void scm_init( void )} routine that registers +these routines, or by building them into AutoGen. + +To build them into AutoGen, you must place your routines in the source +directory and name the files @file{exp*.c}. You also must have a stylized +comment that @file{getdefs} can find that conforms to the following: + +@example +/*=gfunc <function-name> + * + * what: <short one-liner> + * general_use: + * string: <invocation-name-string> + * exparg: <name>, <description> [, ['optional'] [, 'list']] + * doc: A long description telling people how to use + * this function. +=*/ +SCM +ag_scm_<function-name>( SCM arg_name[, ...] ) +@{ <code> @} +@end example + +@table @samp +@item gfunc +You must have this exactly thus. + +@item <function-name> +This must follow C syntax for variable names + +@item <short one-liner> +This should be about a half a line long. +It is used as a subsection title in this document. + +@item general_use: +You must supply this unless you are an AutoGen maintainer and are writing +a function that queries or modifies the state of AutoGen. + +@item <invocation-name-string> +Normally, the @code{function-name} string will be transformed into +a reasonable invocation name. However, that is not always true. +If the result does not suit your needs, then supply an alternate string. + +@item exparg: +You must supply one for each argument to your function. +All optional arguments must be last. +The last of the optional arguments may be a list, if you choose. + +@item doc: +Please say something meaningful. + +@item [, ...] +Do not actually specify an ANSI ellipsis here. You must provide +for all the arguments you specified with @code{exparg}. +@end table + +See the Guile documentation for more details. +More information is also available in a large comment at the +beginning of the @file{agen5/snarf.tpl} template file. + +@c === SECTION MARKER + +@node AutoGen macros +@section AutoGen Macros + +There are two kinds@: those you define yourself and AutoGen native. +The user-defined macros may be defined in your templates or loaded +with the @code{--lib-template} option +(See @ref{DEFINE} and @ref{autogen lib-template}). + +As for AutoGen native macros, do not add any. It is easy to do, but I +won't like it. The basic functions needed to accomplish looping over +and selecting blocks of text have proved to be sufficient over a period +of several years. New text transformations can be easily added via any +of the AutoGen extension methods, as discussed above. + +@ignore +END == AUGMENTING == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == INSTALLATION == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@page +@node Installation +@chapter Configuring and Installing + +@menu +* configuring:: Configuring AutoGen +* AutoGen CGI:: AutoGen as a CGI server +* signal names:: Signal Names +* installing:: Installing AutoGen +@end menu + +@c === SECTION MARKER + +@node configuring +@section Configuring AutoGen +@cindex configuring + +AutoGen is configured and built using Libtool, Automake and Autoconf. +Consequently, you can install it wherever you wish using the various +@samp{--prefix} options. To the various configuration options supplied +by these tools, AutoGen adds a few of its own: + +@table @samp +@item --disable-shell +AutoGen is now capable of acting as a CGI forms server, @xref{AutoGen CGI}. +As such, it will gather its definitions using either @samp{GET} or +@samp{POST} methods. All you need to do is have a template named +@file{cgi.tpl} handy or specify a different one with a command line +option. + +However, doing this without disabling the server shell brings +considerable risk. If you were to pass user input to a script +that contained, say, the classic "@samp{`rm -rf /`}", you might have +a problem. This configuration option will cause shell template +commands to simply return the command string as the result. +No mistakes. Much safer. Strongly recommended. +The default is to have server shell scripting enabled. + +Disabling the shell will have some build side effects, too. + +@itemize @bullet +@item +Many of the make check tests will fail, since they assume +a working server shell. +@item +The getdefs and columns programs are not built. +The options are distributed as definition files and they +cannot be expanded with a shell-disabled AutoGen. +@item +Similarly, the documentation cannot be regenerated because +the documentation templates depend on subshell functionality. +@end itemize + +@item --enable-debug +Turning on AutoGen debugging enables very detailed inspection of +the input definitions and monitoring shell script processing. +These options are not particularly useful to anyone not directly +involved in maintaining AutoGen. If you do choose to enable AutoGen +debugging, be aware that the usage page was generated without these +options, so when the build process reaches the documentation rebuild, +there will be a failure. @samp{cd} into the @file{agen5} build +directory, @samp{make} the @samp{autogen.texi} file and all will +be well thereafter. + +@item --with-regex-header +@itemx --with-header-path +@itemx --with-regex-lib +These three work together to specify how to compile with and link to +a particular POSIX regular expression library. The value for +@file{--with-regex-header=value} must be the name of the relevant header +file. The AutoGen sources will attempt to include that source with +a @code{#include <value>} C preprocessing statement. The @code{path} from the +@file{--with-header-path=path} will be added to @code{CPPFLAGS} as @file{-Ipath}. +The @code{lib-specs} from @file{--with-regex-lib=lib-specs} will be added +to @code{LDFLAGS} without any adornment. +@end table + +@c === SECTION MARKER + +@page +@node AutoGen CGI +@section AutoGen as a CGI server + +AutoGen is now capable of acting as a CGI forms server. +It behaves as a CGI server if the definitions input is from stdin +and the environment variable @code{REQUEST_METHOD} is defined +and set to either "GET" or "POST". If set to anything else, +AutoGen will exit with a failure message. When set to one of those +values, the CGI data will be converted to AutoGen definitions +(@pxref{Definitions File}) and the template named "@code{cgi.tpl}" +will be processed. + +This works by including the name of the real template to process +in the form data and having the "@code{cgi.tpl}" template include +that template for processing. I do this for processing the form +@url{http://autogen.sourceforge.net/conftest.html}. The "@code{cgi.tpl}" +looks approximately like this: + +@example +<? AutoGen5 Template ?> +<? +IF (not (exist? "template")) ?><? + form-error ?><? + +ELIF (=* (get "template") "/") ?><? + form-error ?><? + +ELIF (define tpl-file (string-append "cgi-tpl/" + (get "template"))) + (access? tpl-file R_OK) ?><? + INCLUDE (. tpl-file) ?><? + +ELIF (set! tpl-file (string-append tpl-file ".tpl")) + (access? tpl-file R_OK) ?><? + INCLUDE (. tpl-file) ?><? + +ELSE ?><? + form-error ?><? +ENDIF ?> +@end example + +@noindent +This forces the template to be found in the "@code{cgi-tpl/}" +directory. Note also that there is no suffix specified in the +pseudo macro (@pxref{pseudo macro}). That tells AutoGen to emit +the output to @file{stdout}. + +The output is actually spooled until it is complete so that, +in the case of an error, the output can be discarded and a proper +error message can be written in its stead. + +@strong{Please also note} that it is advisable, @emph{especially} for network +accessible machines, to configure AutoGen (@pxref{configuring}) with +shell processing disabled (@code{--disable-shell}). That will make it +impossible for any referenced template to hand data to a subshell for +interpretation. + +@c === SECTION MARKER + +@node signal names +@section Signal Names +@cindex Signal Names + +When AutoGen is first built, it tries to use @code{psignal(3)}, +@code{sys_siglist}, @code{strsigno(3)} and @code{strsignal(3)} from the +host operating system. If your system does not supply these, the +AutoGen distribution will. However, it will use the distributed mapping +and this mapping is unlikely to match what your system uses. This can +be fixed. Once you have installed autogen, the mapping can be rebuilt +on the host operating system. To do so, you must perform the +following steps: + +@enumerate +@item +Build and install AutoGen in a place where it will be found in your +search path. + +@item +@code{cd $@{top_srcdir@}/compat} + +@item +@code{autogen strsignal.def} + +@item +Verify the results by examining the @file{strsignal.h} file produced. + +@item +Re-build and re-install AutoGen. +@end enumerate + +If you have any problems or peculiarities that cause this process to +fail on your platform, please send me copies of the header files +containing the signal names and numbers, along with the full path names +of these files. I will endeavor to fix it. There is a shell script +inside of @file{strsignal.def} that tries to hunt down the information. + +@c === SECTION MARKER + +@node installing +@section Installing AutoGen +@cindex Installing + +There are several files that get installed. The number depend +whether or not both shared and archive libraries are to be +installed. The following assumes that everything is installed +relative to @code{$prefix}. You can, of course, use +@code{configure} to place these files where you wish. + +@strong{NB}@: AutoGen does not contain any compiled-in path names. +All support directories are located via option processing, +the environment variable @code{HOME} or finding the directory where +the executable came from. + +The installed files are: + +@enumerate +@item +The executables in @file{bin} (autogen, getdefs and columns). + +@item +The AutoOpts link libraries as @file{lib/libopts.*}. + +@item +An include file in @file{include/options.h}, needed for +Automated Option Processing (see next chapter). + +@item +Several template files and a scheme script in @file{share/autogen}, needed +for Automated Option Processing (@pxref{AutoOpts}), parsing definitions +written with scheme syntax (@pxref{Dynamic Text}), the templates for +producing documentation for your program (@pxref{documentation attributes}), +autoconf test macros, and AutoFSM. + +@item +Info-style help files as @file{info/autogen.info*}. +These files document AutoGen, the option processing +library AutoOpts, and several add-on components. + +@item +The three man pages for the three executables are installed in man/man1. +@end enumerate + +This program, library and supporting files can be installed +with three commands: + +@itemize @bullet +@item +<src-dir>/configure [ <configure-options> ] +@item +make +@item +make install +@end itemize + +However, you may wish to insert @code{make check} +before the @code{make install} command. + +If you do perform a @code{make check} and there are any failures, you +will find the results in @code{<module>/test/FAILURES}. Needless to say, I +would be interested in seeing the contents of those files and any +associated messages. If you choose to go on and analyze one of these +failures, you will need to invoke the test scripts individually. You +may do so by specifying the test (or list of test) in the TESTS make +variable, thus: + +@example +gmake TESTS=test-name.test check +@end example + +I specify @code{gmake} because most makes will not let you override +internal definitions with command line arguments. @code{gmake} does. + +All of the AutoGen tests are written to honor the contents of the +@t{VERBOSE} environment variable. Normally, any commentary generated +during a test run is discarded unless the @t{VERBOSE} environment +variable is set. So, to see what is happening during the test, you +might invoke the following with @i{bash} or @i{ksh}: + +@example +VERBOSE=1 gmake TESTS="for.test forcomma.test" check +@end example + +@noindent +Or equivalently with @i{csh}: + +@example +env VERBOSE=1 gmake TESTS="for.test forcomma.test" check +@end example + +@ignore +END == INSTALLATION == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AUTOFSM == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node AutoFSM +@section Automated Finite State Machine +@cindex AutoFSM +@cindex 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 @uref{http://www.gnu.org/software/autogen/autofsm.html,viewing}, +or you can @uref{http://download.sourceforge.net/autogen/,download FSM}. + +@node AutoXDR +@section Combined RPC Marshalling +@cindex RPC +@cindex rpcgen +@cindex remote procedure call +@cindex AutoXDR +@cindex XDR + +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 +@code{AutoXDR} for generating the marshaling and unmarshaling of combined +RPC calls. There is a brief example +@uref{http://www.gnu.org/software/autogen/xdr/index.html,on the web}, but +you should @uref{http://download.sourceforge.net/autogen/,download AutoXDR}. + +@c === SECTION MARKER + +@node AutoEvents +@section Automated Event Management +@cindex AutoEvents + +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 +@uref{http://www.gnu.org/software/autogen/autoevents.html,web page} +on the subject, if you are interested. +I have some useful things put together, but it is not ready +to call a product. + +@ignore +END == AUTOFSM == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = +@c +@c AUTOOPTS SECTIONS +@c +@c +@ignore +START == AUTOOPTS == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +All the features notwithstanding, some applications simply have +well-established command line interfaces. Even still, those programs +may use the configuration file parsing portion of the library. +See the ``AutoOpts Features'' and ``Configuration File Format'' sections. + +@menu +* Features:: AutoOpts Features +* Licensing:: AutoOpts Licensing +* Caveats:: Developer and User Notes +* Quick Start:: Quick Start +* Option Definitions:: Option Definitions +* AutoOpts API:: Programmatic Interface +* Multi-Threading:: Multi-Threading +* option descriptor:: Option Descriptor File +* Using AutoOpts:: Using AutoOpts +* Presetting Options:: Configuring your program +* Config File Format:: Configuration File Format +* shell options:: AutoOpts for Shell Scripts +* AutoInfo:: Automated Info Docs +* AutoMan pages:: Automated Man Pages +* getopt_long:: Using getopt(3C) +* i18n:: Internationalizing AutoOpts +* Naming Conflicts:: Naming Conflicts +* All Attribute Names:: All Attribute Names +* Option Define Names:: Option Definition Name Index +@end menu + +@c === SECTION MARKER + +@node Features +@section AutoOpts Features +@cindex features + +AutoOpts supports option processing; option state saving; and +program documentation with innumerable features. Here, we list +a few obvious ones and some important ones, but the full list is +really defined by all the attributes defined in the @ref{Option Definitions} +section. + +@enumerate +@item +POSIX-compliant short (flag) option processing. + +@item +GNU-style long options processing. Long options +are recognized without case sensitivity, and they may be abbreviated. + +@item +Environment variable initializations, @xref{environrc}. + +@item +Initialization from configuration files (aka RC or INI files), and +saving the option state back into one, @xref{loading rcfile}. + +@item +Config files may be partitioned. One config file may be used by several +programs by partitioning it with lines containing, +``@code{[PROGRAM_NAME]}'' or ``@code{<?program-name>}'', @xref{loading rcfile}. + +@item +Config files may contain AutoOpts directives. +``@code{<?auto-options [[option-text]]>}'' may be used to set @code{AutoOpts} +option processing options. Viz., @code{GNU} usage layout versus @code{AutoOpts} +conventional layout, and @code{misuse-usage} versus @code{no-misuse-usage}, +@xref{usage attributes}. + +@item +Options may be marked as @code{@i{dis}-abled} with a disablement prefix. +Such options may default to either an enabled or a disabled state. You +may also provide an enablement prefix, too, e.g., @code{--allow-mumble} +and @code{--prevent-mumble} (@pxref{Common Attributes}). + +@item +Verify that required options are present between the minimum and maximum +number of times on the command line. Verify that conflicting options do not +appear together. Verify that options requiring the presence of other options +are, in fact, used in the presence of other options. +See @xref{Common Attributes}, and @xref{Option Conflict Attributes}. + +@item +There are several @ref{automatic options, automatically supported options}. +They will have short flags if any options have option flags and the flags +are not suppressed. The associated flag may be altered or suppressed by +specifying no value or an alternate character for ``@code{xxx-value;}'' in +the option definition file. ``@code{xxx}'' is the name of the option below: + +@table @samp +@item --help +@itemx --more-help +These are always available. @samp{--more-help} will pass the full usage +text through a pager. +@item --usage +@vindex usage-opt +This is added to the option list if @code{usage-opt} is specified. +It yields the abbreviated usage to @file{stdout}. +@item --version +This is added to the option list if @code{version = xxx;} is specified. +@item --load-opts +@itemx --save-opts +These are added to the option list if @code{homerc} is specified. Mostly. +If, @code{disable-save} is specified, then @samp{--save-opts} is disabled. +@end table + +@item +Various forms of main procedures can be added to the output, +@xref{Generated main}. There are four basic forms: + +@enumerate a +@item +A program that processes the arguments and writes to standard out +portable shell commands containing the digested options. + +@item +A program that will generate portable shell commands to parse the defined +options. The expectation is that this result will be copied into a +shell script and used there. + +@item +A ``for-each'' main that will invoke a named function once for either +each non-option argument on the command line or, if there are none, +then once for each non-blank, non-comment input line read from stdin. + +@item +A main procedure of your own design. Its code can be supplied in the +option description template or by incorporating another template. +@end enumerate + +@item +There are several methods for handling option arguments. +@itemize @bullet +@item +nothing (@pxref{OPT_ARG}) option argument strings are globally available. +@item +user supplied (@pxref{Option Argument Handling}) +@item +stack option arguments (@pxref{Option Argument Handling}) +@item +integer numbers (@pxref{arg-type number}) +@item +true or false valued (@pxref{arg-type boolean}) +@item +enumerated list of names (@pxref{arg-type keyword}) +@item +an enumeration (membership) set (@pxref{arg-type set membership}) +@item +a list of name/value pairs (option ``subopts'') (@pxref{arg-type hierarchy}) +@item +a time duration or a specific time and date +@item +validated file name (@pxref{arg-type file name}) +@item +optional option argument (@pxref{arg-optional}) +@end itemize + +@item +The generated usage text can be emitted in either AutoOpts standard +format (maximizing the information about each option), or GNU-ish +normal form. The default form is selected by either specifying or not +specifying the @code{gnu-usage} attribute (@pxref{information attributes}). +This can be overridden by the user himself with the +@code{AUTOOPTS_USAGE} environment variable. If it exists and is set +to the string @code{gnu}, it will force GNU-ish style format; if it is +set to the string @code{autoopts}, it will force AutoOpts standard +format; otherwise, it will have no effect. + +@item +The usage text and many other strings are stored in a single character array +(@pxref{SCM string-table-new,string table functions}). This reduces fixup +costs when loading the program or library. The downside is that if GCC +detects that any of these strings are used in a printf format, you may get +the warning, @code{embedded '\0' in format}. To eliminate the warning, you +must provide GCC with the @code{-Wno-format-contains-nul} option. + +@item +If you compile with @code{ENABLE_NLS} defined and @code{_()} defined to +a localization function (e.g. @code{gettext(3GNU)}), then the option +processing code will be localizable (@pxref{i18n}). Provided also that +you do not define the @code{no-xlate} attribute to @emph{anything} +(@pxref{presentation attributes}). + +@item +Provides a callable routine to parse +a text string as if it were from one of the rc/ini/config files, +hereafter referred to as a configuration file. + +@item +By adding a @samp{doc} and @samp{arg-name} attributes to each option, +AutoGen will also be able to produce a man page and the @samp{invoking} +section of a texinfo document. + +@item +Intermingled option processing. AutoOpts options may be intermingled with +command line operands and options processed with other parsing techniques. +This is accomplished by setting the @code{allow-errors} +(@pxref{program attributes}) attribute. When processing reaches a point +where @code{optionProcess} (@pxref{libopts-optionProcess}) needs to be called +again, the current option can be set with @code{RESTART_OPT(n)} +(@pxref{RESTART_OPT}) before calling @code{optionProcess}. + +See: @xref{library attributes}. + +@item +Library suppliers can specify command line options that their +client programs will accept. They specify option definitions +that get @code{#include}-d into the client option definitions +and they specify an "anchor" option that has a callback and must be invoked. +That will give the library access to the option state for their options. + +@item +library options. An AutoOpt-ed library may export its options for use in +an AutoOpt-ed program. This is done by providing an option definition file +that client programs @code{#include} into their own option definitions. +See ``AutoOpt-ed Library for AutoOpt-ed Program'' (@pxref{lib and program}) +for more details. +@end enumerate + +@c === SECTION MARKER + +@node Licensing +@section AutoOpts Licensing +@cindex Licensing + +When AutoGen is installed, the AutoOpts project is installed with it. +AutoOpts includes various AutoGen templates and a pair of shared +libraries. These libraries may be used under the terms of version 3 +of the GNU Lesser General Public License (LGPL). + +One of these libraries (@code{libopts}) is needed by programs that are built +using AutoOpts generated code. This library is available as a separate +``tear-off'' source tarball. It is redistributable for use under either of +two licenses: The above mentioned GNU Lesser General Public License, and +the advertising-clause-free BSD license. Both of these license terms are +incorporated into appropriate COPYING files included with the @code{libopts} +source tarball. This source may be incorporated into your package with +the following simple commands: + +@example +rm -rf libopts libopts-* +gunzip -c `autoopts-config libsrc` | \ + tar -xvf - +mv libopts-*.*.* libopts +@end example + +View the @file{libopts/README} file for further integration information. + +@c === SECTION MARKER + +@page +@node Caveats +@section Developer and User Notes + +AutoOpts has its conventional way of displaying option information +that includes somewhat more information that the standard GNU method. +AutoOpts will also print out a line of usage text for each option type +when options are misspecified. GNU programs typically do not do this. +These defaults can be changed on a per-program basis by adding either +or both of the following in the option definition file: + +@example +gnu-usage; +no-misuse-usage; +@end example + +Users may also override these settings with the @code{AUTOOPTS_USAGE} +environment variable. It may be set to a comma or white space separated +list of the following strings: + +@table @samp +@item gnu +@cindex gnu +The format of the extended usage text will be displayed in GNU-normal form. +The default display for @code{--version} will be to include a note +on licensing terms. + +@item autoopts +@cindex autoopts +The format of the extended usage will be in AutoOpts' native layout. + +@item no-misuse-usage +@cindex no-misuse-usage +When an option error is made on the command line, the abbreviated +usage text will be suppressed. + +@item misuse-usage +@cindex misuse-usage +When an option error is made on the command line, the abbreviated +usage text will be shown. +@end table + +@noindent +The setting used is the last one seen. The @code{autoopts} and +@code{misuse-usage} serve no purpose, unless the definition file +entries were specified as above. + +@b{Note for developers}: + +The templates used to implement AutoOpts depend heavily upon +token pasting. That mens that if you name an option, ``debug'', for +example, the generated header will expect to be able to emit +@code{#define} macros such as this: +@example +#define DESC(n) (autogenOptions.pOptDesc[INDEX_OPT_## n]) +@end example +and expect @code{DESC(DEBUG)} to expand correctly into +@code{(autogenOptions.pOptDesc[INDEX_OPT_DEBUG])}. +If @code{DEBUG} is @code{#defined} to something else, then +that something else will be in the above expansion. + +If you discover you are having strange problems like this, +you may wish to use some variation of the @code{guard-option-names} +@xref{program attributes}. + + +@c === SECTION MARKER + +@page +@node Quick Start +@section Quick Start +@cindex example, simple AutoOpts + +Since it is generally easier to start with a simple example than it is +to look at the options that AutoGen uses itself, here is a very simple +AutoOpts example. You can copy this example out of the Info file and +into a source file to try it. You can then embellish it into what you +really need. For more extensive examples, you can also examine the help +output and option definitions for the commands @code{columns}, +@code{getdefs} and @code{autogen} itself. + +For our simple example, assume you have a program named @code{check} +that takes two options: + +@enumerate +@item +A list of directories to check over for whatever it is @code{check} does. +You want this option available as a POSIX-style flag option +and a GNU long option. You want to allow as many of these +as the user wishes. +@item +An option to show or not show the definition tree being used. +Only one occurrence is to be allowed, specifying one or the other. +@end enumerate + +@ignore +END == AUTOOPTS == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AUTOOPTS-MAIN == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@noindent +Normally, however, you would not use the ``main'' clause. Instead, +the file would be named something like @file{checkopt.def}, you would +compile @file{checkopt.c} the usual way, and link the object with the rest +of your program. + +The options are processed by calling @code{optionProcess} +(@pxref{libopts-optionProcess}): + +@example +main( int argc, char** argv ) +@{ + @{ + int optct = optionProcess( &checkOptions, argc, argv ); + argc -= optct; + argv += optct; + @} +@end example + +The options are tested and used as in the following fragment. +``@code{ENABLED_OPT}'' is used instead of ``@code{HAVE_OPT}'' for the +@code{show-defs} option because it is an enabled/disabled option type: + +@example + if ( ENABLED_OPT( SHOW_DEFS ) + && HAVE_OPT( CHECK_DIRS )) @{ + int dirct = STACKCT_OPT( CHECK_DIRS ); + char** dirs = STACKLST_OPT( CHECK_DIRS ); + while (dirct-- > 0) @{ + char* dir = *dirs++; + ... +@end example + +The ``doc'' clauses are used in the flag stanzas for man pages and +texinfo invoking documentation. With the above definition file, the +two following commands will produce the two documentation files +@file{check.1} and @file{invoke-check.texi}. The latter file will +be generated as a chapter, rather than a section or subsection. + +@example +autogen -Tagman-cmd check.def +autogen -DLEVEL=chapter -Tagtexi-cmd -binvoke-check.texi check.def +@end example + +@noindent +The result of which is left as an exercise for the reader. + +A lot of magic happens to make this happen. +The rest of this chapter will describe the myriad of option attributes +supported by AutoOpts. However, keep in mind that, in general, you won't +need much more than what was described in this "quick start" section. + +@node Option Definitions +@section Option Definitions +@cindex Option Definitions + +AutoOpts uses an AutoGen definitions file for the definitions of the +program options and overall configuration attributes. +The complete list of program and option attributes is quite extensive, +so if you are reading to understand how to use AutoOpts, I recommend +reading the "Quick Start" section (@pxref{Quick Start}) and paying +attention to the following: + +@enumerate +@item +@code{prog-name}, @code{prog-title}, and @code{argument}, program +attributes, @xref{program attributes}. +@item +@code{name} and @code{descrip} option attributes, @xref{Required Attributes}. +@item +@code{value} (flag character) and @code{min} (occurrence counts) +option attributes, @xref{Common Attributes}. +@item +@code{arg-type} from the option argument specification section, +@xref{Option Arguments}. +@item +Read the overall how to, @xref{Using AutoOpts}. +@item +Highly recommended, but not required, are the several "man" and +"info" documentation attributes, @xref{documentation attributes}. +@end enumerate + +Keep in mind that the majority are rarely used and can be safely +ignored. However, when you have special option processing requirements, +the flexibility is there. + +@menu +* program attributes:: Program Description Attributes +* library attributes:: Options for Library Code +* information attributes:: Program Information Attributes +* Generated main:: Generating main procedures +* option attributes:: Option Attributes +* Option Arguments:: Option Argument Specification +* Option Argument Handling:: Option Argument Handling +* Internationalizing Options:: Internationalizing Options +* documentation attributes:: Man and Info doc Attributes +* automatic options:: Automatically Supported Options +* standard options:: Library of Standard Options +@end menu + +@node program attributes +@subsection Program Description Attributes +@cindex program attributes + +The following global definitions are used to define attributes of the entire +program. These generally alter the configuration or global behavior of the +AutoOpts option parser. The first two are required of every program. The +third is required if there are to be any left over arguments (operands) +after option processing. The rest have been grouped below. Except as noted, +there may be only one copy of each of these definitions: + +@table @samp + +@item prog-name +@vindex prog-name +This attribute is required. Variable names derived from this name +are derived using @code{string->c_name!} (@pxref{SCM string->c-name!}). + +@item prog-title +@vindex prog-title +This attribute is required and may be any descriptive text. + +@item argument +@vindex argument +This attribute is required if your program uses operand arguments. +It specifies the syntax of the arguments that @strong{follow} the options. +It may not be empty, but if it is not supplied, then option processing +must consume all the arguments. If it is supplied and starts with an +open bracket (@code{[}), then there is no requirement on the presence or +absence of command line arguments following the options. Lastly, if it +is supplied and does not start with an open bracket, then option +processing must @strong{not} consume all of the command line arguments. + +@item config-header +@vindex config-header +If your build has a configuration header, it must be included before +anything else. Specifying the configuration header file name with this +attribute will cause that to happen. +@end table + +@menu +* usage attributes:: Usage and Version Info Display +* config attributes:: Program Configuration +* programming attributes:: Programming Details +* presentation attributes:: User Presentation Attributes +@end menu + +@c +@c = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = +@c +@node usage attributes +@subsubsection Usage and Version Info Display + +These will affect the way usage is seen and whether or not version +information gets displayed. + +@table @samp +@item full-usage +@vindex full-usage +If this attribute is provided, it may specify the full length +usage text, or a variable name assignable to a ``char const *'' pointer, +or it may be empty. The meanings are determined by the length. +@itemize @bullet +@item +If not provided, the text will be computed as normal. +@item +If the length is zero, then the usage text will be derived from +the current settings and inserted as text into the generated .c file. +@item +If the length is 1 to 32 bytes, then it is presumed to be a variable +name that either points to or is an array of const chars. +@item +If it is longer than that, it is presumed to be the help text itself. +This text will be inserted into the generated .c file. +@end itemize + +This string should be readily translatable. Provision will be made +to translate it if this is provided, if the source code is compiled with +@code{ENABLE_NLS} defined, and @code{no-xlate} has not been set to the +value @emph{anything}. + +@item short-usage +@vindex short-usage +If this attribute is provided, it is used to specify an abbreviated +version of the usage text. This text is constructed in the same way +as the ``full-usage'', described above. + +@item gnu-usage +@vindex gnu-usage +AutoOpts normaly displays usage text in a format that provides more +information than the standard GNU layout, but that also means it is +not the standard GNU layout. This attribute changes the default to +GNU layout, with the @code{AUTOOPTS_USAGE} environment variable used +to request @code{autoopts} layout. +See @xref{Caveats, Developer and User Notes}. + +@item usage-opt +@vindex usage-opt +I apologize for too many confusing usages of usage. +This attribute specifies that @code{--usage} and/or @code{-u} be +supported. The help (usage) text displayed will be abbreviated +when compared to the default help text. + +@item no-misuse-usage +@vindex no-misuse-usage +When there is a command line syntax error, by default AutoOpts will +display the abbreviated usage text, rather than just a one line +``you goofed it, ask for usage'' message. You can change the default +behavior for your program by supplying this attribute. The user may +override this choice, again, with the @code{AUTOOPTS_USAGE} environment +variable. See @xref{Caveats, Developer and User Notes}. + +@item prog-group +@vindex prog-group +The version text in the @file{getopt.tpl} template will include this +text in parentheses after the program name, when this attribute is specified. +For example: +@example +mumble (stumble) 1.0 +@end example +@noindent +says that the ``@code{mumble}'' program is version 1.0 and is part of the +``@code{stumble}'' group of programs. + +@item usage +@vindex usage +If your program has some cleanup work that must be done before exiting +on usage mode issues, or if you have to customize the usage message in +some way, specify this procedure and it will be called instead of the +default @code{optionUsage()} function. For example, if a program is +using the curses library and needs to invoke the usage display, then +you must arrange to call @code{endwin()} before invoking the library +function @code{optionUsage()}. This can be handled by specifying your +own usage function, thus: +@example +void +my_usage(tOptions * opts, int ex) +@{ + if (curses_window_active) + endwin(); + optionUsage(opts, ex); +@} +@end example + +@item version +@vindex version +Specifies the program version and activates the VERSION option, +@xref{automatic options}. +@end table + +@c +@c = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = +@c +@node config attributes +@subsubsection Program Configuration + +Programs may be ``pre-configured'' before normal command line options +are processed (See @pxref{Immediate Action, Immediate Action Attributes}). +How configuration files and environment variables are handled get +specified with these attributes. + +@table @samp +@item disable-load +@itemx disable-save +@vindex disable-load +@vindex disable-save +Indicates that the command line usage of @code{--load-opts} and/or +@code{--save-opts} are disallowed. + +@item environrc +@vindex environrc +Indicates looking in the environment for values of variables named, +@code{PROGRAM_OPTNAME} or @code{PROGRAM}, where @code{PROGRAM} is the +upper cased @code{C-name} of the program and @code{OPTNAME} is the +upper cased @code{C-name} of a specific option. The contents of +the @code{PROGRAM} variable, if found, are tokenized and processed. +The contents of @code{PROGRAM_OPTNAME} environment variables are taken +as the option argument to the option nameed @code{optname}. + +@item homerc +@vindex homerc +Specifies that option settings may be loaded from and stored into +configuration files. Each instance of this attribute is either a directory or +a file using a specific path, a path based on an environment variable or a +path relative to installation directories. The method used depends on the name. +If the one entry is empty, it enables the loading and storing of settings, +but no specific files are searched for. Otherwise, a series of configuration +files are hunted down and, if found, loaded. + +If the first character of the @samp{homerc} value is not the dollar +character (@code{$}), then it is presumed to be a path name based on the +current directory. Otherwise, the method depends on the second character: + +@table @code +@item $ +The path is relative to the directory where the executable was found. +@item @@ +The path is relative to the package data directory, e.g. +@code{/usr/local/share/autogen}. +@item [a-zA-Z] +The path is derived from the named environment variable. +@end table + +Use as many as you like. The presence of this attribute +activates the @code{--save-opts} and @code{--load-opts} options. +However, saving into a file may be disabled with the @samp{disable-save}. +@xref{loading rcfile}. +See the @code{optionMakePath(3AGEN)} man page for excruciating details. + +@item rcfile +@vindex rcfile +Specifies the configuration file name. This is only useful if you +have provided at least one @code{homerc} attribute. +@example +default: .<prog-name>rc +@end example + +@item vendor-opt +@vindex vendor-opt +This option implements the @code{-W} vendor option command line option. + +For POSIX specified utilities, the options are constrained to the options +that are specified by POSIX. Extensions should be handled with @code{-W} +command line options, the short flag form. Long option name processing +must be disabled. In fact, the @code{long-opts} attribute must not be +provided, and some options must be specified without flag values. + +The @code{-W long-name} is processed by looking up the long option +name that follows it. It cannot be a short flag because that would +conflict with the POSIX flag name space. It will be processed as if +long options were accepted and @code{--long-name} were found on the +command line. +@end table + +@c +@c = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = +@c +@node programming attributes +@subsubsection Programming Details + +These attributes affect some of the ways that the option data are +used and made available to the program. + +@table @samp +@item config-header +@vindex config-header +The contents of this attribute should be just the name of the configuration +file. A "#include" naming this file will be inserted at the top of the +generated header. + +@item exit-name +@itemx exit-desc +@vindex exit-name +@vindex exit-desc +These values should be defined as indexed values, thus: +@example +exit-name[0] = success; +exit-desc[0] = 'Successful program execution.'; +exit-name[1] = failure; +exit-desc[1] = 'The operation failed or command syntax was not valid.'; +@end example +By default, all programs have these effectively defined for them. +They may be overridden by explicitly defining any or all of these values. +Additional names and descriptions may be defined. +They will cause an enumeration to be emitted, like this one +for @code{getdefs}: +@example +typedef enum @{ + GETDEFS_EXIT_SUCCESS = 0, + GETDEFS_EXIT_FAILURE = 1 +@} getdefs_exit_code_t; +@end example +@noindent +which will be augmented by any @code{exit-name} definitions beyond ``1''. + +@item usage-message +@vindex usage-message +This attribute will cause two procedures to be added to the code file: +@code{usage_message} and @code{vusage_message}, with any applicable prefix +(see @code{prefix}, below). They are declared in the +generated header, thus: +@example +extern void vusage_message(char const * fmt, va_list ap); +extern void usage_message(char const * fmt, ...); +@end example +@noindent +These functions print the message to @file{stderr} and invoke the usage +function with the exit code set to @code{1} (@code{EXIT_FAILURE}). + +@item die-code +@vindex die-code +This tells AutoOpts templates to emit code for @code{vdie}, @code{die} and +@code{fserr} functions. If the @code{die-code} is assigned a text value, +then that code will be inserted in the @code{vdie} function immediately +before it prints the death rattle message. + +The profiles for these functions are: +@example +extern void vdie( int exit_code, char const * fmt, va_list); +extern void die( int exit_code, char const * fmt, ...); +extern void fserr(int exit_code, char const * op, char const * fname); +@end example + +@item export +@vindex export +This string is inserted into the .h interface file. Generally used for +global variables or @code{#include} directives required by +@code{flag-code} text and shared with other program text. +Do not specify your configuration header (@file{config.h}) in this +attribute or the @code{include} attribute, however. Instead, use +@code{config-header}, above. + +@item guard-option-names +@vindex guard-option-names +AutoOpts generates macros that presume that there are no @code{cpp} macros +with the same name as the option name. For example, if you have an option +named, @code{debug}, then you must not use @code{#ifdef DEBUG} in your code. +If you specify this attribute, every option name will be guarded. If the name +is @code{#define}-d, then a warning will be issued and the name undefined. +If you do not specify this and there is a conflict, you will get strange +error messages. + +This attribute may be set to any of four recognized states: + +@itemize @bullet +@item +Not defined. AutoOpts will behave as described above. + +@item +Defined, but set to the empty string. Text will be emitted into the header +to undefine (@code{#undef}) any conflicting preprocessor macros. The code +will include compiler warnings (via @code{#warning}). Some compilers are +not ANSI-C-99 compliant yet and will error out on those warnings. You may +compile with @code{-DNO_OPTION_NAME_WARNINGS} to silence or mostly silence +them. + +@item +Defined and set to the string, ``@code{no-warning}''. All of the needed +@code{#undef}s will be emitted, without any conflict checking @code{#warning} +directives emitted. + +@item +Defined and set to the string, ``@code{full-enum}''. The option manipulation +preprocessor macros will not token paste the option names to the index +enumeration prefix. e.g. you will need to use @code{HAVE_OPT(INDEX_OPT_DEBUG)} +instead of @code{HAVE_OPT(DEBUG)}. +@end itemize + +@item include +@vindex include +This string is inserted into the .c file. Generally used for global +variables required only by @code{flag-code} program text. + +@item no-libopts +@vindex no-libopts +If you are going to handle your option processing with the @code{getopt.tpl} +template instead of using libopts, then specify this attribute. It will +suppress mention of @code{--more-help} in the generated documentation. +(@code{getopt_long} does not support @code{--more-help}.) + +@item prefix +@vindex prefix +This value is inserted into @strong{all} global names. This will +disambiguate them if more than one set of options are to be compiled +into a single program. +@end table + +@c +@c = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = +@c +@node presentation attributes +@subsubsection User Presentation Attributes + +Attributes that affect the user's experience. + +@table @samp +@item allow-errors +@vindex allow-errors +The presence of this attribute indicates ignoring any command line +option errors. This may also be turned on and off by invoking the +macros @code{ERRSKIP_OPTERR} and @code{ERRSTOP_OPTERR} from the +generated interface file. + +@item long-opts +@vindex long-opts +@cindex named option mode +Presence indicates GNU-standard long option processing. Partial name +matches are accepted, if they are at least two characters long and the +partial match is unique. The matching is not case sensitive, and the +underscore, hyphen and carat characters are all equivalent (they match). + +If any options do not have an option value (flag character) specified, +and least one does specify such a value, then you must specify +@code{long-opts}. If none of your options specify an option value +(flag character) and you do not specify @code{long-opts}, then command +line arguments are processed in "named option mode". This means that: + +@itemize @bullet +@item +Every command line argument must be a long option. +@item +The flag markers @code{-} and @code{--} are completely optional. +@item +The @code{argument} program attribute is disallowed. +@item +One of the options may be specified as the default +(as long as it has a required option argument). +@end itemize + +@item no-xlate +@vindex no-xlate +Modifies when or whether option names get translated. If provided, +it must be assigned one of these values: +@table @samp +@item opt-cfg +to suppress option name translation for configuration file and and environment +variable processing. +@item opt +to suppress option name translation completely. The usage text will +always be translated if @code{ENABLE_NLS} is defined and you have +translations for that text. +@item anything +Specifies disabling all internationalization support for option code, completely. +@end table +See also the various @code{XLAT} interface entries in the +AutoOpts Programmatic Interface section (@pxref{AutoOpts API}). + +@item reorder-args +@vindex reorder-args +Normally, POSIX compliant commands do not allow for options to be interleaved +with operands. If this is necessary for historical reasons, there are two +approaches available: +@itemize @bullet +@item +Allow @code{optionProcess} to return the index of the operand like it normally +does and process the operand(s). When an operand is encountered that starts +with a hyphen, then set the AutoOpts current index with the @code{RESTART_OPT} +macro (see @pxref{RESTART_OPT}), and re-invoke @code{optionProcess}. This will +also allow you to process the operands in context. + +@item +Specify this attribute. AutoOpts will re-order the command arguments +so that the operands appear (in the original order) at the end of +the argument list. Differing configuration state is not possible +to detect after all options have been processed. +@end itemize + +@item resettable +@vindex resettable +Specifies that the @code{--reset-option} command line option is to be supported. +This makes it possible to suppress any setting that might be found in +a configuration file or environment variable. +@end table + +@node library attributes +@subsection Options for Library Code +@cindex library attributes + +Some libraries provide their own code for processing command line +options, and this may be used by programs that utilize AutoOpts. +You may also wish to write a library that gets configured with AutoOpts +options and config files. Such a library may either supply its own +configury routine and process its own options, or it may export its +option descriptions to programs that also use AutoOpts. This section +will describe how to do all of these different things. + +@menu +* lib and program:: AutoOpt-ed Library for AutoOpt-ed Program +* lib called:: AutoOpt-ed Library for Regular Program +* prog calls lib:: AutoOpt-ed Program Calls Regular Library +@end menu + +@node lib and program +@subsubsection AutoOpt-ed Library for AutoOpt-ed Program + +The library source code must provide an option definition file that consists +of only the attribute @code{library} +@vindex library +and @code{flag} entries. The ``library'' attribute does not need any +associated value, so it will generally appeary by itself on a line folowed +by a semi-colon. The first @code{flag} entry must contain the following +attributes: + +@table @samp +@item name +This name is used in the construction of a global pointer of type +@code{tOptDesc const*}. It is always required. +@item documentation +@vindex documentation +It tells @code{AutoOpts} that this option serves no normal purpose. +It will be used to add usage clarity and to locate option descriptors +in the library code. +@item descrip +This is a string that is inserted in the extended usage display +before the options specific to the current library. It is always required. +@item lib-name +@vindex lib-name +This should match the name of the library. This string is also used in +the construction of the option descriptor pointer name. In the end, it +looks like this: +@example +extern tOptDesc const* <<lib-name>>_<<name>>_optDesc_p; +@end example +@noindent +and is used in the macros generated for the library's @code{.h} file. +@end table + +In order to compile this @code{AutoOpts} using library, you must create a +special header that is not used by the client program. This is accomplished +by creating an option definition file that contains essentially exactly the +following: + +@example +AutoGen definitions options; +prog-name = does-not-matter; // but is always required +prog-title = 'also does not matter'; // also required +config-header = 'config.h'; // optional, but common +library; +#include library-options-only.def +@end example + +@noindent +and nothing else. AutoGen will produce only the @code{.h} file. +You may now compile your library, referencing just this @code{.h} file. +The macros it creates will utilize a global variable that will be defined +by the @code{AutoOpts}-using client program. That program will need to +have the following @code{#include} in @i{its} option definition file: + +@example +#include library-options-only.def +@end example + +@noindent +All the right things will magically happen so that the global variables +named @code{<<lib-name>>_<<name>>_optDesc_p} are initialized correctly. +For an example, please see the @code{AutoOpts} test script: +@file{autoopts/test/library.test}. + +@node lib called +@subsubsection AutoOpt-ed Library for Regular Program + +In this case, your library must provide an option processing function +to a calling program. This is accomplished by setting the @code{allow-errors} +global option attribute. Each time your option handling function is called, +you must determine where your scan is to resume and tell the AutoOpts library +by invoking: + +@example +RESTART_OPT(next_arg_index); +@end example + +@noindent +and then invoke @code{not_opt_index = optionProcess(...)}. +The @code{not_opt_index} value can be used to set @code{optind}, +if that is the global being used to scan the program argument array. + +In this method, do @strong{NOT} utilize the global @code{library} attribute. +Your library must specify its options as if it were a complete program. +You may choose to specify an alternate @code{usage()} function so that +usage for other parts of the option interface may be displayed as well. +See ``Program Information Attributes'' (@pxref{information attributes}). + +At the moment, there is no method for calling @code{optionUsage()} telling +it to produce just the information about the options and not the program +as a whole. Some later revision after somebody asks. + +@node prog calls lib +@subsubsection AutoOpt-ed Program Calls Regular Library + +As with providing an @code{AutoOpt}-ed library to a non-@code{AutoOpt}-ed +program, you must write the option description file as if you were writing +all the options for the program, but you should specify the +@code{allow-errors} global option attribute and you will likely want an +alternate @code{usage()} function (see ``Program Information Attributes'' +@pxref{information attributes}). In this case, though, when +@code{optionProcess()} returns, you need to test to see if there might be +library options. If there might be, then call the library's exported +routine for handling command line options, set the next-option-to-process +with the @code{RESTART_OPT()} macro, and recall @code{optionProcess()}. +Repeat until done. + +@node information attributes +@subsection Program Information Attributes +@cindex information attributes + +These attributes are used to define how and what information is displayed +to the user of the program. + +@table @samp +@item copyright +@vindex copyright +The @code{copyright} is a structured value containing three to five +values. If @code{copyright} is used, then the first three are required. + +@enumerate +@item +@vindex date +@file{date} - the list of applicable dates for the copyright. +@item +@vindex owner +@file{owner} - the name of the copyright holder. +@item +@vindex type +@file{type} - specifies the type of distribution license. +AutoOpts/AutoGen supports the text of the GNU Public License (@file{gpl}), +the GNU ``Lesser'' General Public License with Library extensions +(@file{lgpl}), the Modified Free BSD license (@file{mbsd}) and a few others. +Other licenses may be specified, but you must provide your own license file. +The list of license files provided by AutoOpts may be seen by typing: +@example +ls $(autoopts-config pkgdatadir)/*.lic +@end example +@item +@vindex text +@file{text} - the text of the copyright notice. This must be provided +if @file{type} is set to @file{NOTE}. +@item +@vindex author +@file{author} - in case the author name is to appear in the documentation +and is different from the copyright owner. +@item +@vindex eaddr +@file{eaddr} - email address for receiving praises and complaints. +Typically that of the author or copyright holder. +@end enumerate +@* +An example of this might be: +@example +copyright = @{ + date = "1992-2012"; + owner = "Bruce Korb"; + eaddr = 'bkorb@@gnu.org'; + type = GPL; +@}; +@end example + +@item detail +@vindex detail +This string is added to the usage output when the HELP option is +selected. + +@item explain +@vindex explain +Gives additional information whenever the usage routine is invoked. + +@item package +@vindex package +The name of the package the program belongs to. This will appear +parenthetically after the program name in the version and usage output, +e.g.: @code{autogen @i{(GNU autogen)} - The Automated Program Generator}. + +@item preserve-case +@vindex preserve-case +This attribute will not change anything except appearance. Normally, the +option names are all documented in lower case. However, if you specify this +attribute, then they will display in the case used in their specification. +Command line options will still be matched without case sensitivity. +This is useful for specifying option names in camel-case. + +@item prog-desc @strong{and} +@itemx opts-ptr +@vindex prog-desc +@vindex opts-ptr +These define global pointer variables that point to the program +descriptor and the first option descriptor for a library option. This +is intended for use by certain libraries that need command line and/or +initialization file option processing. These definitions have no effect +on the option template output, but are used for creating a library +interface file. Normally, the first "option" for a library will be a +documentation option that cannot be specified on the command line, but +is marked as @code{settable}. The library client program will invoke the +@code{SET_OPTION} macro which will invoke a handler function that will +finally set these global variables. + +@item usage +@vindex usage +Optionally names the usage procedure, if the library routine +@code{optionUsage()} does not work for you. If you specify +@code{my_usage} as the value of this attribute, for example, you will +use a procedure by that name for displaying usage. Of course, you will +need to provide that procedure and it must conform to this profile: +@example +void @i{my_usage}( tOptions* pOptions, int exitCode ) +@end example + +@item gnu-usage +@vindex gnu-usage +Normally, the default format produced by the @code{optionUsage} procedure +is @i{AutoOpts Standard}. By specifying this attribute, the default format +will be @i{GNU-ish style}. Either default may be overridden by the user with +the @code{AUTOOPTS_USAGE} environment variable. If it is set to @code{gnu} +or @code{autoopts}, it will alter the style appropriately. This attribute +will conflict with the @code{usage} attribute. + +@item reorder-args +@vindex reorder-args +Some applications traditionally require that the command operands be +intermixed with the command options. In order to handle that, the arguments +must be reordered. If you are writing such an application, specify this +global option. All of the options (and any associated option arguments) +will be brought to the beginning of the argument list. New applications +should not use this feature, if at all possible. This feature is +@i{disabled} if @code{POSIXLY_CORRECT} is defined in the environment. +@end table + +@node Generated main +@subsection Generating main procedures +@cindex main procedure + +When AutoOpts generates the code to parse the command line options, it has +the ability to produce any of several types of @code{main()} procedures. +This is done by specifying a global structured value for +@vindex main +@code{main}. The values that it contains are dependent on the value set for +the one value it must have: @code{main-type}. + +@vindex main-type +The recognized values for @code{main-type} are: +@menu +* main guile:: guile: main and inner_main procedures +* main shell-process:: shell-process: emit Bourne shell results +* main shell-parser:: shell-parser: emit Bourne shell script +* main main:: main: user supplied main procedure +* main include:: include: code emitted from included template +* main invoke:: invoke: code emitted from AutoGen macro +* main for-each:: for-each: perform function on each argument +@end menu + +Here is an example of an @code{include} variation: + +@example +main = @{ + main-type = include; + tpl = "main-template.tpl"; +@}; +@end example + +@node main guile +@subsubsection guile: main and inner_main procedures + +When the @code{main-type} is specified to be @code{guile}, +a @code{main()} procedure is generated that calls @code{gh_enter()}, providing +it with a generated @code{inner_main()} to invoke. If you must perform +certain tasks before calling @code{gh_enter()}, you may specify such code +in the value for the +@vindex before-guile-boot +@code{before-guile-boot} attribute. + +The @code{inner_main()} procedure itself will process the command line +arguments (by calling @code{optionProcess()}, +@pxref{libopts-optionProcess}), and then either invoke the code +specified with the +@vindex guile-main +@code{guile-main} attribute, or else export the parsed options to Guile +symbols and invoke the @code{scm_shell()} function from the Guile library. +This latter will render the program nearly identical to the stock +@code{guile(1)} program. + +@node main shell-process +@subsubsection shell-process: emit Bourne shell results + +This will produce a @code{main()} procedure that parses the command line +options and emits to @file{stdout} Bourne shell commands that puts the +option state into environment variables. This can be used within a +shell script as follows: + +@example +unset OPTION_CT +eval "`opt_parser \"$@@\"`" +test -z "$@{OPTION_CT@}" && exit 1 +test $@{OPTION_CT@} -gt 0 && shift $@{OPTION_CT@} +@end example + +If the option parsing code detects an error or a request for usage, +it will not emit an assignment to OPTION_CT and the script should just +exit. If the options are set consistently, then something along the +lines of the following will be written to @file{stdout} and evaled: + +@example + OPTION_CT=4 + export OPTION_CT + MYPROG_SECOND='first' + export MYPROG_SECOND + MYPROG_ANOTHER=1 # 0x1 + export MYPROG_ANOTHER +@end example + +@noindent +If the arguments are to be reordered, however, then the resulting set +of operands will be emitted and @code{OPTION_CT} gets set to zero. +For example, the following would be appended to the above: + +@example + set -- 'operand1' 'operand2' 'operand3' + OPTION_CT=0 +@end example + +@noindent +@code{OPTION_CT} is set to zero since it is not necessary to shift +off any options. + +@node main shell-parser +@subsubsection shell-parser: emit Bourne shell script + +This will produce a @code{main()} procedure that emits a shell script +that will parse the command line options. That script can be emitted +to @file{stdout} or inserted or substituted into a pre-existing shell +script file. Improbable markers are used to identify previously inserted +parsing text: + +@example +# # # # # # # # # # -- do not modify this marker -- +@end example + +@noindent +The program is also pretty insistent upon starting its parsing script +on the second line. + +@node main main +@subsubsection main: user supplied main procedure + +You must supply a value for the @code{main-text} attribute. +You may also supply a value for +@vindex option-code +@code{option-code}. If you do, then the @code{optionProcess} invocation +will not be emitted into the code. AutoOpts will wrap the @code{main-text} +inside of: + +@example +int +main( int argc, char** argv ) +@{ + @{ // replaced by option-code, if that exists + int ct = optionProcess( &<<prog-name>>Options, argc, argv ); + argc -= ct; + argv += ct; + @} +<<your main-text goes here>> +@} +@end example + +@noindent +so you can most conveniently set the value with a ``@code{here string}'' +(@pxref{here-string}): + +@example +code = <<- _EndOfMainProc_ + <<your text goes here>> + _EndOfMainProc_; +@end example + +@node main include +@subsubsection include: code emitted from included template + +You must write a template to produce your main procedure. +You specify the name of the template with the @code{tpl} attribute +and it will be incorporated at the point where AutoOpts is ready +to emit the @code{main()} procedure. + +This can be very useful if, in your working environment, you have +many programs with highly similar @code{main()} procedures. All you need +to do is parameterize the variations and specify which variant is needed +within the @code{main} AutoOpts specification. Since you are coding +the template for this, the attributes needed for this variation would +be dictated by your template. + +@node main invoke +@subsubsection invoke: code emitted from AutoGen macro + +You must write a template to produce your main procedure. That template +must contain a definition for the function specified with the @code{func} +attribute to this @code{main()} procedure specification. Typically, this +template will be incorporated by using the @code{--lib-template} option +(@pxref{autogen lib-template}) in the AutoGen invocation. Otherwise, this +variation operates in much the same way as ``@code{include}'' +(@pxref{main include}) method. + +@node main for-each +@subsubsection for-each: perform function on each argument + +This produces a main procedure that invokes a procedure once for each operand +on the command line (non-option arguments), @strong{OR} once for each +non-blank, non-comment @code{stdin} input line. Leading and trailing white +space is trimmed from the input line and comment lines are lines that are +empty or begin with a comment character, defaulting to a hash ('#') character. + +@strong{NB}: +The @code{argument} program attribute (@pxref{program attributes}) +must begin with the @code{[} character, to indicate that there are +command operands, but that they are optional. + +There are a number of attributes to @code{main} that may be used: + +@table @code +@item handler-proc +@vindex handler-proc +This attribute is required. It is used to name the procedure to call. +That procedure is presumed to be external, but if you provide the code +for it, then the procedure is emitted as a static procedure in the +generated code. + +This procedure should return 0 on success, a cumulative error code on warning +and exit without returning on an unrecoverable error. As the cumulative +warning codes are @i{or}-ed together, the codes should be some sort of bit +mask in order to be ultimately decipherable (if you need to do that). + +If the called procedure needs to cause a fail-exit, it is expected to call +@code{exit(3)} directly. If you want to cause a warning exit code, then this +handler function should return a non-zero status. That value will be +@strong{OR}-ed into a result integer for computing the final exit code. E.g., +here is part of the emitted code: + +@example + int res = 0; + if (argc > 0) @{ + do @{ + res |= @i{my_handler}( *(argv++) ); + @} while (--argc > 0); + @} else @{ ... +@end example + +@item handler-type +@vindex handler-type +If you do not supply this attribute, your handler procedure must be +the default type. The profile of the procedure must be: + +@example +int @i{my_handler}( char const *pz_entry ); +@end example + +@noindent +However, if you do supply this attribute, you may set the value to any of +four alternate flavors: + +@table @samp +@item name-of-file +This is essentially the same as the default handler type, except that before +your procedure is invoked, the generated code has verified that the string +names an existing file. The profile is unchanged. + +@item file-X +Before calling your procedure, the file is f-opened according to the ``X'', +where ``X'' may be any of the legal modes for @code{fopen(3C)}. In this case, +the profile for your procedure must be: + +@example +int @i{my_handler}( char const* pz_fname, FILE* entry_fp ); +@end example + +@item text-of-file +@itemx some-text-of-file +Before calling your procedure, the contents of the file are read or mapped into memory. +(Excessively large files may cause problems.) The @samp{some-text-of-file} +disallows empty files. Both require regular files. In this case, the profile +for your procedure must be: + +@example +program_exit_code_t +@i{my_handler}(char const* pz_fname, char* file_text, + size_t text_size); +@end example + +@noindent +Note that though the @code{file_text} is not @code{const}, any changes made to +it are not written back to the original file. It is merely a memory image of +the file contents. Also, the memory allocated to hold the text is +@code{text_size + 1} bytes long and the final byte is always @code{NUL}. +The file contents need not be text, as the data are read with the @code{read(2)} +system call. +@end table + +If you select one of these file type handlers, then on access or usage errors +the @code{PROGRAM_EXIT_FAILURE} exit code will, by default, be or-ed +into the final exit code. This can be changed by specifying the +global @code{file-fail-code} attribute and naming a different value. +That is, something other than @code{failure}. You may choose @code{success}, +in which case file access issues will not affect the exit code and the error +message will not be printed. + +@item @i{my_handler}-code +@vindex MYHANDLER-code +With this attribute, you provide the code for your handler procedure +in the option definition file. In this case, your @code{main()} +procedure specification might look something like this: + +@example +main = @{ + main-type = for-each; + handler-proc = @i{my_handler}; + @i{my_handler}-code = <<- EndOfMyCode + /* whatever you want to do */ + EndOfMyCode; +@}; +@end example + +@noindent +and instead of an emitted external reference, a procedure will be emitted +that looks like this: + +@example +static int +@i{my_handler}( char const* pz_entry ) +@{ + int res = 0; + <<@i{my_handler}-code goes here>> + return res; +@} +@end example + +@item main-init +@vindex main-init +This is code that gets inserted after the options have been processed, but +before the handler procs get invoked. + +@item main-fini +@vindex main-fini +This is code that gets inserted after all the entries have been processed, +just before returning from @code{main()}. + +@item comment-char +@vindex comment-char +If you wish comment lines to start with a character other than a hash +(@code{#}) character, then specify one character with this attribute. +If that character is the @code{NUL} byte, then only blank lines will be +considered comments. +@end table + +@node option attributes +@subsection Option Attributes +@cindex option attributes + +For each option you wish to specify, you must have a block macro named +@code{flag} defined. There are two required attributes: @code{name} and +@code{descrip}. If any options do not have a @code{value} (traditional flag +character) attribute, then the @code{long-opts} program attribute must also +be defined. As a special exception, if no options have a @code{value} +@strong{and} @code{long-opts} is not defined @strong{and} @code{argument} is +not defined, then all arguments to the program are named options. In this +case, the @code{-} and @code{--} command line option markers are optional. + +@menu +* Required Attributes:: Required Attributes +* Common Attributes:: Common Option Attributes +* Immediate Action:: Immediate Action Attributes +* Option Conflict Attributes:: Option Conflict Attributes + +These option attributes do not fit well with the above categories. + +* opt-attr settable:: Program may set option +* opt-attr no-preset:: Option cannot be pre-configured +* opt-attr equivalence:: Option Equivalence Class +* opt-attr aliases:: Option Aliasing +* opt-attr default option:: Default Option +* opt-attr documentation:: Option Sectioning Comment +* opt-attr translators:: Translator Notes +@end menu + +@node Required Attributes +@subsubsection Required Attributes +@cindex Required Attributes + +Every option must have exactly one copy of both of these attributes. + +@table @samp +@item name +@vindex name +Long name for the option. Even if you are not accepting long options +and are only accepting flags, it must be provided. AutoOpts generates +private, named storage that requires this name. This name also causes +a @code{#define}-d name to be emitted. It must not conflict with any +other names you may be using in your program. + +For example, if your option name is, @code{debug} or @code{munged-up}, +you must not use the @code{#define} names @code{DEBUG} (or +@code{MUNGED_UP}) in your program for non-AutoOpts related purposes. +They are now used by AutoOpts. + +Sometimes (most especially under Windows), you may get a surprise. +For example, @code{INTERFACE} is apparently a user space name that +one should be free to use. Windows usurps this name. To solve this, +you must do one of the following: + +@enumerate +@item +Change the name of your option +@item +add the program attribute (@pxref{program attributes}): + +@example +export = '#undef INTERFACE'; +@end example +@item +add the program attribute: + +@example +guard-option-names; +@end example +@end enumerate + +@item descrip +@vindex descrip +Except for documentation options, a @strong{very} brief description of the +option. About 40 characters on one line, maximum, not counting any texinfo +markups. Texinfo markups are stripped before printing in the usage text. It +appears on the @code{usage()} output next to the option name. + +If, however, the option is a documentation option, it will appear on one or +more lines by itself. It is thus used to visually separate and comment upon +groups of options in the usage text. +@end table + +@node Common Attributes +@subsubsection Common Option Attributes +@cindex Common Option Attributes + +These option attributes are optional. Any that do appear in the +definition of a flag, may appear only once. + +@table @samp +@item value +@vindex value +The flag character to specify for traditional option flags, e.g., @code{-L}. + +@item max +@vindex max +Maximum occurrence count (invalid if @var{disable} present). +The default maximum is 1. @code{NOLIMIT} can be used for the value, +otherwise it must be a number or a @code{#define} that evaluates to a number. + +@item min +@vindex min +Minimum occurrence count. If present, then the option @strong{must} +appear on the command line. Do not define it with the value zero (0). + +@item must-set +@vindex must-set +If an option must be specified, but it need not be specified on +the command line, then specify this attribute for the option. + +@item deprecated +@vindex deprecated +There are two effects to this attribute: the usage text will not +show the option, and the generated documentation will mark it with: +``@emph{NOTE: THIS OPTION IS DEPRECATED}''. + +@item disable +@vindex disable +Prefix for disabling (inverting sense of) the option. Only useful +if long option names are being processed. When an option has this +attribute, the test @code{ENABLED_OPT(OPTNAME)} is false when either +of the following is true: +@itemize @bullet +@item +The option has not been specified and the @code{enable} attribute has +not been specified. +@item +The option has been specified with this disabling prefix. +@end itemize +To detect that the option has been specified with the disabling +prefix, you must use: +@example +HAVE_OPT(OPTNAME) && ! ENABLED_OPT(OPTNAME) +@end example + +@item enable +@vindex enable +Long-name prefix for enabling the option (invalid if @var{disable} +@strong{not} present). Only useful if long option names are being +processed. + +@item enabled +@vindex enabled +If default is for option being enabled. (Otherwise, the OPTST_DISABLED +bit is set at compile time.) Only useful if the option can be disabled. + +@item ifdef +@itemx ifndef +@itemx omitted-usage +@vindex ifdef +@vindex ifndef +@vindex omitted-usage +If an option is relevant on certain platforms or when certain features +are enabled or disabled, you can specify the compile time flag used +to indicate when the option should be compiled in or out. For example, +if you have a configurable feature, @code{mumble} that is indicated +with the compile time define, @code{WITH_MUMBLING}, then add: + +@example +ifdef = WITH_MUMBLING; +@end example + +@noindent +Take care when using these. There are several caveats: + +@itemize @bullet +@item +The case and spelling must match whatever is specified. +@item +Do not confuse these attributes with the AutoGen directives of the +same names, @xref{Directives}. These cause C preprocessing directives +to be inserted into the generated C text. +@item +Only one of @code{ifdef} and @code{ifndef} may apply to any one option. +@item +The @code{VALUE_OPT_} values are @code{#define}-d. If @code{WITH_MUMBLING} +is not defined, then the associated @code{VALUE_OPT_} value will not be +@code{#define}-d either. So, if you have an option named, @code{MUMBLING} +that is active only if @code{WITH_MUMBLING} is @code{#define}-d, then +@code{VALUE_OPT_MUMBLING} will be @code{#define}-d iff @code{WITH_MUMBLING} +is @code{#define}-d. Watch those switch statements. +@item +If you specify @code{omitted-usage}, then the option will be recognized +as disabled when it is configured out of the build, but will yield the +message, ``This option has been disabled.'' You may specify an alternate +message by giving @code{omitted-usage} a string value. e.g.: +@example +omitted-usage = 'you cannot do this'; +@end example +@end itemize + +@item no-command +@vindex no-command +This option specifies that the option is not allowed on the command line. +Such an option may not take a @code{value} (flag character) attribute. +The program must have the @code{homerc} (@pxref{program attributes}) option set. +@end table + +@node Immediate Action +@subsubsection Immediate Action Attributes +@cindex immediate action + +Certain options may need to be processed early. For example, in order to +suppress the processing of configuration files, it is necessary to process the +command line option @code{--no-load-opts} @strong{before} the config files are +processed. To accommodate this, certain options may have their enabled or +disabled forms marked for immediate processing. The consequence of this is +that they are processed ahead of all other options in the reverse of normal +order. + +Normally, the first options processed are the options specified in the first +@code{homerc} file, followed by then next @code{homerc} file through to the +end of config file processing. Next, environment variables are processed and +finally, the command line options. The later options override settings +processed earlier. That actually gives them higher priority. Command line +immediate action options actually have the lowest priority of all. They would +be used only if they are to have an effect on the processing of subsequent +options. + +@table @samp +@item immediate +@vindex immediate +Use this option attribute to specify that the enabled form of the option +is to be processed immediately. The @code{help} and @code{more-help} +options are so specified. They will also call @code{exit()} upon +completion, so they @strong{do} have an effect on the processing +of the remaining options :-). + +@item immed-disable +@vindex immed-disable +Use this option attribute to specify that the disabled form of the +option is to be processed immediately. The @code{load-opts} option is +so specified. The @code{--no-load-opts} command line option will +suppress the processing of config files and environment variables. +Contrariwise, the @code{--load-opts} command line option is +processed normally. That means that the options specified in that file +will be processed after all the @code{homerc} files and, in fact, after +options that precede it on the command line. + +@item also +If either the @code{immediate} or the @code{immed-disable} attributes +are set to the string, ``@code{also}'', then the option will actually be +processed twice: first at the immediate processing phase and again +at the ``normal'' time. +@end table + +@node Option Conflict Attributes +@subsubsection Option Conflict Attributes +@cindex Option Conflict Attributes + +These attributes may be used as many times as you need. +They are used at the end of the option processing to verify +that the context within which each option is found does not +conflict with the presence or absence of other options. + +This is not a complete cover of all possible conflicts and +requirements, but it simple to implement and covers the +more common situations. + +@table @samp +@cindex flags-must +@item flags-must +one entry for every option that @strong{must} be present +when this option is present + +@cindex flags-cant +@item flags-cant +one entry for every option that @strong{cannot} be present +when this option is present +@end table + +@node opt-attr settable +@subsubsection Program may set option +@vindex settable +If the option can be set outside of option processing, specify +``@code{settable}''. If this attribute is defined, special macros for setting +this particular option will be inserted into the interface file. For example, +@code{TEMPL_DIRS} is a settable option for AutoGen, so a macro named +@code{SET_OPT_TEMPL_DIRS(a)} appears in the interface file. This attribute +interacts with the @var{documentation} attribute. + +@node opt-attr no-preset +@subsubsection Option cannot be pre-configured +@vindex no-preset +@cindex configuration file +If presetting this option is not allowed, specify ``@code{no-preset}''. +(Thus, environment variables and values set in configuration files will be +ignored.) + +@node opt-attr equivalence +@subsubsection Option Equivalence Class +@vindex equivalence +Generally, when several options are mutually exclusive and basically serve the +purpose of selecting one of several processing modes, specify the +``@code{equivalence}'' attribute. These options will be considered an +equivalence class. Sometimes, it is just easier to deal with them as such. +All members of the equivalence class must contain the same equivalenced-to +option, including the equivalenced-to option itself. Thus, it must be a class +member. + +For an option equivalence class, there is a single occurrence counter for +the class. It can be referenced with the interface macro, +@code{COUNT_OPT(BASE_OPTION)}, where ``BASE_OPTION'' is the equivalenced-to +option name. + +Also, please take careful note: since the options are mapped to the +equivalenced-to option descriptor, any option argument values are mapped to +that descriptor also. Be sure you know which ``equivalent option'' was +selected before getting an option argument value! + +During the presetting phase of option processing (@pxref{Presetting +Options}), equivalenced options may be specified. However, if different +equivalenced members are specified, only the last instance will be +recognized and the others will be discarded. A conflict error is indicated +only when multiple different members appear on the command line itself. + +As an example of where equivalenced options might be useful, @code{cpio(1)} +has three options @code{-o}, @code{-i}, and @code{-p} that define the +operational mode of the program (@code{create}, @code{extract} and +@code{pass-through}, respectively). They form an equivalence class from +which one and only one member must appear on the command line. If +@code{cpio} were an AutoOpt-ed program, then each of these option +definitions would contain: + +@example +equivalence = create; +@end example + +and the program would be able to determine the operating mode +with code that worked something like this: + +@example +switch (WHICH_IDX_CREATE) @{ +case INDEX_OPT_CREATE: ... +case INDEX_OPT_EXTRACT: ... +case INDEX_OPT_PASS_THROUGH: ... +default: /* cannot happen */ +@} +@end example + +@node opt-attr aliases +@subsubsection Option Aliasing + +Sometimes, for backwards compatibility or tradition or just plain convenience, +it works better to define one option as a pure alias for another option. +For such situations, provide the following pieces of information: +@example +flag = @{ + name = @i{aliasing-option-name}; + value = @i{aliasing-flag-char}; // optional ! + aliases = @i{aliased-to-option}; +@}; +@end example +Do not provide anything else. The usage text for such an option will be: +@example + This is an alias for @i{aliased-to-option} +@end example + +@node opt-attr default option +@subsubsection Default Option +@vindex default +If your program processes its arguments in named option mode (See +@code{long-opts} in @ref{program attributes}), then you may select +@strong{one} of your options to be the default option. Do so by using +attribute @code{default} with one of the options. The option so specified +must have an @code{arg-type} (@pxref{Option Arguments}) specified, but not the +@code{arg-optional} (@pxref{arg-optional}) attribute. That is to say, the +option argument must be required. + +If you have done this, then any arguments that do not match an option name and +do not contain an equal sign (@code{=}) will be interpreted as an option +argument to the default option. + +@node opt-attr documentation +@subsubsection Option Sectioning Comment +This attribute means the option exists for the purpose of separating option +description text in the usage output and texi documentation. Without this +attribute, every option is a separate node in the texi docs. With this +attribute, the documentation options become texi doc nodes and the options are +collected under them. Choose the name attribute carefully because it will +appear in the texi documentation. + +Libraries may also choose to make it settable so that the library can +determine which command line option is the first one that pertains to the +library. + +@vindex documentation +If the @samp{documentation} attribute is present, then all other +attributes are disabled except @code{settable}, @code{call-proc} and +@code{flag-code}. @code{settable} must be and is only specified if +@code{call-proc}, @code{extract-code} or @code{flag-code} has been specified. +When present, the @code{descrip} attribute will be displayed only when the +@code{--help} option has been specified. It will be displayed flush to the +left hand margin and may consist of one or more lines of text, filled to 72 +columns. + +The name of the option will not be printed in the help text. It @i{will}, +however, be printed as section headers in the texi documentation. If the +attribute is given a non-empty value, this text will be reproduced in the man +page and texi doc immediately after the @code{descrip} text. + +@node opt-attr translators +@subsubsection Translator Notes +@vindex translators +If you need to give the translators a special note about a particular option, +please use the ``@code{translators}'' attribute. The attribute text will be +emitted into the generated @code{.c} text where the option related strings get +defined. To make a general comment about all of the option code, add comments +to an @code{include} attribute (@pxref{program attributes}). Do @strong{not} +use this attribute globally, or it will get emitted into every option +definition block. + +@node Option Arguments +@subsection Option Argument Specification +@cindex Option Arguments + +Command line options come in three flavors: options that do not +take arguments, those that do and those that may. Without an +"arg-type" attribute, AutoOpts will not process an argument to an +option. If "arg-type" is specified and "arg-optional" is also +specified, then the next command line token will be taken to +be an argument, unless it looks like the name of another option. + +If the argument type is specified to be anything other than "str[ing]", then +AutoOpts will specify a callback procedure to handle the argument. Some of +these procedures will be created and inserted into the generated @code{.c} +file, and others are already built into the @file{libopts} library. +Therefore, if you write your own callback procedure +(@pxref{Option Argument Handling}), then you must either not specify an +"arg-type" attribute, or else specify it to be of type "str[ing]". Your +callback function will be able to place its own restrictions on what that +string may contain or represent. + +Option argument handling attributes depend upon the value set for the +@vindex arg-type +@code{arg-type} attribute. It specifies the type of argument the option +will take. If not present, the option cannot take an argument. If present, +it must be an entry in the following table. The first three letters is +sufficient. + +@menu +* arg-type string:: Arg Type String +* arg-type number:: Arg Type Number +* arg-type boolean:: Arg Type Boolean +* arg-type keyword:: Arg Type Keyword +* arg-type set membership:: Arg Type Set Membership +* arg-type hierarchy:: Arg Type Hierarchical +* arg-type file name:: Arg Type File Name +* arg-type time-duration:: Arg Type Time Duration +* arg-type time-date:: Arg Type Time and Date + +Supporting attributes for particular argument types: + +* arg-keyword:: Keyword list +* arg-optional:: Option Argument Optional +* arg-default:: Default Option Argument Value +@end menu + +@node arg-type string +@subsubsection Arg Type String +@code{arg-type = string;} + +The argument may be any arbitrary string, though your program or option +callback procedure may place additional constraints upon it. + + +@node arg-type number +@subsubsection Arg Type Number +@code{arg-type = number;} + +The argument must be a correctly formed integer, without any trailing U's or +L's. AutoOpts contains a library procedure to convert the string to a number. +If you specify range checking with @code{arg-range} (see below), then AutoOpts +produces a special purpose procedure for this option. + +@table @samp +@item scaled +@vindex scaled +@code{scaled} marks the option so that suffixes of @samp{k}, @samp{K}, +@samp{m}, @samp{M}, @samp{g}, @samp{G}, @samp{t}, and @samp{T} will multiply +the given number by a power of 1000 or 1024. Lower case letters scale by a +power of 1000 and upper case scale by a power of 1024. + +@item arg-range +@vindex arg-range +@code{arg-range} is used to create a callback procedure for validating the +range of the option argument. It must match one of the range entries. Each +@code{arg-range} should consist of either an integer by itself or an integer +range. The integer range is specified by one or two integers separated by the +two character sequence, @code{->}. Be sure to quote the entire range string. +The definitions parser will not accept the range syntax as a single string +token. + +The generated procedure imposes the range constraints as follows: +@itemize @bullet +@item +A number by itself will match that one value. +@item +The high end of the range may not be @code{INT_MIN}, both for obvious +reasons and because that value is used to indicate a single-valued match. +@item +An omitted lower value implies a lower bound of INT_MIN. +@item +An omitted upper value implies a upper bound of INT_MAX. +@item +The argument value is required. It may not be optional. +@item +The value must match one of the entries. If it can match more than one, +then you have redundancies, but no harm will come of it. +@end itemize +@end table + + +@node arg-type boolean +@subsubsection Arg Type Boolean +@code{arg-type = boolean;} + +The argument will be interpreted and always yield either AG_TRUE or +AG_FALSE. False values are@: the empty string, the number zero, or a +string that starts with @code{f}, @code{F}, @code{n} or @code{N} +(representing False or No). Anything else will be interpreted as True. + + +@node arg-type keyword +@subsubsection Arg Type Keyword +@code{arg-type = keyword;} + +The argument must match a specified list of strings (@pxref{arg-keyword}). +Assuming you have named the option, @code{optn-name}, the strings will be +converted into an enumeration of type @code{te_Optn_Name} with the values +@code{OPTN_NAME_KEYWORD}.* If you have @strong{not} specified a default value, +the value @code{OPTN_NAME_UNDEFINED} will be inserted with the value zero. +The option will be initialized to that value. You may now use this in your +code as follows: + +@example +te_Optn_Name opt = OPT_VALUE_OPTN_NAME; +switch (opt) @{ +case OPTN_NAME_UNDEFINED: /* undefined things */ break; +case OPTN_NAME_KEYWORD: /* `keyword' things */ break; +default: /* utterly impossible */ ; +@} +@end example + +AutoOpts produces a special purpose procedure for this option. +You may not specify an alternate handling procedure. + +If you have need for the string name of the selected keyword, you +may obtain this with the macro, @code{OPT_OPTN_NAME_VAL2STR(val)}. +The value you pass would normally be @code{OPT_VALUE_OPTN_NAME}, +but anything with numeric value that is legal for @code{te_Optn_Name} +may be passed. Anything out of range will result in the string, +@code{"*INVALID*"} being returned. The strings are read only. +It may be used as in: + +@example +te_Optn_Name opt = OPT_VALUE_OPTN_NAME; +printf( "you selected the %s keyword\n", + OPT_OPTN_NAME_VAL2STR(opt) ); +@end example + +* Note: you may replace the @code{OPTN_NAME} enumeration prefix with +another prefix by specifying a +@vindex prefix-enum +@code{prefix-enum} attribute. + +Finally, users may specify the argument either by name or by number. +Since the numeric equivalents change by having new entries inserted +into the keyword list, this would not be a recommended practice. +However, either @code{-1} or @code{~0} will always be equivalent to +specifying the last keyword. + +@node arg-type set membership +@subsubsection Arg Type Set Membership +@code{arg-type = set;} + +The argument must be a list of names each of which must match the strings +"@code{all}", "@code{none}" or one of the keywords (@pxref{arg-keyword}) +specified for this option. @code{all} will turn on all membership bits and +@code{none} will turn them all off. Specifying one of the keywords will turn +on the corresponding set membership bit. Literal numbers may also be used and +may, thereby, set or clear more than one bit. Preceding a keyword or literal +number with a bang (@code{!} - exclamation point) will turn the bit(s) off. +The number of keywords allowed is constrained by the number of bits in a +pointer, as the bit set is kept in a @code{void*}. + +If, for example, you specified @code{first} in your list of keywords, +then you can use the following code to test to see if either @code{first} +or @code{all} was specified: + +@example +uintptr_t opt = OPT_VALUE_OPTN_NAME; +if (opt & OPTN_NAME_FIRST) + /* OPTN_NAME_FIRST bit was set */ ; +@end example + +AutoOpts produces a special purpose procedure for this option. +To set multiple bits as the default (initial) value, you must +specify an initial numeric value (which might become inaccurate over +time), or else specify @code{arg-default} multiple times. Do not +specify a series of names conjoined with @code{+} symbols as the +value for any of the @code{arg-default} attributes. That works for +option parsing, but not for the option code generation. + +@node arg-type hierarchy +@subsubsection Arg Type Hierarchical +@code{arg-type = hierarchy;} +@* +@code{arg-type = nested;} + +This denotes an option with a structure-valued argument, a.k.a. +``subopts'' in @code{getopts} terminology. The argument is parsed +and the values made available to the program via the find and +find next calls (@xref{libopts-optionFindValue}, +@xref{libopts-optionGetValue}, and +@pxref{libopts-optionFindNextValue}). + +@example +tOptionValue * val = optionGetValue(VALUE_OPT_OPTN_NAME, "name"); +while (val != NULL) @{ + process(val); + val = optionNextValue(VALUE_OPT_OPTN_NAME, val); + if (wrong_name(val, "name")) + break; +@} +@end example + + +@node arg-type file name +@subsubsection Arg Type File Name +@code{arg-type = file;} + +This argument type will have some validations on the argument and, +optionally, actually open the file. You must specify several additonal +attributes for the option: + +@table @samp +@item file-exists +@vindex file-exists +If not specified or empty, then the directory portion of the name is checked. +The directory must exist or the argument is rejected and the usage procedure +is invoked. + +Otherwise, both the directory as above and the full name is tested for +existence. If the value begins with the two letters ``no'', then the file +must not pre-exist. Otherwise, the file is expected to exist. + +@item open-file +@vindex open-file +If not specified or empty, the file is left alone. +If the value begins with the four letters ``desc''[@i{riptor}], then +@code{open(2)} is used and @code{optArg.argFd} is set. Otherwise, the +file is opened with @code{fopen} and @code{optArg.argFp} is set. + +@item file-mode +@vindex file-mode +If ``open-file'' is set and not empty, then you must specify the open mode. +Set the value to the flag bits or mode string as appropriate for the open +type. +@end table + + +@node arg-type time-duration +@subsubsection Arg Type Time Duration +@code{arg-type = time-duration;} + +The argument will be converted into a number of seconds. It may be +a multi-part number with different parts being multiplied into a seconds +value and added into the final result. Valid forms are in the table +below. Upper cased letters represent numbers that must be used in the +expressions. + +@table @samp +@item [[HH:]MM:]SS +@code{HH} is multiplied by @code{3600} and @code{MM} multiplied by @code{60} +before they are added to @code{SS}. This time specification may not be +followed by any other time specs. @code{HH} and @code{MM} are both optional, +though @code{HH} cannot be specified without @code{MM}. + +@item DAYS d +@code{DAYS} is multiplied by the number of seconds in a day. This value may +be followed by (and added to) values specified by @code{HH:MM:SS} or the +suffixed values below. If present, it must always be first. + +@item HRS h +@code{HRS} is multiplied by the number of seconds in an hour. This value may +be followed by (and added to) values specified by @code{MM:SS} or the +suffixed values below. + +@item MINS m +@code{MINS} is multiplied by the number of seconds in a minute. This value may +be followed by (and added to) a count of seconds. + +@item SECS s +This value can only be the last value in a time specification. The @code{s} +suffix is optional. +@end table + +@example + 5 d 1:10:05 ==> 5 days + 1 hour 10 minutes and 5 seconds + 5 d 1 h 10 m 5 ==> yields: 436205 seconds + 5d1h10m5s ==> same result -- spaces are optional. +@end example + +When saved into a config file, the value will be stored as a simple count +of seconds. There are actually more (many) accepted time duration strings. +The full documentation can be found with ISO-8601 documentation and the +more extedded documentation when ``parse_duration()'' becomes more widely +available. + + +@node arg-type time-date +@subsubsection Arg Type Time and Date +@code{arg-type = time-date;} + +The argument will be converted into the number of seconds since the epoch. +The conversion rules are very complicated, please see the @file{getdate_r(3GNU)} +man page. There are some additional restrictions: + +@enumerate +@item +Your project must be compiled with @code{PKGDATADIR} defined and naming a +valid directory. +@item +The @code{DATEMSK} environment variable will be set to the @file{datemsk} file +within that directory. +@end enumerate + +If that file is not accessible for any reason, the string will be +parsed as a time duration (@pxref{arg-type time-duration}) instead of a +specific date and time. + +@node arg-keyword +@subsubsection Keyword list +@vindex keyword +If the @code{arg-type} is @code{keyword} (@pxref{arg-type keyword}) or +@code{set-membership} (@pxref{arg-type set membership}), then you must specify +the list of keywords by a series of @code{keyword} entries. The interface +file will contain values for @code{@i{<OPTN_NAME>}_@i{<KEYWORD>}} for each +keyword entry. @code{keyword} option types will have an enumeration and +@code{set-membership} option types will have a set of unsigned bits +@code{#define}-d. + +If the @code{arg-type} is specifically @code{keyword}, you may also add +special handling code with a +@vindex extra-code +@code{extra-code} attribute. After @code{optionEnumerationVal} has +converted the input string into an enumeration, you may insert code to +process this enumeration value (@code{pOptDesc->optArg.argEnum}). + +@node arg-optional +@subsubsection Option Argument Optional +@vindex arg-optional +This attribute indicates that the user does not have to supply an argument for +the option. This is only valid if the @var{arg-type} is @code{string} +(@pxref{arg-type string}) or @code{keyword} (@pxref{arg-type keyword}). If it +is @code{keyword}, then this attribute may also specify the default keyword to +assume when the argument is not supplied. If left empty, @var{arg-default} +(@pxref{arg-default}) or the zero-valued keyword will be used. + +This is overridden and the options are required if the libopts library +gets configured with @code{--disable-optional-args}. + +@node arg-default +@subsubsection Default Option Argument Value +@vindex arg-default +This specifies the default option argument value to be used when the option is +not specified or preset. You may specify multiple @code{arg-default} values if +the argument type is @code{set membership}. + +@node Option Argument Handling +@subsection Option Argument Handling +@cindex Option Argument Handling + +AutoOpts will either specify or automatically generate callback procedures +for options that take specialized arguments. The only option argument types +that are not specialized are plain string arguments and no argument at all. +For options that fall into one of those two categories, you may specify your +own callback function, as specified below. If you do this and if you +specify that options are resettable (@pxref{automatic options}), then your +option handling code @strong{must} look for the @samp{OPTST_RESET} bit in +the @code{fOptState} field of the option descriptor. + +If the option takes a string argument, then you may specify that the option +is to be handled by the @code{libopts} library procedures +@code{stackOptArg()} or @code{unstackOptArg()} (see below). In this case, +you may not provide option handling code. + +Finally, @samp{documentation} options (@pxref{opt-attr documentation}) may +also be marked as @option{settable} (@pxref{opt-attr settable}) and have +special callback functions (either @samp{flag-code}, @samp{extract-code}, +or @samp{call-proc}). + +@table @samp +@item flag-code +@vindex flag-code +statements to execute when the option is encountered. This may be used in +conjunction with option argument types that cause AutoOpts to emit handler +code. If you do this, the @samp{flag-code} with index zero (0) is emitted +into the handler code @emph{before} the argument is handled, and the entry +with index one (1) is handled afterward. + +The generated procedure will be laid out something like this: + +@example +static void +doOpt<name>(tOptions* pOptions, tOptDesc* pOptDesc) +@{ +<flag-code[0]> +<AutoOpts defined handler code> +<flag-code[1]> +@} +@end example + +Only certain fields within the @code{tOptions} and @code{tOptDesc} +structures may be accessed. @xref{Option Processing Data}. When writing +this code, you must be very careful with the @code{pOptions} pointer. The +handler code is called with this pointer set to special values for handling +special situations. Your code must handle them. As an example, +look at @code{optionEnumerationVal} in @file{enum.c}. + +@item extract-code +@vindex extract-code +This is effectively identical to @code{flag-code}, except that the +source is kept in the output file instead of the definitions file +and you cannot use this in conjunction with options with arguments, +other than string arguments. + +A long comment is used to demarcate the code. You must not modify +that marker. @i{Before} regenerating the option code file, +the old file is renamed from MUMBLE.c to MUMBLE.c.save. The template +will be looking there for the text to copy into the new output file. + +@item call-proc +@vindex call-proc +external procedure to call when option is encountered. The calling +sequence must conform to the sequence defined above for the generated +procedure, @code{doOpt<name>}. It has the same restrictions +regarding the fields within the structures passed in as arguments. +@xref{Option Processing Data}. + +@item flag-proc +@vindex flag-proc +Name of another option whose @code{flag-code} can be executed +when this option is encountered. + +@item stack-arg +@vindex stack-arg +Call a special library routine to stack the option's arguments. Special +macros in the interface file are provided for determining how many of the +options were found (@code{STACKCT_OPT(NAME)}) and to obtain a pointer to a +list of pointers to the argument values (@code{STACKLST_OPT(NAME)}). +Obviously, for a stackable argument, the @code{max} attribute +(@pxref{Common Attributes}) needs to be set higher than @code{1}. + +If this stacked argument option has a disablement prefix, then the entire +stack of arguments will be cleared by specifying the option with that +disablement prefix. + +@item unstack-arg +@vindex unstack-arg +Call a special library routine to remove (``unstack'') strings +from a @code{stack-arg} option stack. This attribute must name +the option that is to be ``unstacked''. Neither this option nor +the stacked argument option it references may be equivalenced to +another option. +@end table + +@node Internationalizing Options +@subsection Internationalizing Options +@cindex Internationalizing Options + +Normally, AutoOpts produces usage text that is difficult to translate. It is +pieced together on the fly using words and phrases scattered around here and +there, piecing together toe document. This does not translate well. + +Incorporated into this package are some ways around the problem. First, you +should specify the @code{full-usage} and @code{short-usage} program attributes +(@pxref{program attributes}). This will enable your translators to translate +the usage text as a whole. + +Your translators will also be able to translate long option names. The option +name translations will then become the names searched for both on the command +line and in configuration files. However, it will not affect the names of +environment variable names used to configure your program. + +If it is considered desireable to keep configuration files in the ``C'' +locale, then several macros are available to suppress or delay the +translations of option names at run time. These are all disabled if +@code{ENABLE_NLS} is not defined at compile time or if @code{no-xlate} has +been set to the value @emph{anything}. These macros @strong{must} +be invoked before the first invocation of @code{optionProcess}. + +@table @samp +@item OPT_NO_XLAT_CFG_NAMES; +@itemx OPT_XLAT_CFG_NAMES; +Disable (or enable) the translations of option names for configuration files. +If you enable translation for config files, then they will be translated for +command line options. + +@item OPT_NO_XLAT_OPT_NAMES; +@itemx OPT_XLAT_OPT_NAMES; +Disable (or enable) the translations of option names for command line +processing. If you disable the translation for command line processing, +you will also disable it for configuration file processing. Once translated, +the option names will remain translated. +@end table + +@node documentation attributes +@subsection Man and Info doc Attributes +@cindex documentation attributes + +AutoOpts includes AutoGen templates for producing abbreviated man pages +and for producing the invoking section of an info document. To take +advantage of these templates, you must add several attributes to your +option definitions. + +@table @samp +@item arg-name +@vindex arg-name +If an option has an argument, the argument should have a name for +documentation purposes. It will default to @code{arg-type}, but +it will likely be clearer with something else like, @code{file-name} +instead of @code{string} (the type). + +@item doc +@vindex doc +First, every @code{flag} definition @emph{other than} ``documentation'' +definitions, must have a @code{doc} attribute defined. If the option takes +an argument, then it will need an @code{arg-name} attribute as well. The +@code{doc} text should be in plain sentences with minimal formatting. The +Texinfo commands @code{@@code}, and @code{@@var} will have its enclosed text +made into @strong{\fB} entries in the man page, and the @code{@@file} text +will be made into @strong{\fI} entries. The @code{arg-name} attribute is +used to display the option's argument in the man page. + +Options marked with the ``documentation'' attribute are for documenting +the usage text. All other options should have the ``doc'' attribute in +order to document the usage of the option in the generated man pages. + +@item option-info +@vindex option-info +This text will be inserted as a lead-in paragraph in the @code{OPTIONS} +section of the generated man page. + +@item doc-section +@vindex doc-section +This is a compound attribute that requires three @i{sub}attributes: +@table @i +@item ds-type +This describes the section type. Basically, the title of the section +that will be added to all output documentation. There may be only one +@code{doc-section} for any given @code{ds-type}. If there are duplicates, +the results are undefined (it might work, it might not). + +There are five categories of @code{ds-type} sections. +They are those that the documentation templates would otherwise: +@enumerate +@item +always create itself, ignoring any @code{ds-type}s by this name. +These are marked, below, as @code{ao-only}. +@item +create, if none have been provided. +These are marked, @code{alternate}. +@item +create, but augment if the @code{doc-section} was provided. +These are marked, @code{augments}. +@item +do nothing, but inserts them into the output in a prescribed order. +These are marked, @code{known} +@item +knows nothing about them. They will be alphabetized and inserted +after the list of leading sections and before the list of trailing +sections. These are not marked because I don't know their names. +@end enumerate + +Some of these are emitted by the documentation templates only if +certain conditions are met. If there are conditions, they are +explained below. If there are no conditions, then you will always +see the named section in the output. + +The output sections will appear in this order: +@table @samp +@item NAME +@code{ao-only}. +@item SYNOPSIS +@code{alternate}. +@item DESCRIPTION +@code{augments}. +@item OPTIONS +@code{ao-only}. +@item OPTION PRESETS +@code{ao-only}, if environment presets or configuration file processing +has been specified. +@item unknown +At this point, the unknown, alphabetized sections are inserted. +@item IMPLEMENTATION NOTES +@code{known} +@item ENVIRONMENT +@code{augments}, if environment presets have been specified. +@item FILES +@code{augments}, if configuration file processing has been specified. +@item EXAMPLES +@code{known} +@item EXIT STATUS +@code{augments}. +@item ERRORS +@code{known} +@item COMPATIBILITY +@code{known} +@item SEE ALSO +@code{known} +@item CONFORMING TO +@code{known} +@item HISTORY +@code{known} +@item AUTHORS +@code{alternate}, if the @code{copyright} stanza has either +an @code{author} or an @code{owner} attribute. +@item COPYRIGHT +@code{alternate}, if there is a @code{copyright} stanza. +@item BUGS +@code{augments}, if the @code{copyright} stanza has an +@code{eaddr} attribute. +@item NOTES +@code{augments}. +@end table + +@item ds-format +This describes the format of the associated @code{ds-text} section. +@code{man}, @code{mdoc} and @code{texi} formats are supported. +Regardless of the chosen format, the formatting tags in the output +text will be converted to @code{man} macros for @code{man} pages, +@code{mdoc} macros for @code{mdoc} pages, and @code{texi} macros for +@code{texinfo} pages. +@item ds-text +This is the descriptive text, written according to the rules for +@code{ds-format} documents. +@end table + +Here is an example of a ``doc-section'' for a ``SEE ALSO'' type. + +@example +doc-section = @{ + ds-type = 'SEE ALSO'; // or anything else + ds-format = 'man'; // or texi or mdoc format + ds-text = <<-_EOText_ + text relevant to this section type, + in the chosen format + _EOText_; +@}; +@end example + +@item prog-man-descrip +@itemx prog-info-descrip +@vindex prog-man-descrip +@vindex prog-info-descrip +These attributes are now deprecated. +Please use a @code{doc-section} stanza with a @code{ds-type} +attribute set to @code{DESCRIPTION} instead. + +@item detail +@vindex detail +This attribute is used to add a very short explanation about what +a program is used for when the ``title'' attribute is insufficient. +If there is no ``doc-section'' stanza of type ``DESCRIPTION'', then +this text is used for the man page DESCRIPTION section, too. +@end table + +@node automatic options +@subsection Automatically Supported Options +@cindex automatic options + +AutoOpts provides automated support for several options. @code{help} and +@code{more-help} are always provided. The others are conditional upon +various global program attributes being defined @xref{program attributes}. + +Below are the option names and default flag values. The flags are activated +if and only if at least one user-defined option also uses a flag value. The +long names are supported as option names if @code{long-opts} has been +specified. These option flags may be deleted or changed to characters of your +choosing by specifying +@vindex more-help-value +@vindex usage-value +@vindex version-value +@vindex load-opts-value +@vindex reset-value +@code{xxx-value = "y";}, where @code{xxx} is one of the +option names below and @code{y} is either empty or the character of your choice. +For example, to change the help flag from @code{?} to @code{h}, specify +@vindex help-value +@code{help-value = "h";}; and to require that @code{save-opts} be specified +only with its long option name, specify +@vindex save-opts-value +@code{save-opts-value = "";}. + +Additionally, the procedure that prints out the program version may be +replaced by specifying @code{version-proc}. +@vindex version-proc +This procedure must be defined to be of external scope (non-static). +By default, the AutoOpts library provides @code{optionPrintVersion} +and it will be the specified callback function in the option +definition structure. + +With the exception of the @code{load-opts} option, none of these automatically +supported options will be recognized in configuration files or environment +variables. + +@table @samp +@item help -? +This option will immediately invoke the @code{USAGE()} procedure +and display the usage line, a description of each option with +its description and option usage information. This is followed +by the contents of the definition of the @code{detail} text macro. + +@item more-help -! +This option is identical to the @code{help} option, except that the +output is passed through a pager program. (@code{more} by default, or +the program identified by the @code{PAGER} environment variable.) + +@item usage -u +This option must be requested by specifying, @code{usage-opt} in the option +definition file. It will produce abbreviated help text to @file{stdout} and +exit with zero status (@code{EXIT_SUCCESS}). + +@item version -v +This will print the program name, title and version. If it is followed by +the letter @code{c} and a value for @code{copyright} and @code{owner} have +been provided, then the copyright will be printed, too. If it is followed +by the letter @code{n}, then the full copyright notice (if available) will +be printed. The @code{version} attribute must be specified in the option +definition file. + +@item load-opts -< +@cindex configuration file +This option will load options from the named file. They will be treated +exactly as if they were loaded from the normally found configuration files, +but will not be loaded until the option is actually processed. This can also +be used within another configuration file, causing them to nest. This is the +@strong{only} automatically supported option that can be activated inside of +config files or with environment variables. + +Specifying the negated form of the option (@code{--no-load-opts}) will +suppress the processing of configuration files and environment variables. + +This option is activated by specifying one or more @code{homerc} attributes. + +@item save-opts -> +@cindex configuration file +This option will cause the option state to be printed in the configuration file +format when option processing is done but not yet verified for consistency. +The program will terminate successfully without running when this has +completed. Note that for most shells you will have to quote or escape the +flag character to restrict special meanings to the shell. + +The output file will be the configuration file name (default or provided by +@code{rcfile}) in the last directory named in a @code{homerc} definition. + +This option may be set from within your program by invoking the +"@code{SET_OPT_SAVE_OPTS(@i{filename})}" macro (@pxref{SET_OPT_name}). +Invoking this macro will set the file name for saving the option processing +state, but the state will @strong{not} actually be saved. You must call +@code{optionSaveFile} to do that (@pxref{libopts-optionSaveFile}). +@strong{CAVEAT:} if, after invoking this macro, you call +@code{optionProcess}, the option processing state will be saved to this file +and @code{optionProcess} will not return. You may wish to invoke +@code{CLEAR_OPT( SAVE_OPTS )} (@pxref{CLEAR_OPT}) beforehand if you do need +to reinvoke @code{optionProcess}. + +This option is activated by specifying one or more @code{homerc} attributes. + +@item reset-option -R +This option takes the name of an option for the current program and resets its +state such that it is set back to its original, compile-time initialized +value. If the option state is subsequently stored (via @code{--save-opts}), +the named option will not appear in that file. + +This option is activated by specifying the @code{resettable} attribute. + +@strong{BEWARE}: If the @code{resettable} attribute is specified, all +option callbacks @strong{must} look for the @code{OPTST_RESET} bit in the +@code{fOptState} field of the option descriptor. If set, the @code{optCookie} +and @code{optArg} fields will be unchanged from their last setting. When the +callback returns, these fields will be set to their original values. If you +use this feature and you have allocated data hanging off of the cookie, you +need to deallocate it. +@end table + +@node standard options +@subsection Library of Standard Options +@cindex standard options + +AutoOpts has developed a set of standardized options. +You may incorporate these options in your program simply by @emph{first} +adding a @code{#define} for the options you want, and then the line, + +@example +#include stdoptions.def +@end example + +@noindent +in your option definitions. The supported options are specified thus: + +@example +#define DEBUG +#define DIRECTORY +#define DRY_RUN +#define INPUT +#define INTERACTIVE +#define OUTPUT +#define WARN + +#define SILENT +#define QUIET +#define BRIEF +#define VERBOSE +@end example + +By default, only the long form of the option will be available. +To specify the short (flag) form, suffix these names with @code{_FLAG}. +e.g., + +@example +#define DEBUG_FLAG +@end example + +@code{--silent}, @code{--quiet}, @code{--brief} and @code{--verbose} are +related in that they all indicate some level of diagnostic output. +These options are all designed to conflict with each other. +Instead of four different options, however, several levels can be +incorporated by @code{#define}-ing @code{VERBOSE_ENUM}. In conjunction +with @code{VERBOSE}, it incorporates the notion of @i{5} levels in an +enumeration: @code{silent}, @code{quiet}, @code{brief}, +@code{informative} and @code{verbose}; with the default being +@code{brief}. + +@ignore +END == AUTOOPTS-MAIN == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AUTOOPTS-API == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node AutoOpts API +@section Programmatic Interface +@cindex AutoOpts API + +The user interface for access to the argument information is completely +defined in the generated header file and in the portions of the +distributed file "options.h" that are marked "public". + +In the following macros, text marked @code{<NAME>} or @code{name} +is the name of the option @strong{in upper case} and @strong{segmented +with underscores @code{_}}. The macros and enumerations defined in the +options header (interface) file are used as follows: + +To see how these @code{#define} macros are used in a program, +the reader is referred to the several @file{opts.h} files +included with the AutoGen sources. + +@menu +* Option Processing Data:: Data for Option Processing +* CLEAR_OPT:: CLEAR_OPT( <NAME> ) - Clear Option Markings +* COUNT_OPT:: COUNT_OPT( <NAME> ) - Definition Count +* DESC:: DESC( <NAME> ) - Option Descriptor +* DISABLE_OPT_name:: DISABLE_OPT_name - Disable an option +* ENABLED_OPT:: ENABLED_OPT( <NAME> ) - Is Option Enabled? +* ERRSKIP_OPTERR:: ERRSKIP_OPTERR - Ignore Option Errors +* ERRSTOP_OPTERR:: ERRSTOP_OPTERR - Stop on Errors +* HAVE_OPT:: HAVE_OPT( <NAME> ) - Have this option? +* ISSEL_OPT:: ISSEL_OPT( <NAME> ) - Is Option Selected? +* ISUNUSED_OPT:: ISUNUSED_OPT( <NAME> ) - Never Specified? +* OPTION_CT:: OPTION_CT - Full Count of Options +* OPT_ARG:: OPT_ARG( <NAME> ) - Option Argument String +* OPT_NO_XLAT_CFG_NAMES:: OPT_NO_XLAT_CFG_NAMES - option name xlation +* OPT_NO_XLAT_OPT_NAMES:: OPT_NO_XLAT_OPT_NAMES - option name xlation +* OPT_VALUE_name:: OPT_VALUE_name - Option Argument Value +* OPT_XLAT_CFG_NAMES:: OPT_XLAT_CFG_NAMES - option name xlation +* OPT_XLAT_OPT_NAMES:: OPT_XLAT_OPT_NAMES - option name xlation +* RESTART_OPT:: RESTART_OPT( n ) - Resume Option Processing +* SET_OPT_name:: SET_OPT_name - Force an option to be set +* STACKCT_OPT:: STACKCT_OPT( <NAME> ) - Stacked Arg Count +* STACKLST_OPT:: STACKLST_OPT( <NAME> ) - Argument Stack +* START_OPT:: START_OPT - Restart Option Processing +* STATE_OPT:: STATE_OPT( <NAME> ) - Option State +* USAGE:: USAGE( exit-code ) - Usage invocation macro +* VALUE_OPT_name:: VALUE_OPT_name - Option Flag Value +* VERSION:: VERSION - Version and Full Version +* WHICH_IDX_name:: WHICH_IDX_name - Which Equivalenced Index +* WHICH_OPT_name:: WHICH_OPT_name - Which Equivalenced Option +* teOptIndex:: teOptIndex - Option Index and Enumeration +* OPTIONS_STRUCT_VERSION:: OPTIONS_STRUCT_VERSION - active version +* libopts procedures:: libopts External Procedures +@end menu + +@node Option Processing Data +@subsection Data for Option Processing +@cindex Option Processing Data + +This section describes the data that may be accessed from within the +option processing callback routines. The following fields may be used +in the following ways and may be used for read only. The first set is +addressed from the @code{tOptDesc*} pointer: + +@table @samp +@cindex optIndex +@item optIndex +@cindex optValue +@item optValue +These may be used by option procedures to determine which option they +are working on (in case they handle several options). + +@cindex optActualIndex +@item optActualIndex +@cindex optActualValue +@item optActualValue +These may be used by option procedures to determine which option was +used to set the current option. This may be different from the above if +the options are members of an equivalence class. + +@cindex optOccCt +@item optOccCt +If AutoOpts is processing command line arguments, then this value will +contain the current occurrence count. During the option preset phase +(reading configuration files and examining environment variables), the value is +zero. + +@cindex fOptState +@item fOptState +The field may be tested for the following bit values +(prefix each name with @code{OPTST_}, e.g. @code{OPTST_INIT}): + +@table @samp +@item INIT +Initial compiled value. As a bit test, it will always yield FALSE. + +@item SET +The option was set via the @code{SET_OPT()} macro. + +@item PRESET +@cindex configuration file +The option was set via a configuration file. + +@item DEFINED +The option was set via a command line option. + +@item SET_MASK +This is a mask of flags that show the set state, one of the +above four values. + +@item EQUIVALENCE +This bit is set when the option was selected by an equivalenced option. + +@item DISABLED +This bit is set if the option is to be disabled. +(Meaning it was a long option prefixed by the disablement prefix, or +the option has not been specified yet and initializes as @code{disabled}.) +@end table + +As an example of how this might be used, in AutoGen I want to allow +template writers to specify that the template output can be left +in a writable or read-only state. To support this, there is a Guile +function named @code{set-writable} (@pxref{SCM set-writable}). +Also, I provide for command options @code{--writable} and +@code{--not-writable}. I give precedence to command line and RC +file options, thus: + +@example +switch (STATE_OPT( WRITABLE )) @{ +case OPTST_DEFINED: +case OPTST_PRESET: + fprintf(stderr, zOverrideWarn, pCurTemplate->pzFileName, + pCurMacro->lineNo); + break; + +default: + if (gh_boolean_p( set ) && (set == SCM_BOOL_F)) + CLEAR_OPT( WRITABLE ); + else + SET_OPT_WRITABLE; +@} +@end example + +@cindex pzLastArg +@item pzLastArg +Pointer to the latest argument string. BEWARE@: If the argument type +is numeric, an enumeration or a bit mask, then this will be the +argument @strong{value} and not a pointer to a string. +@end table + +The following two fields are addressed from the @code{tOptions*} pointer: + +@table @samp +@cindex pzProgName +@item pzProgName +Points to a NUL-terminated string containing the current program +name, as retrieved from the argument vector. + +@cindex pzProgPath +@item pzProgPath +Points to a NUL-terminated string containing the full path of +the current program, as retrieved from the argument vector. +(If available on your system.) + +@end table + +Note@: these fields get filled in during the first call to +@code{optionProcess()}. All other fields are private, for the exclusive +use of AutoOpts code and are subject to change. + +@node CLEAR_OPT +@subsection CLEAR_OPT( <NAME> ) - Clear Option Markings +@findex CLEAR_OPT + +Make as if the option had never been specified. +@code{HAVE_OPT(<NAME>)} will yield @code{FALSE} +after invoking this macro. + +@node COUNT_OPT +@subsection COUNT_OPT( <NAME> ) - Definition Count +@findex COUNT_OPT + +This macro will tell you how many times the option was +specified on the command line. It does not include counts +of preset options. + +@example +if (COUNT_OPT( NAME ) != desired-count) @{ + make-an-undesirable-message. +@} +@end example + +@node DESC +@subsection DESC( <NAME> ) - Option Descriptor +@findex DESC + +This macro is used internally by other AutoOpt macros. +It is not for general use. It is used to obtain the option description +corresponding to its @strong{UPPER CASED} option name argument. +This is primarily used in other macro definitions. + +@node DISABLE_OPT_name +@subsection DISABLE_OPT_name - Disable an option +@findex DISABLE_OPT_name + +This macro is emitted if it is both settable +and it can be disabled. If it cannot be disabled, it may +always be CLEAR-ed (see above). + +The form of the macro will actually depend on whether the +option is equivalenced to another, and/or has an assigned +handler procedure. Unlike the @code{SET_OPT} macro, +this macro does not allow an option argument. + +@example +DISABLE_OPT_NAME; +@end example + +@node ENABLED_OPT +@subsection ENABLED_OPT( <NAME> ) - Is Option Enabled? +@findex ENABLED_OPT + +Yields true if the option defaults to disabled and +@code{ISUNUSED_OPT()} would yield true. It also yields true if +the option has been specified with a disablement prefix, +disablement value or the @code{DISABLE_OPT_NAME} macro was invoked. + +@node ERRSKIP_OPTERR +@subsection ERRSKIP_OPTERR - Ignore Option Errors +@findex ERRSKIP_OPTERR + +When it is necessary to continue (return to caller) +on option errors, invoke this option. It is reversible. +@xref{ERRSTOP_OPTERR}. + +@node ERRSTOP_OPTERR +@subsection ERRSTOP_OPTERR - Stop on Errors +@findex ERRSTOP_OPTERR + +After invoking this macro, if @code{optionProcess()} +encounters an error, it will call @code{exit(1)} rather than return. +This is the default processing mode. It can be overridden by +specifying @code{allow-errors} in the definitions file, +or invoking the macro @xref{ERRSKIP_OPTERR}. + +@node HAVE_OPT +@subsection HAVE_OPT( <NAME> ) - Have this option? +@findex HAVE_OPT + +This macro yields true if the option has been specified +in any fashion at all. It is used thus: + +@example +if (HAVE_OPT( NAME )) @{ + <do-things-associated-with-opt-name>; +@} +@end example + +@node ISSEL_OPT +@subsection ISSEL_OPT( <NAME> ) - Is Option Selected? +@findex ISSEL_OPT + +This macro yields true if the option has been +specified either on the command line or via a SET/DISABLE macro. + +@node ISUNUSED_OPT +@subsection ISUNUSED_OPT( <NAME> ) - Never Specified? +@findex ISUNUSED_OPT + +This macro yields true if the option has +never been specified, or has been cleared via the +@code{CLEAR_OPT()} macro. + +@node OPTION_CT +@subsection OPTION_CT - Full Count of Options +@findex OPTION_CT + +The full count of all options, both those defined +and those generated automatically by AutoOpts. This is primarily +used to initialize the program option descriptor structure. + +@node OPT_ARG +@subsection OPT_ARG( <NAME> ) - Option Argument String +@findex OPT_ARG + +The option argument value as a pointer to string. Note that argument +values that have been specified as numbers are stored as numbers or +keywords. For such options, use instead the @code{OPT_VALUE_name} +define. It is used thus: + +@example +if (HAVE_OPT( NAME )) @{ + char* p = OPT_ARG( NAME ); + <do-things-with-opt-name-argument-string>; +@} +@end example + +@node OPT_NO_XLAT_CFG_NAMES +@subsection OPT_NO_XLAT_CFG_NAMES - option name xlation +@findex OPT_NO_XLAT_CFG_NAMES + +Invoking this macro will disable the translation of option names only while +processing configuration files and environment variables. This must be +invoked before the first call to @code{optionProcess}.. You need not invoke +this if your option definition file contains the attribute assignment, +``@code{no-xlate = opt-cfg;}''. + +@node OPT_NO_XLAT_OPT_NAMES +@subsection OPT_NO_XLAT_OPT_NAMES - option name xlation +@findex OPT_NO_XLAT_OPT_NAMES + +Invoking this macro will completely disable the translation of option names. +This must be invoked before the first call to @code{optionProcess}. You need +not invoke this if your option definition file contains the attribute +assignment, ``@code{no-xlate = opt;}''. + +@node OPT_VALUE_name +@subsection OPT_VALUE_name - Option Argument Value +@findex OPT_VALUE_name + +This macro gets emitted only for options that take numeric, keyword or set +membership arguments. The macro yields a word-sized integer containing the +enumeration, bit set or numeric value for the option argument. + +@example +int opt_val = OPT_VALUE_name; +@end example + +@node OPT_XLAT_CFG_NAMES +@subsection OPT_XLAT_CFG_NAMES - option name xlation +@findex OPT_XLAT_CFG_NAMES + +If @code{ENABLE_NLS} is defined and @code{no-xlate} has been not set to the +value @emph{anything}, this macro will cause the translation of option names +to happen before starting the processing of configuration files and +environment variables. This will change the recognition of options within the +@code{$PROGRAMNAME} environment variable, but will not alter the names used +for setting options via @code{$PROGRAMNAME_name} environment variables. + +This must be invoked before the first call to @code{optionProcess}. You might +need to use this macro if your option definition file contains the attribute +assignment, ``@code{no-xlate = opt;}'' or ``@code{no-xlate = opt-cfg;}'', and +you have determined in some way that you wish to override that. + +@node OPT_XLAT_OPT_NAMES +@subsection OPT_XLAT_OPT_NAMES - option name xlation +@findex OPT_XLAT_OPT_NAMES + +If @code{ENABLE_NLS} is defined and @code{no-xlate} has been not set to the +value @emph{anything}, translate the option names before processing the +command line options. Long option names may thus be localized. (If the names +were translated before configuration processing, they will not be +re-translated.) + +This must be invoked before the first call to @code{optionProcess}. You might +need to use this macro if your option definition file contains the attribute +assignment, ``@code{no-xlate = opt;}'' and you have determined in some way that +you wish to override that. + +@node RESTART_OPT +@subsection RESTART_OPT( n ) - Resume Option Processing +@findex RESTART_OPT + +If option processing has stopped (either because of an error +or something was encountered that looked like a program argument), +it can be resumed by providing this macro with the index @code{n} +of the next option to process and calling @code{optionProcess()} again. + +@node SET_OPT_name +@subsection SET_OPT_name - Force an option to be set +@findex SET_OPT_name + +This macro gets emitted only when the given +option has the @code{settable} attribute specified. + +The form of the macro will actually depend on whether the option is +equivalenced to another, has an option argument and/or has an assigned +handler procedure. If the option has an argument, then this macro will +too. Beware that the argument is not reallocated, so the value must not +be on the stack or deallocated in any other way for as long as the value +might get referenced. + +If you have supplied at least one @file{homerc} file +(@pxref{program attributes}), this macro will be emitted for the +@code{--save-opts} option. + +@example +SET_OPT_SAVE_OPTS( "filename" ); +@end example + +@noindent +@xref{automatic options}, for a discussion of the implications of using +this particular example. + +@node STACKCT_OPT +@subsection STACKCT_OPT( <NAME> ) - Stacked Arg Count +@findex STACKCT_OPT + +When the option handling attribute is specified +as @code{stack_arg}, this macro may be used to determine how +many of them actually got stacked. + +Do not use this on options that have not been stacked or has not been +specified (the @code{stack_arg} attribute must have been specified, +and @code{HAVE_OPT(<NAME>)} must yield TRUE). +Otherwise, you will likely seg fault. + +@example +if (HAVE_OPT( NAME )) @{ + int ct = STACKCT_OPT( NAME ); + char** pp = STACKLST_OPT( NAME ); + + do @{ + char* p = *pp++; + do-things-with-p; + @} while (--ct > 0); +@} +@end example + +@node STACKLST_OPT +@subsection STACKLST_OPT( <NAME> ) - Argument Stack +@findex STACKLST_OPT + +The address of the list of pointers to the +option arguments. The pointers are ordered by the order in +which they were encountered in the option presets and +command line processing. + +Do not use this on options that have not been stacked or has not been +specified (the @code{stack_arg} attribute must have been specified, +and @code{HAVE_OPT(<OPTION>)} must yield TRUE). +Otherwise, you will likely seg fault. + +@example +if (HAVE_OPT( NAME )) @{ + int ct = STACKCT_OPT( NAME ); + char** pp = STACKLST_OPT( NAME ); + + do @{ + char* p = *pp++; + do-things-with-p; + @} while (--ct > 0); +@} +@end example + +@node START_OPT +@subsection START_OPT - Restart Option Processing +@findex START_OPT + +This is just a shortcut for RESTART_OPT(1) (@xref{RESTART_OPT}.) + +@node STATE_OPT +@subsection STATE_OPT( <NAME> ) - Option State +@findex STATE_OPT + +If you need to know if an option was set because of presetting actions +(configuration file processing or environment variables), versus a command +line entry versus one of the SET/DISABLE macros, then use this macro. It +will yield one of four values: @code{OPTST_INIT}, @code{OPTST_SET}, +@code{OPTST_PRESET} or @code{OPTST_DEFINED}. It is used thus: + +@example +switch (STATE_OPT( NAME )) @{ + case OPTST_INIT: + not-preset, set or on the command line. (unless CLEAR-ed) + + case OPTST_SET: + option set via the SET_OPT_NAME() macro. + + case OPTST_PRESET: + option set via an configuration file or environment variable + + case OPTST_DEFINED: + option set via a command line option. + + default: + cannot happen :) +@} +@end example + +@node USAGE +@subsection USAGE( exit-code ) - Usage invocation macro +@findex USAGE + +This macro invokes the procedure registered to display +the usage text. Normally, this will be @code{optionUsage} from the +AutoOpts library, but you may select another procedure by specifying +@code{usage = "proc_name"} program attribute. This procedure must +take two arguments@: first, a pointer to the option descriptor, and +second the exit code. The macro supplies the option descriptor +automatically. This routine is expected to call @code{exit(3)} with +the provided exit code. + +The @code{optionUsage} routine also behaves differently depending +on the exit code: + +@table @code +@item EXIT_SUCCESS (the value zero) +It is assumed that full usage help has been requested. Consequently, more +information is provided than when displaying usage and exiting with a +non-zero exit code. Output will be sent to @file{stdout} and the program will +exit with a zero status code. + +@item EX_USAGE (64) +The abbreviated usage will be printed to @file{stdout} and the program will +exit with a zero status code. ``EX_USAGE'' may or may not be 64. If your +system provides ``/usr/include/sysexits.h'' that has a different value, +then that value will be used. + +@item any other value +The abbreviated usage will be printed to stderr and the program will +exit with the provided status code. +@end table + +@node VALUE_OPT_name +@subsection VALUE_OPT_name - Option Flag Value +@findex VALUE_OPT_name + +This is a #define for the flag character used to +specify an option on the command line. If @code{value} was not +specified for the option, then it is a unique number associated +with the option. @code{option value} refers to this value, +@code{option argument} refers to the (optional) argument to the +option. + +@example +switch (WHICH_OPT_OTHER_OPT) @{ +case VALUE_OPT_NAME: + this-option-was-really-opt-name; +case VALUE_OPT_OTHER_OPT: + this-option-was-really-other-opt; +@} +@end example + +@node VERSION +@subsection VERSION - Version and Full Version +@findex VERSION + +If the @code{version} attribute is defined for the program, +then a stringified version will be #defined as PROGRAM_VERSION and +PROGRAM_FULL_VERSION. PROGRAM_FULL_VERSION is used for printing +the program version in response to the version option. The version +option is automatically supplied in response to this attribute, too. + +You may access PROGRAM_VERSION via @code{programOptions.pzFullVersion}. + +@node WHICH_IDX_name +@subsection WHICH_IDX_name - Which Equivalenced Index +@findex WHICH_IDX_name + +This macro gets emitted only for equivalenced-to options. It is used to +obtain the index for the one of the several equivalence class members +set the equivalenced-to option. + +@example +switch (WHICH_IDX_OTHER_OPT) @{ +case INDEX_OPT_NAME: + this-option-was-really-opt-name; +case INDEX_OPT_OTHER_OPT: + this-option-was-really-other-opt; +@} +@end example + +@node WHICH_OPT_name +@subsection WHICH_OPT_name - Which Equivalenced Option +@findex WHICH_OPT_name + +This macro gets emitted only for equivalenced-to options. It is used to +obtain the value code for the one of the several equivalence class members +set the equivalenced-to option. + +@example +switch (WHICH_OPT_OTHER_OPT) @{ +case VALUE_OPT_NAME: + this-option-was-really-opt-name; +case VALUE_OPT_OTHER_OPT: + this-option-was-really-other-opt; +@} +@end example + +@node teOptIndex +@subsection teOptIndex - Option Index and Enumeration +@findex teOptIndex + +This enum defines the complete set of options, both +user specified and automatically provided. This can be used, +for example, to distinguish which of the equivalenced options +was actually used. + +@example +switch (pOptDesc->optActualIndex) @{ +case INDEX_OPT_FIRST: + stuff; +case INDEX_OPT_DIFFERENT: + different-stuff; +default: + unknown-things; +@} +@end example + +@node OPTIONS_STRUCT_VERSION +@subsection OPTIONS_STRUCT_VERSION - active version + +You will not actually need to reference this value, but you need to be +aware that it is there. It is the first value in the option descriptor +that you pass to @code{optionProcess}. It contains a magic number and +version information. Normally, you should be able to work with a more +recent option library than the one you compiled with. However, if the +library is changed incompatibly, then the library will detect the out of +date magic marker, explain the difficulty and exit. You will then need +to rebuild and recompile your option definitions. This has rarely been +necessary. + +@ignore +END == AUTOOPTS-API == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AUTOOPTS-DATA == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node Multi-Threading +@section Multi-Threading + +AutoOpts was designed to configure a program for running. This generally +happens before much real work has been started. Consequently, it is +expected to be run before multi-threaded applications have started multiple +threads. However, this is not always the case. Some applications may +need to reset and reload their running configuration, and some may use +@code{SET_OPT_xxx()} macros during processing. If you need to dynamically +change your option configuration in your multi-threaded application, it is +your responsibility to prevent all threads from accessing the option +configuration state, except the one altering the configuration. + +The various accessor macros (@code{HAVE_OPT()}, etc.) do not modify state +and are safe to use in a multi-threaded application. It is safe as long +as no other thread is concurrently modifying state, of course. + +@c === SECTION MARKER + +@node option descriptor +@section Option Descriptor File +@cindex option descriptor + +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 @code{flag-code} construct. + +@c === SECTION MARKER + +@node Using AutoOpts +@section Using AutoOpts +@cindex 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 +@end menu + +@node local use +@subsection 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. + +@itemize @bullet +@item +Create a file @samp{myopts.def}, according to the documentation above. +It is probably easiest to start with the example in @ref{Quick Start} +and edit it into the form you need. + +@item +Run AutoGen to create the option interface file (@code{myopts.h}) +and the option descriptor code (@code{myopts.c}): + +@example +autogen myopts.def +@end example + +@item +In all your source files where you need to refer to option state, +@code{#include "myopts.h"}. +@item +In your main routine, code something along the lines of: + +@example +#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(); + ... +@} +@end example + +@item +Compile @samp{myopts.c} and link your program +with the following additional arguments: + +@example +`autoopts-config cflags ldflags` myopts.c +@end example +@end itemize + +@node binary not installed +@subsection binary distro, AutoOpts not installed + +If you will be distributing (or copying) your project to a system that +does not have AutoOpts installed, you will need to statically link the +AutoOpts library, ``libopts'' into your program. Get the link information +with ``@code{static-libs}'' instead of ``@code{ldflags}'': + +@example +`autoopts-config static-libs` +@end example + +@node binary pre-installed +@subsection 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 +@code{--rpath} or by setting the @code{LD_LIBRARY_PATH} appropriately. +Otherwise, @xref{binary not installed}. + +@node source pre-installed +@subsection 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, +@file{autoopts.m4}. It will add an @code{autoconf} macro named, +@code{AG_PATH_AUTOOPTS}. Add this to your @file{configure.ac} script +and use the following substitution values: + +@table @code +@item AUTOGEN +the name of the autogen executable +@item AUTOGEN_TPLIB +the directory where AutoGen template library is stored +@item AUTOOPTS_CFLAGS +the compile time options needed to find the AutoOpts headers +@item AUTOOPTS_LIBS +the link options required to access the @code{libopts} library +@end table + +@node source not installed +@subsection 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 @code{libopts} in your project. +To do this, I recommend reading the tear-off libopts library +@file{README} that you can find in the @file{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: +@example +@url{http://autogen.sourceforge.net/blocksort.html} +@end example + +Alternatively, you can pull the @code{libopts} library sources into +a build directory and build it for installation along with your package. +This can be done approximately as follows: +@example +tar -xzvf `autoopts-config libsrc` +cd libopts-* +./bootstrap +configure +make +make install +@end example +That will install the library, but not the headers or anything else. + +@c === SECTION MARKER + +@node Presetting Options +@section Configuring your program +@cindex shell options + +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 (@file{rc} or @file{ini} files). In order to take +advantage of this, the AutoOpts client program must specify these features +in the option descriptor file (@pxref{program attributes}) with the +@code{rcfile} or @code{environrc} attributes. + +@menu +* loading rcfile:: configuration file presets +* saving rcfile:: Saving the presets into a configuration file +* sample rcfile:: Creating a sample configuration file +* environrc:: environment variable presets +* config example:: Config file only example +@end menu + +It is also possible to configure your program @i{without} using +the command line option parsing code. This is done by using +only the following four functions from the @file{libopts} library: + +@table @samp +@item configFileLoad +(@pxref{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. + +@item optionGetValue +(@pxref{libopts-optionGetValue}) will find the first value within the +hierarchy with a name that matches the name passed in. + +@item optionNextValue +(@pxref{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. + +@item optionUnloadNested +(@pxref{libopts-optionUnloadNested}). The pointer passed in must be +of type, @code{OPARG_TYPE_HIERARCHY} (see the autoopts/options.h +header file). @code{configFileLoad} will return a @code{tOptionValue} +pointer of that type. This function will release all the associated +memory. @code{AutoOpts} generated code uses this function for its own +needs. Client code should only call this function with pointers +gotten from @code{configFileLoad}. +@end table + +@node loading rcfile +@subsection configuration file presets +@cindex rcfile + +Configuration files are enabled by specifying the program attribute +@code{homerc} (@pxref{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 @code{homerc} entries and, +optionally, via a command line option. The first component of the +@code{homerc} entry may be an environment variable such as @code{$HOME}, or +it may also be @code{$$} (@strong{two} dollar sign characters) to specify +the directory of the executable. For example: + +@example +homerc = "$$/../share/autogen"; +@end example + +@noindent +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 @code{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 @code{immediate action} (@pxref{Immediate Action}). Any such +options are acted upon in @strong{reverse} order. The disabled +@code{load-opts} (@code{--no-load-opts}) option, for example, is an +immediate action option. Its presence in the last @code{homerc} file will +prevent the processing of any prior @code{homerc} files because its effect +is immediate. + +Configuration file processing can be completely suppressed by specifying +@code{--no-load-opts} on the command line, or @code{PROGRAM_LOAD_OPTS=no} in +the environment (if @code{environrc} has been specified). + +See the ``Configuration File Format'' section (@pxref{Config File Format}) +for details on the format of the file. + +@node saving rcfile +@subsection Saving the presets into a configuration file + +When configuration files are enabled for an application, the user is +also provided with an automatically supplied @code{--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 +@code{homerc} file. + +@node sample rcfile +@subsection Creating a sample configuration file +@cindex sample rcfile + +AutoOpts is shipped with a template named, @file{rc-sample.tpl}. +If your option definition file specifies the @code{homerc} attribute, +then you may invoke @file{autogen} thus: + +@example +autogen -Trc-sample <your-option-def-file> +@end example + +This will, by default, produce a sample file named, +@file{sample-<prog-name>rc}. It will be named differently if you specify your +configuration (rc) file name with the @code{rcfile} attribute. In that case, +the output file will be named, @file{sample-<rcfile-name>}. It will contain +all of the program options not marked as @code{no-preset}. It will also +include the text from the @code{doc} attribute. + +@ignore +END == AUTOOPTS-DATA == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AO-DATA1 == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@node environrc +@subsection environment variable presets +@cindex environrc + +If the AutoOpts client program specifies @code{environrc} in its +option descriptor file, then environment variables will be used for +presetting option state. Variables will be looked for that are named, +@code{PROGRAM_OPTNAME} and @code{PROGRAM}. @code{PROGRAM} is the +upper cased @code{C-name} of the program, and @code{OPTNAME} is the +upper cased @code{C-name} of a specific option. (The @code{C-name}s +are the regular names with all special characters converted to +underscores (@code{_}).) + +Option specific environment variables are processed after (and thus +take precedence over) the contents of the @code{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 @code{OPTNAME}. + +If a particular option may be disabled, then its disabled state is +indicated by setting the @code{PROGRAM_OPTNAME} value to the +disablement prefix. So, for example, if the disablement prefix were +@code{dont}, then you can disable the @code{optname} option by setting +the @code{PROGRAM_OPTNAME}' environment variable to `@i{dont}'. +@xref{Common Attributes}. + +The @code{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 +@code{no-preset} attribute and the @code{--help}, @code{--more-help}, +and @code{--save-opts} auto-supported options may not be preset. + +@node config example +@subsection Config file only example +@cindex rcfile +@cindex Configuration File +@cindex Configuration File example + +If for some reason it is difficult or unworkable to integrate configuration +file processing with command line option parsing, the @code{libopts} +(@pxref{libopts procedures}) library can still be used to process configuration +files. Below is a ``@t{Hello, World!}'' greeting program that tries +to load a configuration file @file{hello.conf} to see if it should use +an alternate greeting or to personalize the salutation. +@ignore +END == AO-DATA1 == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AO-DATA2 == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node Config File Format +@section Configuration File Format +@cindex Configuration File + +The configuration file is designed to associate names and values, much like +an AutoGen Definition File (@pxref{Definitions File}). Unfortunately, the +file formats are different. Specifically, AutoGen Definitions provide for +simpler methods for the precise control of a value string and provides for +dynamically computed content. Configuration files have some established +traditions in their layout. So, they are different, even though they do +both allow for a single name to be associated with multiple values and they +both allow for hierarchical values. + +@menu +* config name/string-value:: assigning a string value to a configurable +* config integer-values:: integer values +* config nested-values:: hierarchical values +* config directives:: configuration file directives +* config comments:: comments in the configuration file +@end menu + +@node config name/string-value +@subsection 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 (@code{:}) or an +equal sign (@code{=}). The colon or equal sign may optionally be surrounded +by additional white space. If more than one value line is needed, a +backslash (@code{\}) 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: + +@example +name value for that name +name = another \ + multi-line value \ + for that name. +name: a *third* value for ``name'' +@end example + +If you need more control over the content of the value, you may enclose the +value in XML style brackets: +@example +<name>value </name> +@end example +@noindent +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: @code{<name keep>}. + +@table @samp +@item keep +This mode will keep all text between the brackets and not strip any +white space. +@item uncooked +This mode strips leading and trailing white space, but not do any +quote processing. This is the default and need not be specified. +@item cooked +The text is trimmed of leading and trailing white space and XML encodings +are processed. These encodings are slightly expanded over the XML +specification. They are specified with an ampersand followed by a value +name or numeric value and then a semicolon: + +@table @samp +@item amp +@itemx lt +@itemx gt +@itemx quot +@itemx apos +@itemx #dd +@itemx #xHH + +These are all per fairly standad HTML and/or XML encodings. +Additionally: + +@item bs +The ASCII back space character. +@item ff +The ASCII form feed character. +@item ht +The ASCII horizontal (normal) tab character. +@item cr +The ASCII carriage return character. +@item vt +The ASCII vertical tab character. +@item bel +The ASCII alarm bell character. +@item nl +The ASCII new line character. +@item space +The ASCII space character. Normally not necessary, but if you want +to preserve leading or trailing space characters, then use this. +@end table +@end table + +And here is an example of an XML-styled value: + +@example +<name cooked> + This is&nl;&ht;another multi-line +&ht;string example. +</name> +@end example + +The string value associated with ``name'' will be exactly the text enclosed +in quotes with the encoded characters ``cooked'' as you would expect +(three text lines with the last line not ending with a newline, but +ending with a period). + +@node config integer-values +@subsection 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: + +@example +<name type=integer> 1234 </name> +@end example + +Boolean, enumeration and set membership types will be added as time +allows. ``type=string'' is also supported, but also is the default. + +@node config nested-values +@subsection 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: + +@example +<structured-name type=nested> + [[....]] +</structured-name> +@end example + +@noindent +The ellipsis may be filled with any legal configuration file name/value +assignments. + +@node config directives +@subsection configuration file directives +@cindex autoopts directives + +The @code{<?} marker indicates an XML directive. +There is only one directive supported: program sectioning, +though two syntaxes are supported. + +If, for example, you have a collection of programs that work closely +together and, likely, have a common set of options, these programs may use a +single, sectioned, configuration file. The file may be sectioned in either +of two ways. The two ways may not be intermixed in a single configuration +file. All text before the first segmentation line is processed, then only +the segment that applies: + +@table @samp +@item <?auto-options ...> +The @code{...} ellipsis may contain AutoOpts option processing options. +Currently, that consists of one or both of: + +@table @code +@item gnu +@itemx autoopts +to indicate GNU-standard or AutoOpts-standard layout of usage and +version information, and/or + +@item misuse-usage +@itemx no-misuse-usage +to indicate whether the available options should be listed when +an invalid option appears on the command line. +@end table +@noindent +Anything else will be silently ignored. + +@item <?program prog-name> +The @code{<?} marker indicates an XML directive. +The file is partitioned by these lines and the options are processed +for the @code{prog-name} program only before the first @code{<?program} +directive and the program section with a matching program name. + +@item [PROG_NAME] +This is basically an alias for @code{<?program prog-name>}, except that +the program name must be upper cased and segmented only with underscores. +@end table + +@noindent +Segmentation does not apply if the config file is being parsed with +the @code{configFileLoad(3AutoOpts)} function. + +@node config comments +@subsection comments in the configuration file + +Comments are lines beginning with a hash mark (@code{#}), +XML-style comments (@code{<!-- arbitrary text -->}), and +unrecognized XML directives. + +@example +# this is a comment +<!-- this is also + a comment --> +<?this is + a bad comment ;-> +@end example + +@c === SECTION MARKER + +@node shell options +@section AutoOpts for Shell Scripts +@cindex shell options +@cindex configuration file + +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: + +@enumerate +@item +You cannot obtain options from configuration files. +@item +You cannot obtain options from environment variables. +@item +You cannot save the option state to an option file. +@item +Option conflict/requirement verification is disabled. +@end enumerate + +Both of these methods are enabled by running AutoGen on +the definitions file with the additional main procedure attribute: + +@example +main = @{ main-type = shell-process; @}; +@end example +@noindent +or: +@example +main = @{ main-type = shell-parser; @}; +@end example + +If you do not supply a @code{proc-to-call}, it will default to +@code{optionPutShell}. That will produce a program that will process the +options and generate shell text for the invoking shell to interpret +(@pxref{binary-parser}). If you supply the name, @code{optionParseShell}, then +you will have a program that will generate a shell script that can parse the +options (@pxref{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 +@end menu + +@node binary-parser +@subsection 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: + +@example +autogen -L <opt-template-dir> test-errors.def +cc -o test-errors -L <opt-lib-dir> -I <opt-include-dir> \ + -DTEST_PROGRAM_OPTS test-errors.c -lopts +@end example + +The resulting program can then be used within your shell script as follows: + +@example +eval `./test-errors "$@@"` +if [ -z "$@{OPTION_CT@}" ] ; then exit 1 ; fi +test $@{OPTION_CT@} -gt 0 && shift $@{OPTION_CT@} +@end example +@ignore +END == AO-DATA2 == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@ignore +START == AUTOINFO == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c === SECTION MARKER + +@node AutoInfo +@section Automated Info Docs +@cindex AutoInfo + +AutoOpts provides two templates for producing @file{.texi} documentation. +@file{agtexi-cmd.tpl} for the invoking section, and @file{aginfo3.tpl} for +describing exported library functions and macros. + +For both types of documents, the documentation level is selected by +passing a @samp{-DLEVEL=<level-name>} argument to AutoGen when you build +the document. (See the example invocation below.) + +Two files will be produced, a @file{.texi} file and a @file{.menu} file. +You should include the text in the @file{.menu} file in a @file{@@menu} +list, either with @file{@@include}-ing it or just copying text. +The @file{.texi} file should be @file{@@include}-ed where the invoking +section belongs in your document. + +The @file{.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: + +@example +This chapter documents the @@file@{AutoOpts@} generated usage text +and option meanings for the @@file@{your-program@} program. +@end example + +@noindent +or: + +@example +These are the publicly exported procedures from the lib@i{name} library. +Any other functions mentioned in the @i{header} file are for the private use +of the library. +@end example + +@menu +* command-info:: ``invoking'' info docs +* library-info:: library info docs +@end menu + +@node command-info +@subsection ``invoking'' info docs + +Using the option definitions for an AutoOpt client program, the +@file{agtexi-cmd.tpl} template will produce texinfo text that documents the +invocation of your program. The text emitted is designed to be included +in the full texinfo document for your product. It is not a stand-alone +document. The usage text for the @ref{autogen usage}, +@ref{getdefs usage} and @ref{columns usage} programs, are included in +this document and are all generated using this template. + +If your program's option definitions include a +@samp{prog-info-descrip} section, then that text will replace the +boilerplate introductory paragraph. + +@noindent +These files are produced by invoking the following command: + +@example +autogen -L $@{prefix@}/share/autogen -Tagtexi-cmd.tpl \ + -DLEVEL=section your-opts.def +@end example + +@noindent +Where @file{$@{prefix@}} is the AutoGen installation prefix +and @file{your-opts.def} is the name of your product's option +definition file. + +@node library-info +@subsection library info docs + +The @file{texinfo} doc for libraries is derived from mostly the same +information as is used for producing man pages @xref{man3}. The main +difference is that there is only one output file and the individual +functions are referenced from a @code{.texi} menu. There is also +a small difference in the global attributes used: + +@multitable @columnfractions .02 .23 .65 +@item @tab lib_description +@tab A description of the library. This text appears before the menu. +If not provided, the standard boilerplate version will be inserted. +@item +@item @tab see_also +@tab The @code{SEE ALSO} functionality is not supported for the +@file{texinfo} documentation, so any @code{see_also} attribute will be ignored. +@end multitable + +@noindent +These files are produced by invoking the following commands: + +@example +getdefs linenum srcfile template=aginfo3.tpl output=libexport.def \ + <source-file-list> + +autogen -L $@{prefix@}/share/autogen -DLEVEL=section libexport.def +@end example + +@noindent +Where @file{$@{prefix@}} is the AutoGen installation prefix +and @file{libexport.def} is some name that suits you. + +An example of this can be seen in this document, @xref{libopts procedures}. + +@c === SECTION MARKER + +@node AutoMan pages +@section Automated Man Pages +@cindex AutoMan pages + +AutoOpts provides two templates for producing man pages. +The command (@file{man1}) pages are derived from the options definition +file, and the library (@file{man3}) pages are derived from +stylized comments (@pxref{getdefs Invocation}). + +@menu +* man1:: command line man pages +* man3:: library man pages +@end menu + +@node man1 +@subsection command line man pages + +Using the option definitions for an AutoOpts client program, +the @samp{agman-cmd.tpl} template will produce an nroff document +suitable for use as a @samp{man(1)} page document for a command +line command. The description section of the document is either +the @samp{prog-man-descrip} text, if present, or the @samp{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 (@pxref{option attributes}), plus +the @samp{doc} attribute is appended. Since the @samp{doc} +text is presumed to be designed for @code{texinfo} documentation, +@code{sed} is used to convert some constructs from @code{texi} +to @code{nroff}-for-@code{man}-pages. Specifically, + +@example +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 @samp{end example} command with ".br" +Replace the @samp{@@*} command with ".br" +@end example + +@noindent +This document is produced by invoking the following command: + +@example +autogen -L $@{prefix@}/share/autogen -Tagman-cmd.tpl options.def +@end example + +@noindent +Where @file{$@{prefix@}} is the AutoGen installation prefix and +@file{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. + +@node man3 +@subsection library man pages + +Two global definitions are required, and then +one library man page is produced for each @code{export_func} definition +that is found. It is generally convenient to place these definitions +as @file{getdefs} comments (@pxref{getdefs Invocation}) near the procedure +definition, but they may also be a separate AutoGen definitions file +(@pxref{Definitions File}). Each function will be cross referenced +with their sister functions in a @file{SEE ALSO} section. A global +@code{see_also} definition will be appended to this cross referencing text. + +@noindent +The two global definitions required are: + +@multitable @columnfractions .02 .15 .77 +@item @tab library +@tab This is the name of your library, without the @file{lib} prefix. +The AutoOpts library is named @file{libopts.so...}, so the @code{library} +attribute would have the value @code{opts}. +@item +@item @tab header +@tab Generally, using a library with a compiled program entails +@code{#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, @file{your-opts.h} is +specified. +@end multitable + +@noindent +The @code{export_func} definition should contain the following attributes: + +@multitable @columnfractions .02 .15 .77 +@item @tab name +@tab The name of the procedure the library user may call. +@item @tab what +@tab A brief sentence describing what the procedure does. +@item @tab doc +@tab A detailed description of what the procedure does. +It may ramble on for as long as necessary to properly describe it. +@item @tab err +@tab A short description of how errors are handled. +@item @tab ret_type +@tab The data type returned by the procedure. +Omit this for @code{void} procedures. +@item @tab ret_desc +@tab Describe what the returned value is, if needed. +@item @tab private +@tab If specified, the function will @strong{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. +@item +@item @tab arg +@tab This is a compound attribute that contains: +@end multitable +@multitable @columnfractions .02 .15 .15 .62 +@item @tab @tab arg_type +@tab The data type of the argument. +@item @tab @tab arg_name +@tab A short name for it. +@item @tab @tab arg_desc +@tab A brief description. +@end multitable + +@noindent +As a @file{getdefs} comment, this would appear something like this: + +@example +/*=--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. +=*/ +@end example + +@noindent +Note the @code{subblock} and @code{library} comments. +@code{subblock} is an embedded @file{getdefs} +option (@pxref{getdefs subblock}) that tells it how to parse the +@code{arg} attribute. The @code{library} and @code{header} entries +are global definitions that apply to all the documented functions. + +@c === SECTION MARKER + +@node getopt_long +@section Using getopt(3C) +@cindex getopt_long + +There is a template named, @code{getopt.tpl} that is distributed with +AutoOpts. Using that template instead of @code{options.tpl} will produce +completely independent source code that will parse command line options. It +will utilize either the standard @code{getopt(3C)} or the GNU +@code{getopt_long(3GNU)} function to drive the parsing. Which is used is +selected by the presence or absence of the @code{long-opts} program attribute. +It will save you from being dependent upon the @code{libopts} library @i{and} +it produces code ready for internationalization. However, it also carries +with it some limitations on the use of AutoOpts features and some requirements +on the build environment. + + +@menu +* getopt limitations:: getopt feature limitations +* getopt building:: getopt build requirements +@end menu + +@node getopt limitations +@subsection getopt feature limitations + +This list of limitations is relative to the full list of AutoOpts +supported features, @xref{Features}. + +@enumerate +@item +You cannot automatically take advantage of environment variable options or +automated parsing of configuration files (``rc'' or ``ini'' files). +Consequently, the resulting code does not support @file{--load-opts} or +@file{--save-opts} options automatically. + +@item +You cannot use set membership, enumerated, range checked or stacked +argument type options. In fact, you cannot use anything that depends +upon the @code{libopts} library. You are constrained to options that +take ``@code{string}'' arguments, though you may handle the option +argument with a callback procedure. + +@item +Special disablement and/or enablement prefixes are not recognized. + +@item +Generated @code{main()} procedures will not work. + +@item +Option coordination with external libraries will not work. + +@item +Every option must be ``settable'' because the emitted code +depends upon the @code{SET_OPT_XXX} macros having been defined. +Specify this as a global (program) attribute. + +@item +You must specify a main procedure of type ``main''. The +@file{getopt.tpl} template depends upon being able to compile the +traditional .c file into a program and get it to emit the usage text. + +@item +For the same reason, the traditional option parsing table code must be +emitted @b{before} the @file{getopt.tpl} template gets expanded. + +@item +The usage text is, therefore, statically defined. +@end enumerate + +@node getopt building +@subsection getopt build requirements + +You must supply some compile and link options via environment variables. + +@table @samp +@item srcdir +In case the option definition file lives in a different directory. +@item CFLAGS +Any special flags required to compile. The flags from +@code{autoopts-config cflags} will be included automatically. Since +the creation of the option parsing code includes creating a program +that prints out help text, if it is necessary to include files from +various directories to compile that program, you will need to specify +those directories with ``-Idirpath'' text in the @code{CFLAGS}. +Some experimentation may be necessary in that case. + +@strong{NOTE}: the ``-Idirpath'' text is only needed if your option callback +functions include code that require additional ``#include'' directives. +@item LDFLAGS +Any special flags required to link. The flags from +@code{autoopts-config ldflags} will be included automatically. This +is required only if additional link flags for the help text emission +program might be needed. +@item CC +This is needed only if ``@code{cc}'' cannot be found in @code{$PATH} +(or it is not the one you want). +@end table + +To use this, set the exported environment variables and specify ``getopt'' as +the default template in your option definitions file (@pxref{Identification}). +You will have @i{four} new files. Assuming your definitions were in a file +named @file{myprog-opts.def} and your program name was specified as +@file{progname}, the resulting files would be created: @file{myprog-opts.h}, +@file{myprog-opts.c}, @file{getopt-progname.h} and @file{getopt-progname.c}. +You must compile and link both @file{.c} files into your program. If there +are link failures, then you are using AutoOpts features that require the +@file{libopts} library. You must remove these features, +@xref{getopt limitations}. + +These generated files depend upon configure defines to work correctly. +Therefore, you must specify a @code{config-header} attribute +(@pxref{programming attributes}) and ensure it has @code{#defines} for +either @code{HAVE_STDINT_H} or @code{HAVE_INTTYPES_H}; either +@code{HAVE_SYS_LIMITS_H} or @code{HAVE_LIMITS_H}; and +@code{HAVE_SYSEXITS_H}, if the @file{sysexits.h} header is available. +The required header files for these defines are, respectively, +the @file{/usr/include} files named: +@itemize @bullet +@item stdint.h +@item inttypes.h +@item sys/limits.h +@item limits.h +@item sysexits.h +@end itemize + +@noindent +The following header files must also exist on the build platform: +@itemize @bullet +@item sys/types.h +@item stdio.h +@item string.h +@item unistd.h -- or, for getopt_long: +@item getopt.h +@end itemize +@c === SECTION MARKER + +@node i18n +@section Internationalizing AutoOpts +@cindex Internationalizing AutoOpts + +The generated code for AutoOpts will enable and disable the translation of +AutoOpts run time messages. If @code{ENABLE_NLS} is defined at compile time +and @code{no-xlate} has been not set to the value @emph{anything}, then the +@code{_()} macro may be used to specify a translation function. If undefined, +it will default to @code{gettext(3GNU)}. This define will also enable a +callback function that @code{optionProcess} invokes at the beginning of option +processing. The AutoOpts @code{libopts} library will always check for this +@emph{compiled with NLS} flag, so @code{libopts} does not need to be specially +compiled. The strings returned by the translation function will be +@code{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 @file{my-opts.c} file and adding the +distributed @file{po/usage-txt.pot} file. (Also by extracting the strings +yourself from the @file{usage-txt.h} file.) When you call +@code{optionProcess}, all of the user visible AutoOpts strings will be passed +through the localization procedure established with the @code{_()} +preprocessing macro. + +All of this is @emph{dis}-abled if you specify the global attribute +@code{no-xlate} to @emph{anything}. + +@c === SECTION MARKER + +@node Naming Conflicts +@section Naming Conflicts +@cindex 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 @code{opt_} +or @code{option}, or else they end with @code{_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 @code{prefix} (@pxref{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, @code{debug}, the emitted code will presume that @code{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, @code{HAVE_OPT(DEBUG)} or @code{HAVE_OPT(INTERNAL)} +(@pxref{HAVE_OPT}) in your code. You may trigger an obvious warning for such +conflicts by specifying the @code{guard-option-names} attribute +(@pxref{program attributes}). That emitted code will also @code{#undef}-ine +the conflicting name. + +@node All Attribute Names +@section All Attribute Names + +This is the list of all the option attributes used in the various +option processing templates. There are several flavors of attributes, +and these are not distinguished here. + +@itemize @bullet +@item +Valid, current attributes that you are encouraged to use. +@item +Internally generated attributes that you cannot use at all. +I need to prefix these with a distinguished prefix. e.g. ``ao-'' +@item +Valid attributes, but are deprecated. Alternates should be documented. +@end itemize + +This list is derived by running many example option definitions through the +option generation and man page templates and noting which attributes are +actually used. There may be a few that are used but not exercised in my +testing. If so, I need to ferret those out and test them, too. + +@example +aliases allow-errors arg-default +arg-optional arg-range arg-type +argument call-proc code +config-header copyright default +deprecated descrip detail +disable documentation eaddr +enable enabled environrc +equivalence exit-name explain +export extract-code field +file-fail-code flag flag-code +flag-proc flags-cant flags-must +full-usage gnu-usage guard-option-names +help-value homerc ifdef +ifndef immed-disable immediate +include lib-name library +long-opts main main-text +main-type max min +more-help-value must-set name +no-command no-libopts no-misuse-usage +no-preset no-xlate nomem-fail-code +omitted-usage package prefix +prefix-enum preserve-case prog-name +prog-title reorder-args resettable +scaled settable short-usage +stack-arg std-value test-main +translators unstack-arg usage +usage-message usage-opt usage-type +val-name val-upname value +version +@end example + +@node Option Define Names +@section Option Definition Name Index +@printindex vr + +@ignore +END == AUTOINFO == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore + +@c = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = = +@c +@c TRAILER + +@c LocalWords: AutoGen texinfo Korb tpl bruce Exp texi autogen setfilename AG +@c LocalWords: settitle setchapternewpage dne dircategory direntry ifinfo gpl +@c LocalWords: AutoOpts snprintfv titlepage vskip pt filll sp dir xref cindex +@c LocalWords: AutoGen's noindent rc ini enum IDX const az upcase ENDFOR ESAC +@c LocalWords: optargs egcs inclhack sh fixincl autoconf endif var templ dirs +@c LocalWords: def txt cd STR str ifdef alist downcase sprintf arg lexer +@c LocalWords: srcfile linenum subblock defParse srcdir sed POSIX printf expr +@c LocalWords: stdout expr func gfunc tr findex exparg desc desc sep macfunc +@c LocalWords: ing getdefs libopts src ksh forcomma csh env Sourced autoopts +@c LocalWords: mkmerge builddir ADDON AutoGetopts getopt glibc argp perl awk +@c LocalWords: printindex cp fn |