diff options
Diffstat (limited to 'doc/agdoc.texi')
| -rw-r--r-- | doc/agdoc.texi | 13607 |
1 files changed, 13607 insertions, 0 deletions
diff --git a/doc/agdoc.texi b/doc/agdoc.texi new file mode 100644 index 0000000..2d66161 --- /dev/null +++ b/doc/agdoc.texi @@ -0,0 +1,13607 @@ +@settitle GNU AutoGen - The Automated Program Generator +@setchapternewpage off +@syncodeindex pg cp +@c %**end of header +@copying +This manual is for GNU AutoGen version 5.16, updated August 2012. + +Copyright @copyright{} 1992-2012 by Bruce Korb. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.2 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +@end quotation +@end copying + +@ignore +EDIT THIS FILE WITH CAUTION (agdoc.texi) + +It has been AutoGen-ed August 11, 2012 at 09:42:32 AM by AutoGen 5.16.2 +From the definitions /old-home/bkorb/ag/ag/doc/ag-texi-30133.d/agdoc.def +and the template file auto_gen.tpl + +Plus bits and pieces gathered from all over the source/build +directories: + /old-home/bkorb/ag/ag/doc/auto_gen.tpl + /old-home/bkorb/ag/ag/agen5/opts.def + /old-home/bkorb/ag/ag/columns/invoke-columns.texi + /old-home/bkorb/ag/ag/getdefs/invoke-getdefs.texi + /old-home/bkorb/ag/ag/xml2ag/invoke-xml2ag.texi + /old-home/bkorb/ag/ag/doc/snprintfv.texi + /old-home/bkorb/ag/ag/agen5/defParse-fsm.c + /old-home/bkorb/ag/ag/agen5/opts.h + /old-home/bkorb/ag/ag/autoopts/libopts.texi + /old-home/bkorb/ag/ag/doc/autogen-intro.texi + /old-home/bkorb/ag/ag/agen5/invoke-autogen.texi + /old-home/bkorb/ag/ag/agen5/agShell.c + /old-home/bkorb/ag/ag/agen5/defDirect.c + /old-home/bkorb/ag/ag/agen5/expExtract.c + /old-home/bkorb/ag/ag/agen5/expFormat.c + /old-home/bkorb/ag/ag/agen5/expGperf.c + /old-home/bkorb/ag/ag/agen5/expGuile.c + /old-home/bkorb/ag/ag/agen5/expMake.c + /old-home/bkorb/ag/ag/agen5/expOutput.c + /old-home/bkorb/ag/ag/agen5/expPrint.c + /old-home/bkorb/ag/ag/agen5/expState.c + /old-home/bkorb/ag/ag/agen5/expString.c + /old-home/bkorb/ag/ag/agen5/fmemopen.c + /old-home/bkorb/ag/ag/agen5/funcCase.c + /old-home/bkorb/ag/ag/agen5/funcDef.c + /old-home/bkorb/ag/ag/agen5/funcEval.c + /old-home/bkorb/ag/ag/agen5/funcFor.c + /old-home/bkorb/ag/ag/agen5/funcIf.c + /old-home/bkorb/ag/ag/agen5/functions.c + /old-home/bkorb/ag/ag/agen5/schemedef.scm + /old-home/bkorb/ag/ag/doc/autogen-texi.txt + +@end ignore + +@dircategory GNU programming tools +@direntry +* AutoGen: (autogen). The Automated Program Generator +@end direntry + +@ifinfo +@ifnothtml +This file documents GNU AutoGen Version 5.16. + +AutoGen copyright @copyright{} 1992-2012 Bruce Korb +AutoOpts copyright @copyright{} 1992-2012 Bruce Korb +snprintfv copyright @copyright{} 1999-2000 Gary V. Vaughan + +AutoGen is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation, either version 3 of the License, or +(at your option) any later version. + +AutoGen is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +See the GNU General Public License for more details. + +You should have received a copy of the GNU General Public License along +with this program. If not, see <http://www.gnu.org/licenses/>. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph. +@end ignore +@end ifnothtml +@end ifinfo + +@finalout +@titlepage +@title AutoGen - The Automated Program Generator +@subtitle For version 5.16, August 2012 +@author Bruce Korb +@author @email{bkorb@@gnu.org} + +@page +@vskip 0pt plus 1filll +AutoGen copyright @copyright{} 1992-2012 Bruce Korb +@sp 2 +This is the second edition of the GNU AutoGen documentation, +@sp 2 +Published by Bruce Korb, 910 Redwood Dr., Santa Cruz, CA 95060 + +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/>. + +@insertcopying +@end titlepage + +@node Top, Introduction, , (dir) +@top The Automated Program Generator +@comment node-name, next, previous, up + +This file documents AutoGen version 5.16. It is a tool designed +for generating program files that contain repetitive text with varied +substitutions. This document is very long because it is intended as a +reference document. For a quick start example, @xref{Example Usage}. + +The AutoGen distribution includes the basic generator engine and +several add-on libraries and programs. Of the most general interest +would be Automated Option processing, @xref{AutoOpts}, which also +includes stand-alone support for configuration file parsing, @xref{Features}. +Please see the ``Add-on packages for AutoGen'' section for additional +programs and libraries associated with AutoGen. + +This edition documents version 5.16, August 2012. + + +@menu +* Introduction:: AutoGen's Purpose +* Definitions File:: AutoGen Definitions File +* Template File:: AutoGen Template +* Augmenting AutoGen:: Augmenting AutoGen Features +* autogen Invocation:: Invoking AutoGen +* Installation:: Configuring and Installing +* AutoOpts:: Automated Option Processing +* Add-Ons:: Add-on packages for AutoGen +* Future:: Some ideas for the future. +* Copying This Manual:: Copying This Manual +* Concept Index:: General index +* Function Index:: Function index +@end menu + +@ignore +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +@end ignore +@page +@node Introduction +@chapter Introduction +@cindex Introduction + +AutoGen is a tool designed for generating program files that contain +repetitive text with varied substitutions. Its goal is to simplify the +maintenance of programs that contain large amounts of repetitious text. +This is especially valuable if there are several blocks of such text +that must be kept synchronized in parallel tables. + +An obvious example is the problem of maintaining the code required for +processing program options and configuration settings. Processing options +requires a minimum of four different constructs be kept in proper order in +different places in your program. You need at least: + +@enumerate +@item +The flag character in the flag string, +@item +code to process the flag when it is encountered, +@item +a global state variable or two, and +@item +a line in the usage text. +@end enumerate + +@noindent +You will need more things besides this if you choose to implement long option +names, configuration (rc/ini) file processing, environment variable settings +and keep all the documentation for these up to date. This can be done +mechanically; with the proper templates and this program. In fact, it has +already been done and AutoGen itself uses it@: @xref{AutoOpts}. For a simple +example of Automated Option processing, @xref{Quick Start}. For a full list +of the Automated Option features, @xref{Features}. Be forewarned, though, the +feature list is ridiculously extensive. + +@menu +* Generalities:: The Purpose of AutoGen +* Example Usage:: A Simple Example +* csh/zsh caveat:: csh/zsh caveat +* Testimonial:: A User's Perspective +@end menu + +@c === SECTION MARKER + +@node Generalities +@section The Purpose of AutoGen + +The idea of this program is to have a text file, a template if +you will, that contains the general text of the desired output file. +That file includes substitution expressions and sections of text that are +replicated under the control of separate definition files. + +@cindex design goals + +AutoGen was designed with the following features: + +@enumerate +@item +The definitions are completely separate from the template. By completely +isolating the definitions from the template it greatly increases the +flexibility of the template implementation. A secondary goal is that a +template user only needs to specify those data that are necessary to describe +his application of a template. + +@item +Each datum in the definitions is named. Thus, the definitions can be +rearranged, augmented and become obsolete without it being necessary to +go back and clean up older definition files. Reduce incompatibilities! + +@item +Every definition name defines an array of values, even when there is +only one entry. These arrays of values are used to control the +replication of sections of the template. + +@item +There are named collections of definitions. They form a nested hierarchy. +Associated values are collected and associated with a group name. +These associated data are used collectively in sets of substitutions. + +@item +The template has special markers to indicate where substitutions are +required, much like the @code{$@{VAR@}} construct in a shell @code{here doc}. +These markers are not fixed strings. They are specified at the start of +each template. Template designers know best what fits into their +syntax and can avoid marker conflicts. + +We did this because it is burdensome and difficult to avoid conflicts +using either M4 tokenization or C preprocessor substitution rules. It +also makes it easier to specify expressions that transform the value. +Of course, our expressions are less cryptic than the shell methods. + +@item +These same markers are used, in conjunction with enclosed keywords, to +indicate sections of text that are to be skipped and for sections of +text that are to be repeated. This is a major improvement over using C +preprocessing macros. With the C preprocessor, you have no way of +selecting output text because it is an @i{un}varying, mechanical +substitution process. + +@item +Finally, we supply methods for carefully controlling the output. +Sometimes, it is just simply easier and clearer to compute some text or +a value in one context when its application needs to be later. So, +functions are available for saving text or values for later use. +@end enumerate + +@c === SECTION MARKER + +@node Example Usage +@section A Simple Example +@cindex example, simple AutoGen + +This is just one simple example that shows a few basic features. +If you are interested, you also may run "make check" with the +@code{VERBOSE} environment variable set and see a number of other +examples in the @file{agen5/test/testdir} directory. + +Assume you have an enumeration of names and you wish to associate some +string with each name. Assume also, for the sake of this example, +that it is either too complex or too large to maintain easily by hand. +We will start by writing an abbreviated version of what the result +is supposed to be. We will use that to construct our output templates. + +@noindent +In a header file, @file{list.h}, you define the enumeration +and the global array containing the associated strings: + +@example +typedef enum @{ + IDX_ALPHA, + IDX_BETA, + IDX_OMEGA @} list_enum; + +extern char const* az_name_list[ 3 ]; +@end example + +@noindent +Then you also have @file{list.c} that defines the actual strings: + +@example +#include "list.h" +char const* az_name_list[] = @{ + "some alpha stuff", + "more beta stuff", + "final omega stuff" @}; +@end example + +@noindent +First, we will define the information that is unique for each enumeration +name/string pair. This would be placed in a file named, @file{list.def}, +for example. + +@example +autogen definitions list; +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"; @}; +@end example + +The @code{autogen definitions list;} entry defines the file as an AutoGen +definition file that uses a template named @code{list}. That is followed by +three @code{list} entries that define the associations between the +enumeration names and the strings. The order of the differently named +elements inside of list is unimportant. They are reversed inside of the +@code{beta} entry and the output is unaffected. + +Now, to actually create the output, we need a template or two that can be +expanded into the files you want. In this program, we use a single template +that is capable of multiple output files. The definitions above refer to a +@file{list} template, so it would normally be named, @file{list.tpl}. + +It looks something like this. +(For a full description, @xref{Template File}.) + +@example +[+ AutoGen5 template h c +] +[+ CASE (suffix) +][+ + == h +] +typedef enum @{[+ + FOR list "," +] + IDX_[+ (string-upcase! (get "list_element")) +][+ + ENDFOR list +] @} list_enum; + +extern char const* az_name_list[ [+ (count "list") +] ]; +[+ + + == c +] +#include "list.h" +char const* az_name_list[] = @{[+ + FOR list "," +] + "[+list_info+]"[+ + ENDFOR list +] @};[+ + +ESAC +] +@end example + +The @code{[+ AutoGen5 template h c +]} text tells AutoGen that this is +an AutoGen version 5 template file; that it is to be processed twice; +that the start macro marker is @code{[+}; and the end marker is +@code{+]}. The template will be processed first with a suffix value of +@code{h} and then with @code{c}. Normally, the suffix values are +appended to the @file{base-name} to create the output file name. + +The @code{[+ == h +]} and @code{[+ == c +]} @code{CASE} selection clauses +select different text for the two different passes. In this example, +the output is nearly disjoint and could have been put in two separate +templates. However, sometimes there are common sections and this is +just an example. + +The @code{[+FOR list "," +]} and @code{[+ ENDFOR list +]} clauses delimit +a block of text that will be repeated for every definition of @code{list}. +Inside of that block, the definition name-value pairs that +are members of each @code{list} are available for substitutions. + +The remainder of the macros are expressions. Some of these contain +special expression functions that are dependent on AutoGen named values; +others are simply Scheme expressions, the result of which will be +inserted into the output text. Other expressions are names of AutoGen +values. These values will be inserted into the output text. For example, +@code{[+list_info+]} will result in the value associated with +the name @code{list_info} being inserted between the double quotes and +@code{(string-upcase! (get "list_element"))} will first "get" the value +associated with the name @code{list_element}, then change the case of +all the letters to upper case. The result will be inserted into the +output document. + +If you have compiled AutoGen, you can copy out the template and definitions +as described above and run @code{autogen list.def}. This will produce +exactly the hypothesized desired output. + +One more point, too. Lets say you decided it was too much trouble to figure +out how to use AutoGen, so you created this enumeration and string list with +thousands of entries. Now, requirements have changed and it has become +necessary to map a string containing the enumeration name into the enumeration +number. With AutoGen, you just alter the template to emit the table of names. +It will be guaranteed to be in the correct order, missing none of the entries. +If you want to do that by hand, well, good luck. + +@c === SECTION MARKER + +@node csh/zsh caveat +@section csh/zsh caveat + +AutoGen tries to use your normal shell so that you can supply shell code +in a manner you are accustomed to using. If, however, you use csh or +zsh, you cannot do this. Csh is sufficiently difficult to program that +it is unsupported. Zsh, though largely programmable, also has some +anomalies that make it incompatible with AutoGen usage. Therefore, when +invoking AutoGen from these environments, you must be certain to set the +SHELL environment variable to a Bourne-derived shell, e.g., sh, ksh or +bash. + +Any shell you choose for your own scripts need to follow these basic +requirements: + +@enumerate +@item +It handles @code{trap ":" $sig} without output to standard out. This is done +when the server shell is first started. If your shell does not handle this, +then it may be able to by loading functions from its start up files. +@item +At the beginning of each scriptlet, the command @code{\\cd $PWD} +is inserted. This ensures that @code{cd} is not aliased to something +peculiar and each scriptlet starts life in the execution directory. +@item +At the end of each scriptlet, the command @code{echo mumble} is +appended. The program you use as a shell must emit the single +argument @code{mumble} on a line by itself. +@end enumerate + +@c === SECTION MARKER + +@node Testimonial +@section A User's Perspective + +@format +Alexandre wrote: +> +> I'd appreciate opinions from others about advantages/disadvantages of +> each of these macro packages. +@end format + +I am using AutoGen in my pet project, and find one of its best points to +be that it separates the operational data from the implementation. + +Indulge me for a few paragraphs, and all will be revealed: +In the manual, Bruce cites the example of maintaining command line flags +inside the source code; traditionally spreading usage information, flag +names, letters and processing across several functions (if not files). +Investing the time in writing a sort of boiler plate (a template in +AutoGen terminology) pays by moving all of the option details (usage, +flags names etc.) into a well structured table (a definition file if you +will), so that adding a new command line option becomes a simple matter +of adding a set of details to the table. + +So far so good! Of course, now that there is a template, writing all of +that tedious optargs processing and usage functions is no longer an +issue. Creating a table of the options needed for the new project and +running AutoGen generates all of the option processing code in C +automatically from just the tabular data. AutoGen in fact already ships +with such a template... AutoOpts. + +One final consequence of the good separation in the design of AutoGen is +that it is retargetable to a greater extent. The +egcs/gcc/fixinc/inclhack.def can equally be used (with different +templates) to create a shell script (inclhack.sh) or a c program +(fixincl.c). + +This is just the tip of the iceberg. AutoGen is far more powerful than +these examples might indicate, and has many other varied uses. I am +certain Bruce or I could supply you with many and varied examples, and I +would heartily recommend that you try it for your project and see for +yourself how it compares to m4. +@cindex m4 + +As an aside, I would be interested to see whether someone might be +persuaded to rationalise autoconf with AutoGen in place of m4... Ben, +are you listening? autoconf-3.0! `kay? =)O| + +@format +Sincerely, + Gary V. Vaughan +@end format + +@ignore +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * +@end ignore +@page +@node Definitions File +@chapter Definitions File +@cindex definitions file +@cindex .def file + +This chapter describes the syntax and semantics of the AutoGen +definition file. In order to instantiate a template, you normally must +provide a definitions file that identifies itself and contains some +value definitions. Consequently, we keep it very simple. For +"advanced" users, there are preprocessing directives, sparse +arrays, named indexes and comments that may be used as well. + +The definitions file is used to associate values with names. Every +value is implicitly an array of values, even if there is only one value. +Values may be either simple strings or compound collections of +name-value pairs. An array may not contain both simple and compound +members. Fundamentally, it is as simple as: + +@example +prog-name = "autogen"; +flag = @{ + name = templ_dirs; + value = L; + descrip = "Template search directory list"; +@}; +@end example + +For purposes of commenting and controlling the processing of the +definitions, C-style comments and most C preprocessing directives are +honored. The major exception is that the @code{#if} directive is +ignored, along with all following text through the matching +@code{#endif} directive. The C preprocessor is not actually invoked, so +C macro substitution is @strong{not} performed. + +@menu +* Identification:: The Identification Definition +* Definitions:: Named Definitions +* Index Assignments:: Assigning an Index to a Definition +* Dynamic Text:: Dynamic Text +* Directives:: Controlling What Gets Processed +* Predefines:: Pre-defined Names +* Comments:: Commenting Your Definitions +* Example:: What it all looks like. +* Full Syntax:: Finite State Machine Grammar +* Alternate Definition:: Alternate Definition Forms +@end menu + +@c === SECTION MARKER + +@node Identification +@section The Identification Definition +@cindex identification + +The first definition in this file is used to identify it as a +AutoGen file. It consists of the two keywords, +@samp{autogen} and @samp{definitions} followed by the default +template name and a terminating semi-colon (@code{;}). That is: + +@example + AutoGen Definitions @var{template-name}; +@end example + +@noindent +Note that, other than the name @var{template-name}, the words +@samp{AutoGen} and @samp{Definitions} are searched for without case +sensitivity. Most lookups in this program are case insensitive. + +@noindent +Also, if the input contains more identification definitions, +they will be ignored. This is done so that you may include +(@pxref{Directives}) other definition files without an identification +conflict. + +@cindex template file + +@noindent +AutoGen uses the name of the template to find the corresponding template +file. It searches for the file in the following way, stopping when +it finds the file: + +@enumerate +@item +It tries to open @file{./@var{template-name}}. If it fails, +@item +it tries @file{./@var{template-name}.tpl}. +@item +It searches for either of these files in the directories listed in the +templ-dirs command line option. +@end enumerate + +If AutoGen fails to find the template file in one of these places, +it prints an error message and exits. + +@c === SECTION MARKER + +@node Definitions +@section Named Definitions +@cindex definitions + +A name is a sequence of characters beginning with an alphabetic character +(@code{a} through @code{z}) followed by zero or more alpha-numeric +characters and/or separator characters: hyphen (@code{-}), underscore +(@code{_}) or carat (@code{^}). Names are case insensitive. + +Any name may have multiple values associated with it. Every name may be +considered a sparse array of one or more elements. If there is more than +one value, the values my be accessed by indexing the value with +@code{[index]} or by iterating over them using the FOR (@pxref{FOR}) AutoGen +macro on it, as described in the next chapter. Sparse arrays are specified +by specifying an index when defining an entry +(@pxref{Index Assignments,, Assigning an Index to a Definition}). + +There are two kinds of definitions, @samp{simple} and @samp{compound}. +They are defined thus (@pxref{Full Syntax}): + +@example +compound_name '=' '@{' definition-list '@}' ';' + +simple-name[2] '=' string ';' + +no^text^name ';' +@end example + +@noindent +@code{simple-name} has the third index (index number 2) defined here. +@code{No^text^name} is a simple definition with a shorthand empty string +value. The string values for definitions may be specified in any of +several formation rules. + +@menu +* def-list:: Definition List +* double-quote-string:: Double Quote String +* single-quote-string:: Single Quote String +* simple-string:: An Unquoted String +* shell-generated:: Shell Output String +* scheme-generated:: Scheme Result String +* here-string:: A Here String +* concat-string:: Concatenated Strings +@end menu + +@cindex simple definitions +@cindex compound definitions + +@node def-list +@subsection Definition List + +@code{definition-list} is a list of definitions that may or may not +contain nested compound definitions. Any such definitions may +@strong{only} be expanded within a @code{FOR} block iterating over the +containing compound definition. @xref{FOR}. + +Here is, again, the example definitions from the previous chapter, +with three additional name value pairs. Two with an empty value +assigned (@var{first} and @var{last}), and a "global" @var{group_name}. + +@example +autogen definitions list; +group_name = example; +list = @{ list_element = alpha; first; + list_info = "some alpha stuff"; @}; +list = @{ list_info = "more beta stuff"; + list_element = beta; @}; +list = @{ list_element = omega; last; + list_info = "final omega stuff"; @}; +@end example + +@node double-quote-string +@subsection Double Quote String + +@cindex string, double quote +The string follows the C-style escaping, using the backslash to quote +(escape) the following character(s). Certain letters are translated to +various control codes (e.g. @code{\n}, @code{\f}, @code{\t}, etc.). +@code{x} introduces a two character hex code. @code{0} (the digit zero) +introduces a one to three character octal code (note: an octal byte followed +by a digit must be represented with three octal digits, thus: @code{"\0001"} +yielding a NUL byte followed by the ASCII digit 1). Any other character +following the backslash escape is simply inserted, without error, into the +string being formed. + +Like ANSI "C", a series of these strings, possibly intermixed with +single quote strings, will be concatenated together. + +@node single-quote-string +@subsection Single Quote String + +@cindex string, single quote +This is similar to the shell single-quote string. However, escapes +@code{\} are honored before another escape, single quotes @code{'} +and hash characters @code{#}. This latter is done specifically +to disambiguate lines starting with a hash character inside +of a quoted string. In other words, + +@example +fumble = ' +#endif +'; +@end example + +could be misinterpreted by the definitions scanner, whereas +this would not: + +@example +fumble = ' +\#endif +'; +@end example + +@* +As with the double quote string, a series of these, even intermixed +with double quote strings, will be concatenated together. + +@node simple-string +@subsection An Unquoted String + +A simple string that does not contain white space @i{may} be left +unquoted. The string must not contain any of the characters special to +the definition text (i.e., @code{"}, @code{#}, @code{'}, @code{(}, +@code{)}, @code{,}, @code{;}, @code{<}, @code{=}, @code{>}, @code{[}, +@code{]}, @code{`}, @code{@{}, or @code{@}}). This list is subject to +change, but it will never contain underscore (@code{_}), period +(@code{.}), slash (@code{/}), colon (@code{:}), hyphen (@code{-}) or +backslash (@code{\\}). Basically, if the string looks like it is a +normal DOS or UNIX file or variable name, and it is not one of two +keywords (@samp{autogen} or @samp{definitions}) then it is OK to not +quote it, otherwise you should. + +@node shell-generated +@subsection Shell Output String +@cindex shell-generated string + +@cindex string, shell output +This is assembled according to the same rules as the double quote string, +except that there is no concatenation of strings and the resulting string is +written to a shell server process. The definition takes on the value of +the output string. + +NB@: The text is interpreted by a server shell. There may be left over +state from previous server shell processing. This scriptlet may also leave +state for subsequent processing. However, a @code{cd} to the original +directory is always issued before the new command is issued. + +@node scheme-generated +@subsection Scheme Result String + +A scheme result string must begin with an open parenthesis @code{(}. +The scheme expression will be evaluated by Guile and the +value will be the result. The AutoGen expression functions +are @strong{dis}abled at this stage, so do not use them. + +@node here-string +@subsection A Here String +@cindex here-string + +A @samp{here string} is formed in much the same way as a shell here doc. It +is denoted with two less than characters(@code{<<}) and, optionally, a hyphen. +This is followed by optional horizontal white space and an ending +marker-identifier. This marker must follow the syntax rules for identifiers. +Unlike the shell version, however, you must not quote this marker. + +The resulting string will start with the first character on the next line and +continue up to but not including the newline that precedes the line that +begins with the marker token. The characters are copied directly into the +result string. Mostly. + +If a hyphen follows the less than characters, then leading tabs will be +stripped and the terminating marker will be recognized even if preceded by +tabs. Also, if the first character on the line (after removing tabs) is a +backslash and the next character a tab, then the backslash will be removed as +well. No other kind of processing is done on this string. + +Here are two examples: +@example +str1 = <<- STR_END + $quotes = " ' ` + STR_END; + +str2 = << STR_END + $quotes = " ' ` + STR_END; +STR_END; +@end example +The first string contains no new line characters. +The first character is the dollar sign, the last the back quote. + +The second string contains one new line character. The first character +is the tab character preceding the dollar sign. The last character is +the semicolon after the @code{STR_END}. That @code{STR_END} does not +end the string because it is not at the beginning of the line. In the +preceding case, the leading tab was stripped. + +@node concat-string +@subsection Concatenated Strings +@cindex concat-string + +If single or double quote characters are used, +then you also have the option, a la ANSI-C syntax, +of implicitly concatenating a series of them together, +with intervening white space ignored. + +NB@: You @strong{cannot} use directives to alter the string +content. That is, + +@example +str = "fumble" +#ifdef LATER + "stumble" +#endif + ; +@end example + +@noindent +will result in a syntax error. The preprocessing directives are not +carried out by the C preprocessor. However, + +@example +str = '"fumble\n" +#ifdef LATER +" stumble\n" +#endif +'; +@end example + +@noindent +@strong{Will} work. It will enclose the @samp{#ifdef LATER} +and @samp{#endif} in the string. But it may also wreak +havoc with the definition processing directives. The hash +characters in the first column should be disambiguated with +an escape @code{\} or join them with previous lines: +@code{"fumble\n#ifdef LATER...}. + +@c === SECTION MARKER + +@node Index Assignments +@section Assigning an Index to a Definition +@cindex Definition Index + +In AutoGen, every name is implicitly an array of values. +When assigning values, they are usually implicitly +assigned to the next highest slot. They can also be +specified explicitly: + +@example +mumble[9] = stumble; +mumble[0] = grumble; +@end example + +@noindent +If, subsequently, you assign a value to @code{mumble} without an +index, its index will be @code{10}, not @code{1}. +If indexes are specified, they must not cause conflicts. + +@code{#define}-d names may also be used for index values. +This is equivalent to the above: + +@example +#define FIRST 0 +#define LAST 9 +mumble[LAST] = stumble; +mumble[FIRST] = grumble; +@end example + +All values in a range do @strong{not} have to be filled in. +If you leave gaps, then you will have a sparse array. This +is fine (@pxref{FOR}). You have your choice of iterating +over all the defined values, or iterating over a range +of slots. This: + +@example +[+ FOR mumble +][+ ENDFOR +] +@end example + +@noindent +iterates over all and only the defined entries, whereas this: + +@example +[+ FOR mumble (for-by 1) +][+ ENDFOR +] +@end example + +@noindent +will iterate over all 10 "slots". Your template will +likely have to contain something like this: + +@example +[+ IF (exist? (sprintf "mumble[%d]" (for-index))) +] +@end example + +@noindent +or else "mumble" will have to be a compound value that, +say, always contains a "grumble" value: + +@example +[+ IF (exist? "grumble") +] +@end example + +@c === SECTION MARKER + +@node Dynamic Text +@section Dynamic Text +@cindex Dynamic Definition Text + +There are several methods for including dynamic content inside a definitions +file. Three of them are mentioned above (@ref{shell-generated} and +@pxref{scheme-generated}) in the discussion of string formation rules. +Another method uses the @code{#shell} processing directive. +It will be discussed in the next section (@pxref{Directives}). +Guile/Scheme may also be used to yield to create definitions. + +When the Scheme expression is preceded by a backslash and single +quote, then the expression is expected to be an alist of +names and values that will be used to create AutoGen definitions. + +@noindent +This method can be be used as follows: + +@example +\'( (name (value-expression)) + (name2 (another-expr)) ) +@end example + +@noindent +This is entirely equivalent to: + +@example +name = (value-expression); +name2 = (another-expr); +@end example + +@noindent +Under the covers, the expression gets handed off to a Guile function +named @code{alist->autogen-def} in an expression that looks like this: + +@example +(alist->autogen-def + ( (name (value-expression)) (name2 (another-expr)) ) ) +@end example + +@node Directives +@section Controlling What Gets Processed +@cindex directives + +Definition processing directives can @strong{only} be processed +if the '#' character is the first character on a line. Also, if you +want a '#' as the first character of a line in one of your string +assignments, you should either escape it by preceding it with a +backslash @samp{\}, or by embedding it in the string as in @code{"\n#"}. + +All of the normal C preprocessing directives are recognized, though +several are ignored. There is also an additional @code{#shell} - +@code{#endshell} pair. Another minor difference is that AutoGen +directives must have the hash character (@code{#}) in column 1. + +The final tweak is that @code{#!} is treated as a comment line. +Using this feature, you can use: @samp{#! /usr/local/bin/autogen} +as the first line of a definitions file, set the mode to executable +and "run" the definitions file as if it were a direct invocation of +AutoGen. This was done for its hack value. + +The ignored directives are: +@code{#ident}, @code{#let}, @code{#pragma}, and @code{#if}. +Note that when ignoring the @code{#if} directive, all intervening +text through its matching @code{#endif} is also ignored, +including the @code{#else} clause. + +The AutoGen directives that affect the processing of +definitions are: + +@table @code +@item #assert `shell-script` | (scheme-expr) | <anything else> +@cindex #assert +@cindex assert directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 406. +@end ignore + +If the @code{shell-script} or @code{scheme-expr} do not yield @code{true} +valued results, autogen will be aborted. If @code{<anything else>} or +nothing at all is provided, then this directive is ignored. + +When writing the shell script, remember this is on a preprocessing +line. Multiple lines must be backslash continued and the result is a +single long line. Separate multiple commands with semi-colons. + +The result is @code{false} (and fails) if the result is empty, the +number zero, or a string that starts with the letters 'n' or 'f' ("no" +or "false"). + +@item #define name [ <text> ] +@cindex #define +@cindex define directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 469. +@end ignore + +Will add the name to the define list as if it were a DEFINE program +argument. Its value will be the first non-whitespace token following +the name. Quotes are @strong{not} processed. + +After the definitions file has been processed, any remaining entries +in the define list will be added to the environment. + +@item #elif +@cindex #elif +@cindex elif directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 542. +@end ignore + +This must follow an @code{#if} +otherwise it will generate an error. +It will be ignored. + +@item #else +@cindex #else +@cindex else directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 560. +@end ignore + +This must follow an @code{#if}, @code{#ifdef} or @code{#ifndef}. +If it follows the @code{#if}, then it will be ignored. Otherwise, +it will change the processing state to the reverse of what it was. + +@item #endif +@cindex #endif +@cindex endif directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 578. +@end ignore + +This must follow an @code{#if}, @code{#ifdef} or @code{#ifndef}. +In all cases, this will resume normal processing of text. + +@item #endmac +@cindex #endmac +@cindex endmac directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 595. +@end ignore + +This terminates a "macdef", but must not ever be encountered directly. + +@item #endshell +@cindex #endshell +@cindex endshell directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 611. +@end ignore + +Ends the text processed by a command shell into autogen definitions. + +@item #error [ <descriptive text> ] +@cindex #error +@cindex error directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 631. +@end ignore + +This directive will cause AutoGen to stop processing +and exit with a status of EXIT_FAILURE. + + +@item #if [ <ignored conditional expression> ] +@cindex #if +@cindex if directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 656. +@end ignore + +@code{#if} expressions are not analyzed. @strong{Everything} from here +to the matching @code{#endif} is skipped. + +@item #ifdef name-to-test +@cindex #ifdef +@cindex ifdef directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 673. +@end ignore + +The definitions that follow, up to the matching @code{#endif} will be +processed only if there is a corresponding @code{-Dname} command line +option or if a @code{#define} of that name has been previously encountered. + +@item #ifndef name-to-test +@cindex #ifndef +@cindex ifndef directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 692. +@end ignore + +The definitions that follow, up to the matching @code{#endif} will be +processed only if there is @strong{not} a corresponding @code{-Dname} +command line option or there was a canceling @code{-Uname} option. + +@item #include unadorned-file-name +@cindex #include +@cindex include directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 711. +@end ignore + +This directive will insert definitions from another file into +the current collection. If the file name is adorned with +double quotes or angle brackets (as in a C program), then the +include is ignored. + + +@item #line +@cindex #line +@cindex line directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 829. +@end ignore + +Alters the current line number and/or file name. You may wish to +use this directive if you extract definition source from other files. +@command{getdefs} uses this mechanism so AutoGen will report the correct +file and approximate line number of any errors found in extracted +definitions. + +@item #macdef +@cindex #macdef +@cindex macdef directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 873. +@end ignore + +This is a new AT&T research preprocessing directive. Basically, it is +a multi-line #define that may include other preprocessing directives. + +@item #option opt-name [ <text> ] +@cindex #option +@cindex option directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 888. +@end ignore + +This directive will pass the option name and associated text to the +AutoOpts optionLoadLine routine (@pxref{libopts-optionLoadLine}). The +option text may span multiple lines by continuing them with a backslash. +The backslash/newline pair will be replaced with two space characters. +This directive may be used to set a search path for locating template files +For example, this: + +@example +#option templ-dirs $ENVVAR/dirname +@end example +@noindent +will direct autogen to use the @code{ENVVAR} environment variable to find +a directory named @code{dirname} that (may) contain templates. Since these +directories are searched in most recently supplied first order, search +directories supplied in this way will be searched before any supplied on +the command line. + + +@item #shell +@cindex #shell +@cindex shell directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 925. +@end ignore + +Invokes @code{$SHELL} or @file{/bin/sh} on a script that should +generate AutoGen definitions. It does this using the same server +process that handles the back-quoted @code{`} text. +@strong{CAUTION}@: let not your @code{$SHELL} be @code{csh}. + +@item #undef name-to-undefine +@cindex #undef +@cindex undef directive + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/defDirect.c line 1025. +@end ignore + +Will remove any entries from the define list +that match the undef name pattern. +@end table +@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 +@node Full Syntax +@section Finite State Machine Grammar + +The preprocessing directives and comments are not part of the grammar. They +are handled by the scanner/lexer. The following was extracted directly from +the generated defParse-fsm.c source file. The "EVT:" is the token seen, +the "STATE:" is the current state and the entries in this table describe +the next state and the action to take. Invalid transitions were removed +from the table. + +@ignore +Extracted from $top_srcdir/agen5/defParse.y +@end ignore +@example +dp_trans_table[ DP_STATE_CT ][ DP_EVENT_CT ] = @{ + + /* STATE 0: DP_ST_INIT */ + @{ @{ DP_ST_NEED_DEF, NULL @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 1: DP_ST_NEED_DEF */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_NEED_TPL, NULL @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 2: DP_ST_NEED_TPL */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_NEED_SEMI, dp_do_tpl_name @}, /* EVT: VAR_NAME */ + @{ DP_ST_NEED_SEMI, dp_do_tpl_name @}, /* EVT: OTHER_NAME */ + @{ DP_ST_NEED_SEMI, dp_do_tpl_name @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 3: DP_ST_NEED_SEMI */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_NEED_NAME, NULL @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 4: DP_ST_NEED_NAME */ + @{ @{ DP_ST_NEED_DEF, NULL @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_DONE, dp_do_need_name_end @}, /* EVT: End-Of-File */ + @{ DP_ST_HAVE_NAME, dp_do_need_name_var_name @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_HAVE_VALUE, dp_do_end_block @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 5: DP_ST_HAVE_NAME */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_NEED_NAME, dp_do_empty_val @}, /* EVT: ; */ + @{ DP_ST_NEED_VALUE, dp_do_have_name_lit_eq @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_NEED_IDX, NULL @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 6: DP_ST_NEED_VALUE */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_HAVE_VALUE, dp_do_str_value @}, /* EVT: VAR_NAME */ + @{ DP_ST_HAVE_VALUE, dp_do_str_value @}, /* EVT: OTHER_NAME */ + @{ DP_ST_HAVE_VALUE, dp_do_str_value @}, /* EVT: STRING */ + @{ DP_ST_HAVE_VALUE, dp_do_str_value @}, /* EVT: HERE_STRING */ + @{ DP_ST_HAVE_VALUE, dp_do_str_value @}, /* EVT: NUMBER */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_NEED_NAME, dp_do_start_block @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 7: DP_ST_NEED_IDX */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_NEED_CBKT, dp_do_indexed_name @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_NEED_CBKT, dp_do_indexed_name @}, /* EVT: NUMBER */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 8: DP_ST_NEED_CBKT */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INDX_NAME, NULL @} /* EVT: ] */ + + /* STATE 9: DP_ST_INDX_NAME */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_NEED_NAME, dp_do_empty_val @}, /* EVT: ; */ + @{ DP_ST_NEED_VALUE, NULL @}, /* EVT: = */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ + + /* STATE 10: DP_ST_HAVE_VALUE */ + @{ @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: AUTOGEN */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: DEFINITIONS */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: End-Of-File */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: VAR_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: OTHER_NAME */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: HERE_STRING */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: NUMBER */ + @{ DP_ST_NEED_NAME, NULL @}, /* EVT: ; */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: = */ + @{ DP_ST_NEED_VALUE, dp_do_next_val @}, /* EVT: , */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @{ */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: @} */ + @{ DP_ST_INVALID, dp_do_invalid @}, /* EVT: [ */ + @{ DP_ST_INVALID, dp_do_invalid @} /* EVT: ] */ +@end example +@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 + +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + +@end ignore +@page +@node AutoGen Functions +@section AutoGen Scheme Functions + +AutoGen uses Guile to interpret Scheme expressions within AutoGen +macros. All of the normal Guile functions are available, plus several +extensions (@pxref{Common Functions}) have been added to +augment the repertoire of string manipulation functions and +manage the state of AutoGen processing. + +This section describes those functions that are specific to AutoGen. +Please take note that these AutoGen specific functions are not loaded +and thus not made available until after the command line options have +been processed and the AutoGen definitions have been loaded. They may, +of course, be used in Scheme functions that get defined at those times, +but they cannot be invoked. + +@menu +* SCM ag-fprintf:: @file{ag-fprintf} - format to autogen stream +* SCM ag-function?:: @file{ag-function?} - test for function +* SCM base-name:: @file{base-name} - base output name +* SCM chdir:: @file{chdir} - Change current directory +* SCM count:: @file{count} - definition count +* SCM def-file:: @file{def-file} - definitions file name +* SCM def-file-line:: @file{def-file-line} - get a definition file+line number +* SCM dne:: @file{dne} - "Do Not Edit" warning +* SCM emit:: @file{emit} - emit the text for each argument +* SCM emit-string-table:: @file{emit-string-table} - output a string table +* SCM error:: @file{error} - display message and exit +* SCM exist?:: @file{exist?} - test for value name +* SCM find-file:: @file{find-file} - locate a file in the search path +* SCM first-for?:: @file{first-for?} - detect first iteration +* SCM for-by:: @file{for-by} - set iteration step +* SCM for-from:: @file{for-from} - set initial index +* SCM for-index:: @file{for-index} - get current loop index +* SCM for-sep:: @file{for-sep} - set loop separation string +* SCM for-to:: @file{for-to} - set ending index +* SCM get:: @file{get} - get named value +* SCM get-c-name:: @file{get-c-name} - get named value, mapped to C name syntax +* SCM get-down-name:: @file{get-down-name} - get lower cased named value, mapped to C name syntax +* SCM get-up-name:: @file{get-up-name} - get upper cased named value, mapped to C name syntax +* SCM high-lim:: @file{high-lim} - get highest value index +* SCM last-for?:: @file{last-for?} - detect last iteration +* SCM len:: @file{len} - get count of values +* SCM low-lim:: @file{low-lim} - get lowest value index +* SCM make-header-guard:: @file{make-header-guard} - make self-inclusion guard +* SCM make-tmp-dir:: @file{make-tmp-dir} - create a temporary directory +* SCM match-value?:: @file{match-value?} - test for matching value +* SCM out-delete:: @file{out-delete} - delete current output file +* SCM out-depth:: @file{out-depth} - output file stack depth +* SCM out-emit-suspended:: @file{out-emit-suspended} - emit the text of suspended output +* SCM out-line:: @file{out-line} - output file line number +* SCM out-move:: @file{out-move} - change name of output file +* SCM out-name:: @file{out-name} - current output file name +* SCM out-pop:: @file{out-pop} - close current output file +* SCM out-push-add:: @file{out-push-add} - append output to file +* SCM out-push-new:: @file{out-push-new} - purge and create output file +* SCM out-resume:: @file{out-resume} - resume suspended output file +* SCM out-suspend:: @file{out-suspend} - suspend current output file +* SCM out-switch:: @file{out-switch} - close and create new output +* SCM output-file-next-line:: @file{output-file-next-line} - print the file name and next line number +* SCM set-option:: @file{set-option} - Set a command line option +* SCM set-writable:: @file{set-writable} - Make the output file be writable +* SCM stack:: @file{stack} - make list of AutoGen values +* SCM stack-join:: @file{stack-join} - stack values then join them +* SCM suffix:: @file{suffix} - get the current suffix +* SCM tpl-file:: @file{tpl-file} - get the template file name +* SCM tpl-file-line:: @file{tpl-file-line} - get the template file+line number +* SCM tpl-file-next-line:: @file{tpl-file-next-line} - get the template file plus next line number +* SCM autogen-version:: @file{autogen-version} - ``5.16.2'' +* SCM c-file-line-fmt:: format file info as, ``@code{#line nn "file"}'' +@end menu + + +@node SCM ag-fprintf +@subsection @file{ag-fprintf} - format to autogen stream +@findex ag-fprintf + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 444. +@end ignore + +Usage: (ag-fprintf ag-diversion format [ format-arg ... ]) +@* +Format a string using arguments from the alist. +Write to a specified AutoGen diversion. +That may be either a specified suspended output stream +(@pxref{SCM out-suspend}) or an index into the output stack +(@pxref{SCM out-push-new}). @code{(ag-fprintf 0 ...)} is +equivalent to @code{(emit (sprintf ...))}, and +@code{(ag-fprintf 1 ...)} sends output to the most recently +suspended output stream. + +Arguments: +@* +ag-diversion - AutoGen diversion name or number +@* +format - formatting string +@* +format-arg - Optional - list of arguments to formatting string + +@node SCM ag-function? +@subsection @file{ag-function?} - test for function +@findex ag-function? + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 379. +@end ignore + +Usage: (ag-function? ag-name) +@* +return SCM_BOOL_T if a specified name is a user-defined AutoGen +macro, otherwise return SCM_BOOL_F. + +Arguments: +@* +ag-name - name of AutoGen macro + +@node SCM base-name +@subsection @file{base-name} - base output name +@findex base-name + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 213. +@end ignore + +Usage: (base-name) +@* +Returns a string containing the base name of the output file(s). +Generally, this is also the base name of the definitions file. + +This Scheme function takes no arguments. + +@node SCM chdir +@subsection @file{chdir} - Change current directory +@findex chdir + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/agShell.c line 26. +@end ignore + +Usage: (chdir dir) +@* +Sets the current directory for AutoGen. Shell commands will run +from this directory as well. This is a wrapper around the Guile +native function. It returns its directory name argument and +fails the program on failure. + +Arguments: +@* +dir - new directory name + +@node SCM count +@subsection @file{count} - definition count +@findex count + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 308. +@end ignore + +Usage: (count ag-name) +@* +Count the number of entries for a definition. +The input argument must be a string containing the name +of the AutoGen values to be counted. If there is no +value associated with the name, the result is an SCM +immediate integer value of zero. + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM def-file +@subsection @file{def-file} - definitions file name +@findex def-file + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 329. +@end ignore + +Usage: (def-file) +@* +Get the name of the definitions file. +Returns the name of the source file containing the AutoGen +definitions. + +This Scheme function takes no arguments. + +@node SCM def-file-line +@subsection @file{def-file-line} - get a definition file+line number +@findex def-file-line + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 754. +@end ignore + +Usage: (def-file-line ag-name [ msg-fmt ]) +@* +Returns the file and line number of a AutoGen defined value, using +either the default format, "from %s line %d", or else the format you +supply. For example, if you want to insert a "C" language file-line +directive, you would supply the format "# %2$d \"%1$s\"", but that +is also already supplied with the scheme variable +@xref{SCM c-file-line-fmt}. You may use it thus: + +@example +(def-file-line "ag-def-name" c-file-line-fmt) +@end example + +It is also safe to use the formatting string, "%2$d". AutoGen uses +an argument vector version of printf: @xref{snprintfv}. + +Arguments: +@* +ag-name - name of AutoGen value +@* +msg-fmt - Optional - formatting for line message + +@node SCM dne +@subsection @file{dne} - "Do Not Edit" warning +@findex dne + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 33. +@end ignore + +Usage: (dne prefix [ first_prefix ] [ optpfx ]) +@* +Generate a "DO NOT EDIT" or "EDIT WITH CARE" warning string. +Which depends on whether or not the @code{--writable} command line +option was set. + +The first argument may be an option: -d + +This will suppress the variable text (date and version information). +If specified, then the "prefix" and "first" arguments are shifted +to the next arguments. + +The first argument is a per-line string prefix. The optional second +argument is a prefix for the first-line and, in read-only mode, activates +the editor hints. +@* +@example +-*- buffer-read-only: t -*- vi: set ro: +@end example +@noindent +The warning string also includes information about the template used +to construct the file and the definitions used in its instantiation. + +The optional third argument is used when the first argument is actually an +invocation option and the prefix arguments get shifted. The first +argument must be, specifically, "@code{-d}". That is used to signify that +the date stamp should not be inserted into the output. + +Arguments: +@* +prefix - string for starting each output line +@* +first_prefix - Optional - for the first output line +@* +optpfx - Optional - shifted prefix + +@node SCM emit +@subsection @file{emit} - emit the text for each argument +@findex emit + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcEval.c line 323. +@end ignore + +Usage: (emit alist ...) +@* +Walk the tree of arguments, displaying the values of displayable +SCM types. EXCEPTION: if the first argument is a number, then +that number is used to index the output stack. "0" is the default, +the current output. + +Arguments: +@* +alist - list of arguments to stringify and emit + +@node SCM emit-string-table +@subsection @file{emit-string-table} - output a string table +@findex emit-string-table + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 279. +@end ignore + +Usage: (emit-string-table st-name) +@* +Emit into the current output stream a +@code{static char const} array named @code{st-name} +that will have @code{NUL} bytes between each inserted string. + +Arguments: +@* +st-name - the name of the array of characters + +@node SCM error +@subsection @file{error} - display message and exit +@findex error + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 160. +@end ignore + +Usage: (error message) +@* +The argument is a string that printed out as part of an error +message. The message is formed from the formatting string: + +@example +DEFINITIONS ERROR in %s line %d for %s: %s\n +@end example + +The first three arguments to this format are provided by the +routine and are: The name of the template file, the line within +the template where the error was found, and the current output +file name. + +After displaying the message, the current output file is removed +and autogen exits with the EXIT_FAILURE error code. IF, however, +the argument begins with the number 0 (zero), or the string is the +empty string, then processing continues with the next suffix. + +Arguments: +@* +message - message to display before exiting + +@node SCM exist? +@subsection @file{exist?} - test for value name +@findex exist? + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 344. +@end ignore + +Usage: (exist? ag-name) +@* +return SCM_BOOL_T iff a specified name has an AutoGen value. +The name may include indexes and/or member names. +All but the last member name must be an aggregate definition. +For example: +@example +(exist? "foo[3].bar.baz") +@end example +will yield true if all of the following is true: +@* +There is a member value of either group or string type +named @code{baz} for some group value @code{bar} that +is a member of the @code{foo} group with index @code{3}. +There may be multiple entries of @code{bar} within +@code{foo}, only one needs to contain a value for @code{baz}. + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM find-file +@subsection @file{find-file} - locate a file in the search path +@findex find-file + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expExtract.c line 313. +@end ignore + +Usage: (find-file file-name [ suffix ]) +@* +AutoGen has a search path that it uses to locate template and definition +files. This function will search the same list for @file{file-name}, both +with and without the @file{.suffix}, if provided. + +Arguments: +@* +file-name - name of file with text +@* +suffix - Optional - file suffix to try, too + +@node SCM first-for? +@subsection @file{first-for?} - detect first iteration +@findex first-for? + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 79. +@end ignore + +Usage: (first-for? [ for_var ]) +@* +Returns @code{SCM_BOOL_T} if the named FOR loop (or, if not named, the +current innermost loop) is on the first pass through the data. Outside +of any @code{FOR} loop, it returns @code{SCM_UNDEFINED}, @pxref{FOR}. + +Arguments: +@* +for_var - Optional - which for loop + +@node SCM for-by +@subsection @file{for-by} - set iteration step +@findex for-by + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 189. +@end ignore + +Usage: (for-by by) +@* +This function records the "step by" information +for an AutoGen FOR function. +Outside of the FOR macro itself, this function will emit an error. +@xref{FOR}. + +Arguments: +@* +by - the iteration increment for the AutoGen FOR macro + +@node SCM for-from +@subsection @file{for-from} - set initial index +@findex for-from + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 147. +@end ignore + +Usage: (for-from from) +@* +This function records the initial index information +for an AutoGen FOR function. +Outside of the FOR macro itself, this function will emit an error. +@xref{FOR}. + +Arguments: +@* +from - the initial index for the AutoGen FOR macro + +@node SCM for-index +@subsection @file{for-index} - get current loop index +@findex for-index + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 125. +@end ignore + +Usage: (for-index [ for_var ]) +@* +Returns the current index for the named @code{FOR} loop. +If not named, then the index for the innermost loop. +Outside of any FOR loop, it returns @code{SCM_UNDEFINED}, @xref{FOR}. + +Arguments: +@* +for_var - Optional - which for loop + +@node SCM for-sep +@subsection @file{for-sep} - set loop separation string +@findex for-sep + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 209. +@end ignore + +Usage: (for-sep separator) +@* +This function records the separation string that is to be inserted +between each iteration of an AutoGen FOR function. This is often +nothing more than a comma. +Outside of the FOR macro itself, this function will emit an error. + +Arguments: +@* +separator - the text to insert between the output of +each FOR iteration + +@node SCM for-to +@subsection @file{for-to} - set ending index +@findex for-to + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 168. +@end ignore + +Usage: (for-to to) +@* +This function records the terminating value information +for an AutoGen FOR function. +Outside of the FOR macro itself, this function will emit an error. +@xref{FOR}. + +Arguments: +@* +to - the final index for the AutoGen FOR macro + +@node SCM get +@subsection @file{get} - get named value +@findex get + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 434. +@end ignore + +Usage: (get ag-name [ alt-val ]) +@* +Get the first string value associated with the name. +It will either return the associated string value (if +the name resolves), the alternate value (if one is provided), +or else the empty string. + +Arguments: +@* +ag-name - name of AutoGen value +@* +alt-val - Optional - value if not present + +@node SCM get-c-name +@subsection @file{get-c-name} - get named value, mapped to C name syntax +@findex get-c-name + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 466. +@end ignore + +Usage: (get-c-name ag-name) +@* +Get the first string value associated with the name. It will either +return the associated string value (if the name resolves), the alternate +value (if one is provided), or else the empty string. The result is +passed through "string->c-name!". + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM get-down-name +@subsection @file{get-down-name} - get lower cased named value, mapped to C name syntax +@findex get-down-name + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 507. +@end ignore + +Usage: (get-down-name ag-name) +@* +Get the first string value associated with the name. It will either +return the associated string value (if the name resolves), the alternate +value (if one is provided), or else the empty string. The result is +passed through "string->c-name!" and "string->down-case!". + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM get-up-name +@subsection @file{get-up-name} - get upper cased named value, mapped to C name syntax +@findex get-up-name + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 487. +@end ignore + +Usage: (get-up-name ag-name) +@* +Get the first string value associated with the name. It will either +return the associated string value (if the name resolves), the alternate +value (if one is provided), or else the empty string. The result is +passed through "string->c-name!" and "string->up-case!". + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM high-lim +@subsection @file{high-lim} - get highest value index +@findex high-lim + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 527. +@end ignore + +Usage: (high-lim ag-name) +@* +Returns the highest index associated with an array of definitions. +This is generally, but not necessarily, one less than the +@code{count} value. (The indexes may be specified, rendering a +non-zero based or sparse array of values.) + +This is very useful for specifying the size of a zero-based array +of values where not all values are present. For example: + +@example +tMyStruct myVals[ [+ (+ 1 (high-lim "my-val-list")) +] ]; +@end example + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM last-for? +@subsection @file{last-for?} - detect last iteration +@findex last-for? + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 104. +@end ignore + +Usage: (last-for? [ for_var ]) +@* +Returns SCM_BOOL_T if the named FOR loop (or, if not named, the +current innermost loop) is on the last pass through the data. +Outside of any FOR loop, it returns SCM_UNDEFINED. +@xref{FOR}. + +Arguments: +@* +for_var - Optional - which for loop + +@node SCM len +@subsection @file{len} - get count of values +@findex len + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 573. +@end ignore + +Usage: (len ag-name) +@* +If the named object is a group definition, then "len" is +the same as "count". Otherwise, if it is one or more text +definitions, then it is the sum of their string lengths. +If it is a single text definition, then it is equivalent to +@code{(string-length (get "ag-name"))}. + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM low-lim +@subsection @file{low-lim} - get lowest value index +@findex low-lim + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 594. +@end ignore + +Usage: (low-lim ag-name) +@* +Returns the lowest index associated with an array of definitions. + +Arguments: +@* +ag-name - name of AutoGen value + +@node SCM make-header-guard +@subsection @file{make-header-guard} - make self-inclusion guard +@findex make-header-guard + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 785. +@end ignore + +Usage: (make-header-guard name) +@* +This function will create a @code{#ifndef}/@code{#define} +sequence for protecting a header from multiple evaluation. +It will also set the Scheme variable @code{header-file} +to the name of the file being protected and it will set +@code{header-guard} to the name of the @code{#define} being +used to protect it. It is expected that this will be used +as follows: +@example +[+ (make-header-guard "group_name") +] +... +#endif /* [+ (. header-guard) +] */ + +#include "[+ (. header-file) +]" +@end example +@noindent +The @code{#define} name is composed as follows: + +@enumerate +@item +The first element is the string argument and a separating underscore. +@item +That is followed by the name of the header file with illegal +characters mapped to underscores. +@item +The end of the name is always, "@code{_GUARD}". +@item +Finally, the entire string is mapped to upper case. +@end enumerate + +The final @code{#define} name is stored in an SCM symbol named +@code{header-guard}. Consequently, the concluding @code{#endif} for the +file should read something like: + +@example +#endif /* [+ (. header-guard) +] */ +@end example + +The name of the header file (the current output file) is also stored +in an SCM symbol, @code{header-file}. Therefore, if you are also +generating a C file that uses the previously generated header file, +you can put this into that generated file: + +@example +#include "[+ (. header-file) +]" +@end example + +Obviously, if you are going to produce more than one header file from +a particular template, you will need to be careful how these SCM symbols +get handled. + +Arguments: +@* +name - header group name + +@node SCM make-tmp-dir +@subsection @file{make-tmp-dir} - create a temporary directory +@findex make-tmp-dir + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 544. +@end ignore + +Usage: (make-tmp-dir) +@* +Create a directory that will be cleaned up upon exit. + +This Scheme function takes no arguments. + +@node SCM match-value? +@subsection @file{match-value?} - test for matching value +@findex match-value? + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 401. +@end ignore + +Usage: (match-value? op ag-name test-str) +@* +This function answers the question, "Is there an AutoGen value named +@code{ag-name} with a value that matches the pattern @code{test-str} +using the match function @code{op}?" Return SCM_BOOL_T iff at least +one occurrence of the specified name has such a value. The operator +can be any function that takes two string arguments and yields a +boolean. It is expected that you will use one of the string matching +functions provided by AutoGen. +@* +The value name must follow the same rules as the +@code{ag-name} argument for @code{exist?} (@pxref{SCM exist?}). + +Arguments: +@* +op - boolean result operator +@* +ag-name - name of AutoGen value +@* +test-str - string to test against + +@node SCM out-delete +@subsection @file{out-delete} - delete current output file +@findex out-delete + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 199. +@end ignore + +Usage: (out-delete) +@* +Remove the current output file. Cease processing the template for +the current suffix. It is an error if there are @code{push}-ed +output files. Use the @code{(error "0")} scheme function instead. +@xref{output controls}. + +This Scheme function takes no arguments. + +@node SCM out-depth +@subsection @file{out-depth} - output file stack depth +@findex out-depth + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 719. +@end ignore + +Usage: (out-depth) +@* +Returns the depth of the output file stack. +@xref{output controls}. + +This Scheme function takes no arguments. + +@node SCM out-emit-suspended +@subsection @file{out-emit-suspended} - emit the text of suspended output +@findex out-emit-suspended + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 428. +@end ignore + +Usage: (out-emit-suspended susp_nm) +@* +This function is equivalent to +@code{(begin (out-resume <name>) (out-pop #t))} + +Arguments: +@* +susp_nm - A name tag of suspended output + +@node SCM out-line +@subsection @file{out-line} - output file line number +@findex out-line + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 749. +@end ignore + +Usage: (out-line) +@* +Returns the current line number of the output file. +It rewinds and reads the file to count newlines. + +This Scheme function takes no arguments. + +@node SCM out-move +@subsection @file{out-move} - change name of output file +@findex out-move + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 224. +@end ignore + +Usage: (out-move new-name) +@* +Rename current output file. @xref{output controls}. +Please note: changing the name will not save a temporary file from +being deleted. It @i{may}, however, be used on the root output file. + +Arguments: +@* +new-name - new name for the current output file + +@node SCM out-name +@subsection @file{out-name} - current output file name +@findex out-name + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 732. +@end ignore + +Usage: (out-name) +@* +Returns the name of the current output file. If the current file +is a temporary, unnamed file, then it will scan up the chain until +a real output file name is found. +@xref{output controls}. + +This Scheme function takes no arguments. + +@node SCM out-pop +@subsection @file{out-pop} - close current output file +@findex out-pop + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 265. +@end ignore + +Usage: (out-pop [ disp ]) +@* +If there has been a @code{push} on the output, then close that +file and go back to the previously open file. It is an error +if there has not been a @code{push}. @xref{output controls}. + +If there is no argument, no further action is taken. Otherwise, +the argument should be @code{#t} and the contents of the file +are returned by the function. + +Arguments: +@* +disp - Optional - return contents of the file + +@node SCM out-push-add +@subsection @file{out-push-add} - append output to file +@findex out-push-add + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 520. +@end ignore + +Usage: (out-push-add file-name) +@* +Identical to @code{push-new}, except the contents are @strong{not} +purged, but appended to. @xref{output controls}. + +Arguments: +@* +file-name - name of the file to append text to + +@node SCM out-push-new +@subsection @file{out-push-new} - purge and create output file +@findex out-push-new + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 573. +@end ignore + +Usage: (out-push-new [ file-name ]) +@* +Leave the current output file open, but purge and create +a new file that will remain open until a @code{pop} @code{delete} +or @code{switch} closes it. The file name is optional and, if omitted, +the output will be sent to a temporary file that will be deleted when +it is closed. +@xref{output controls}. + +Arguments: +@* +file-name - Optional - name of the file to create + +@node SCM out-resume +@subsection @file{out-resume} - resume suspended output file +@findex out-resume + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 392. +@end ignore + +Usage: (out-resume susp_nm) +@* +If there has been a suspended output, then make that output descriptor +current again. That output must have been suspended with the same tag +name given to this routine as its argument. + +Arguments: +@* +susp_nm - A name tag for reactivating + +@node SCM out-suspend +@subsection @file{out-suspend} - suspend current output file +@findex out-suspend + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 349. +@end ignore + +Usage: (out-suspend suspName) +@* +If there has been a @code{push} on the output, then set aside the output +descriptor for later reactiviation with @code{(out-resume "xxx")}. The +tag name need not reflect the name of the output file. In fact, the +output file may be an anonymous temporary file. You may also change the +tag every time you suspend output to a file, because the tag names are +forgotten as soon as the file has been "resumed". + +Arguments: +@* +suspName - A name tag for reactivating + +@node SCM out-switch +@subsection @file{out-switch} - close and create new output +@findex out-switch + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 657. +@end ignore + +Usage: (out-switch file-name) +@* +Switch output files - close current file and make the current +file pointer refer to the new file. This is equivalent to +@code{out-pop} followed by @code{out-push-new}, except that +you may not pop the base level output file, but you may +@code{switch} it. @xref{output controls}. + +Arguments: +@* +file-name - name of the file to create + +@node SCM output-file-next-line +@subsection @file{output-file-next-line} - print the file name and next line number +@findex output-file-next-line + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expOutput.c line 313. +@end ignore + +Usage: (output-file-next-line [ line_off ] [ alt_fmt ]) +@* +Returns a string with the current output file name and line number. +The default format is: # <line+1> "<output-file-name>" The argument may be +either a number indicating an offset from the current output line number +or an alternate formatting string. If both are provided, then the first +must be a numeric offset. + +Be careful that you are directing output to the final output file. +Otherwise, you will get the file name and line number of the temporary +file. That won't be what you want. + +Arguments: +@* +line_off - Optional - offset to line number +@* +alt_fmt - Optional - alternate format string + +@node SCM set-option +@subsection @file{set-option} - Set a command line option +@findex set-option + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 622. +@end ignore + +Usage: (set-option opt) +@* +The text argument must be an option name followed by any needed +option argument. Returns SCM_UNDEFINED. + +Arguments: +@* +opt - AutoGen option name + its argument + +@node SCM set-writable +@subsection @file{set-writable} - Make the output file be writable +@findex set-writable + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcIf.c line 478. +@end ignore + +Usage: (set-writable [ set? ]) +@* +This function will set the current output file to be writable +(or not). This is only effective if neither the @code{--writable} +nor @code{--not-writable} have been specified. This state +is reset when the current suffix's output is complete. + +Arguments: +@* +set? - Optional - boolean arg, false to make output non-writable + +@node SCM stack +@subsection @file{stack} - make list of AutoGen values +@findex stack + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 872. +@end ignore + +Usage: (stack ag-name) +@* +Create a scheme list of all the strings that are associated +with a name. They must all be text values or we choke. + +Arguments: +@* +ag-name - AutoGen value name + +@node SCM stack-join +@subsection @file{stack-join} - stack values then join them +@findex stack-join + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 372. +@end ignore + +Usage: (stack-join join ag-name) +@* +This function will collect all the values named @code{ag-name} +(see the @pxref{SCM stack, stack function}) and join them +separated by the @code{join} string (see the +@pxref{SCM join, join function}). + +Arguments: +@* +join - string between each element +@* +ag-name - name of autogen values to stack + +@node SCM suffix +@subsection @file{suffix} - get the current suffix +@findex suffix + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 639. +@end ignore + +Usage: (suffix) +@* +Returns the current active suffix (@pxref{pseudo macro}). + +This Scheme function takes no arguments. + +@node SCM tpl-file +@subsection @file{tpl-file} - get the template file name +@findex tpl-file + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 653. +@end ignore + +Usage: (tpl-file [ full_path ]) +@* +Returns the name of the current template file. +If @code{#t} is passed in as an argument, then the template +file is hunted for in the template search path. Otherwise, +just the unadorned name. + +Arguments: +@* +full_path - Optional - include full path to file + +@node SCM tpl-file-line +@subsection @file{tpl-file-line} - get the template file+line number +@findex tpl-file-line + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 701. +@end ignore + +Usage: (tpl-file-line [ msg-fmt ]) +@* +Returns the file and line number of the current template macro using +either the default format, "from %s line %d", or else the format you +supply. For example, if you want to insert a "C" language file-line +directive, you would supply the format "# %2$d \"%1$s\"", but that +is also already supplied with the scheme variable +@xref{SCM c-file-line-fmt}. You may use it thus: +@example +(tpl-file-line c-file-line-fmt) +@end example + +It is also safe to use the formatting string, "%2$d". AutoGen uses +an argument vector version of printf: @xref{snprintfv}, +and it does not need to know the types of each argument in order to +skip forward to the second argument. + +Arguments: +@* +msg-fmt - Optional - formatting for line message + +@node SCM tpl-file-next-line +@subsection @file{tpl-file-next-line} - get the template file plus next line number +@findex tpl-file-next-line + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 733. +@end ignore + +Usage: (tpl-file-next-line [ msg-fmt ]) +@* +This is almost the same as @xref{SCM tpl-file-line}, except that +the line referenced is the next line, per C compiler conventions, and +consequently defaults to the format: # <line-no+1> "<file-name>" + +Arguments: +@* +msg-fmt - Optional - formatting for line message + +@ignore +Generated from auto_gen.tpl line 271. +@end ignore + +@node SCM autogen-version +@subsection @file{autogen-version} - autogen version number +@findex autogen-version + +This is a symbol defining the current AutoGen version number string. +It was first defined in AutoGen-5.2.14. +It is currently ``5.16.2''. + +@node SCM c-file-line-fmt +@subsection format file info as, ``@code{#line nn "file"}'' +@findex c-file-line-fmt + +This is a symbol that can easily be used with the functions +@xref{SCM tpl-file-line}, and @xref{SCM def-file-line}. +These will emit C program @code{#line} directives pointing to template +and definitions text, respectively. +@ignore + +* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * + +@end ignore +@page +@node Common Functions +@section Common Scheme Functions + +This section describes a number of general purpose functions that make +the kind of string processing that AutoGen does a little easier. +Unlike the AutoGen specific functions (@pxref{AutoGen Functions}), +these functions are available for direct use during definition load time. +The equality test (@pxref{SCM =}) is ``overloaded'' to do string equivalence +comparisons. If you are looking for inequality, the Scheme/Lisp way +of spelling that is, ``(not (= ...))''. + +@menu +* SCM agpl:: @file{agpl} - GNU Affero General Public License +* SCM bsd:: @file{bsd} - BSD Public License +* SCM c-string:: @file{c-string} - emit string for ANSI C +* SCM error-source-line:: @file{error-source-line} - display of file & line +* SCM extract:: @file{extract} - extract text from another file +* SCM format-arg-count:: @file{format-arg-count} - count the args to a format +* SCM fprintf:: @file{fprintf} - format to a file +* SCM gperf:: @file{gperf} - perform a perfect hash function +* SCM gperf-code:: @file{gperf-code} - emit the source of the generated gperf program +* SCM gpl:: @file{gpl} - GNU General Public License +* SCM hide-email:: @file{hide-email} - convert eaddr to javascript +* SCM html-escape-encode:: @file{html-escape-encode} - encode html special characters +* SCM in?:: @file{in?} - test for string in list +* SCM join:: @file{join} - join string list with separator +* SCM kr-string:: @file{kr-string} - emit string for K&R C +* SCM lgpl:: @file{lgpl} - GNU Library General Public License +* SCM license:: @file{license} - an arbitrary license +* SCM license-description:: @file{license-description} - Emit a license description +* SCM license-full:: @file{license-full} - Emit the licensing information and description +* SCM license-info:: @file{license-info} - Emit the licensing information and copyright years +* SCM license-name:: @file{license-name} - Emit the name of the license +* SCM make-gperf:: @file{make-gperf} - build a perfect hash function program +* SCM makefile-script:: @file{makefile-script} - create makefile script +* SCM max:: @file{max} - maximum value in list +* SCM min:: @file{min} - minimum value in list +* SCM prefix:: @file{prefix} - prefix lines with a string +* SCM printf:: @file{printf} - format to stdout +* SCM raw-shell-str:: @file{raw-shell-str} - single quote shell string +* SCM shell:: @file{shell} - invoke a shell script +* SCM shell-str:: @file{shell-str} - double quote shell string +* SCM shellf:: @file{shellf} - format a string, run shell +* SCM sprintf:: @file{sprintf} - format a string +* SCM string-capitalize:: @file{string-capitalize} - capitalize a new string +* SCM string-capitalize!:: @file{string-capitalize!} - capitalize a string +* SCM *=*:: @file{string-contains-eqv?} - caseless substring +* SCM *==*:: @file{string-contains?} - substring match +* SCM string-downcase:: @file{string-downcase} - lower case a new string +* SCM string-downcase!:: @file{string-downcase!} - make a string be lower case +* SCM *~:: @file{string-end-eqv-match?} - caseless regex ending +* SCM *~~:: @file{string-end-match?} - regex match end +* SCM *=:: @file{string-ends-eqv?} - caseless string ending +* SCM *==:: @file{string-ends-with?} - string ending +* SCM ==:: @file{string-equals?} - string matching +* SCM ~:: @file{string-eqv-match?} - caseless regex match +* SCM =:: @file{string-eqv?} - caseless match +* SCM *~*:: @file{string-has-eqv-match?} - caseless regex contains +* SCM *~~*:: @file{string-has-match?} - contained regex match +* SCM ~~:: @file{string-match?} - regex match +* SCM ~*:: @file{string-start-eqv-match?} - caseless regex start +* SCM ~~*:: @file{string-start-match?} - regex match start +* SCM =*:: @file{string-starts-eqv?} - caseless string start +* SCM ==*:: @file{string-starts-with?} - string starting +* SCM string-substitute:: @file{string-substitute} - multiple global replacements +* SCM string-table-add:: @file{string-table-add} - Add an entry to a string table +* SCM string-table-add-ref:: @file{string-table-add-ref} - Add an entry to a string table, get reference +* SCM string-table-new:: @file{string-table-new} - create a string table +* SCM string-table-size:: @file{string-table-size} - print the current size of a string table +* SCM string->c-name!:: @file{string->c-name!} - map non-name chars to underscore +* SCM string->camelcase:: @file{string->camelcase} - make a string be CamelCase +* SCM string-tr:: @file{string-tr} - convert characters with new result +* SCM string-tr!:: @file{string-tr!} - convert characters +* SCM string-upcase:: @file{string-upcase} - upper case a new string +* SCM string-upcase!:: @file{string-upcase!} - make a string be upper case +* SCM sub-shell-str:: @file{sub-shell-str} - back quoted (sub-)shell string +* SCM sum:: @file{sum} - sum of values in list +* SCM time-string->number:: @file{time-string->number} - duration string to seconds +* SCM version-compare:: @file{version-compare} - compare two version numbers +@end menu + + +@node SCM agpl +@subsection @file{agpl} - GNU Affero General Public License +@findex agpl + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 649. +@end ignore + +Usage: (agpl prog-name prefix) +@* +Emit a string that contains the GNU Affero General Public License. +This function is now deprecated. Please @xref{SCM license-description}. + +Arguments: +@* +prog-name - name of the program under the GPL +@* +prefix - String for starting each output line + +@node SCM bsd +@subsection @file{bsd} - BSD Public License +@findex bsd + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 696. +@end ignore + +Usage: (bsd prog_name owner prefix) +@* +Emit a string that contains the Free BSD Public License. +This function is now deprecated. Please @xref{SCM license-description}. + +Arguments: +@* +prog_name - name of the program under the BSD +@* +owner - Grantor of the BSD License +@* +prefix - String for starting each output line + +@node SCM c-string +@subsection @file{c-string} - emit string for ANSI C +@findex c-string + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 936. +@end ignore + +Usage: (c-string string) +@* +Reform a string so that, when printed, the C compiler will be able to +compile the data and construct a string that contains exactly what the +current string contains. Many non-printing characters are replaced with +escape sequences. Newlines are replaced with a backslash, an @code{n}, a +closing quote, a newline, seven spaces and another re-opening quote. The +compiler will implicitly concatenate them. The reader will see line +breaks. + +A K&R compiler will choke. Use @code{kr-string} for that compiler. + +Arguments: +@* +string - string to reformat + +@node SCM error-source-line +@subsection @file{error-source-line} - display of file & line +@findex error-source-line + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcEval.c line 303. +@end ignore + +Usage: (error-source-line) +@* +This function is only invoked just before Guile displays +an error message. It displays the file name and line number +that triggered the evaluation error. You should not need to +invoke this routine directly. Guile will do it automatically. + +This Scheme function takes no arguments. + +@node SCM extract +@subsection @file{extract} - extract text from another file +@findex extract + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expExtract.c line 186. +@end ignore + +Usage: (extract file-name marker-fmt [ caveat ] [ default ]) +@* +This function is used to help construct output files that may contain +text that is carried from one version of the output to the next. + +The first two arguments are required, the second are optional: + +@itemize @bullet +@item +The @code{file-name} argument is used to name the file that +contains the demarcated text. +@item +The @code{marker-fmt} is a formatting string that is used to construct +the starting and ending demarcation strings. The sprintf function is +given the @code{marker-fmt} with two arguments. The first is either +"START" or "END". The second is either "DO NOT CHANGE THIS COMMENT" +or the optional @code{caveat} argument. +@item +@code{caveat} is presumed to be absent if it is the empty string +(@code{""}). If absent, ``DO NOT CHANGE THIS COMMENT'' is used +as the second string argument to the @code{marker-fmt}. +@item +When a @code{default} argument is supplied and no pre-existing text +is found, then this text will be inserted between the START and END +markers. +@end itemize + +@noindent +The resulting strings are presumed to be unique within +the subject file. As a simplified example: + +@example +[+ (extract "fname" "// %s - SOMETHING - %s" "" +"example default") +] +@end example +@noindent +will result in the following text being inserted into the output: + +@example +// START - SOMETHING - DO NOT CHANGE THIS COMMENT +example default +// END - SOMETHING - DO NOT CHANGE THIS COMMENT +@end example + +@noindent +The ``@code{example default}'' string can then be carried forward to +the next generation of the output, @strong{@i{provided}} the output +is not named "@code{fname}" @i{and} the old output is renamed to +"@code{fname}" before AutoGen-eration begins. + +@table @strong +@item NB: +You can set aside previously generated source files inside the pseudo +macro with a Guile/scheme function, extract the text you want to keep +with this extract function. Just remember you should delete it at the +end, too. Here is an example from my Finite State Machine generator: + +@example +[+ AutoGen5 Template -*- Mode: text -*- +h=%s-fsm.h c=%s-fsm.c +(shellf +"test -f %1$s-fsm.h && mv -f %1$s-fsm.h .fsm.head +test -f %1$s-fsm.c && mv -f %1$s-fsm.c .fsm.code" (base-name)) ++] +@end example + +This code will move the two previously produced output files to files +named ".fsm.head" and ".fsm.code". At the end of the 'c' output +processing, I delete them. + +@item also NB: +This function presumes that the output file ought to be editable so +that the code between the @code{START} and @code{END} marks can be edited +by the template user. Consequently, when the @code{(extract ...)} function +is invoked, if the @code{writable} option has not been specified, then +it will be set at that point. If this is not the desired behavior, the +@code{--not-writable} command line option will override this. +Also, you may use the guile function @code{(chmod "file" mode-value)} +to override whatever AutoGen is using for the result mode. +@end table + +Arguments: +@* +file-name - name of file with text +@* +marker-fmt - format for marker text +@* +caveat - Optional - warn about changing marker +@* +default - Optional - default initial text + +@node SCM format-arg-count +@subsection @file{format-arg-count} - count the args to a format +@findex format-arg-count + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expPrint.c line 294. +@end ignore + +Usage: (format-arg-count format) +@* +Sometimes, it is useful to simply be able to figure out how many +arguments are required by a format string. For example, if you +are extracting a format string for the purpose of generating a +macro to invoke a printf-like function, you can run the +formatting string through this function to determine how many +arguments to provide for in the macro. e.g. for this extraction +text: +@example + + /*=fumble bumble + * fmt: 'stumble %s: %d\n' + =*/ +@end example + +@noindent +You may wish to generate a macro: +@example + + #define BUMBLE(a1,a2) printf_like(something,(a1),(a2)) +@end example + +@noindent +You can do this by knowing that the format needs two arguments. + +Arguments: +@* +format - formatting string + +@node SCM fprintf +@subsection @file{fprintf} - format to a file +@findex fprintf + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expPrint.c line 230. +@end ignore + +Usage: (fprintf port format [ format-arg ... ]) +@* +Format a string using arguments from the alist. +Write to a specified port. The result will NOT appear in your +output. Use this to print information messages to a template user. + +Arguments: +@* +port - Guile-scheme output port +@* +format - formatting string +@* +format-arg - Optional - list of arguments to formatting string + +@node SCM gperf +@subsection @file{gperf} - perform a perfect hash function +@findex gperf + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGperf.c line 109. +@end ignore + +Usage: (gperf name str) +@* +Perform the perfect hash on the input string. This is only useful if +you have previously created a gperf program with the @code{make-gperf} +function @xref{SCM make-gperf}. The @code{name} you supply here must +match the name used to create the program and the string to hash must +be one of the strings supplied in the @code{make-gperf} string list. +The result will be a perfect hash index. + +See the documentation for @command{gperf(1GNU)} for more details. + +Arguments: +@* +name - name of hash list +@* +str - string to hash + +@node SCM gperf-code +@subsection @file{gperf-code} - emit the source of the generated gperf program +@findex gperf-code + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 324. +@end ignore + +Usage: (gperf-code st-name) +@* +Returns the contents of the emitted code, suitable +for inclusion in another program. The interface contains +the following elements: + +@table @samp +@item struct @i{<st-name>}_index +containg the fields: @code{@{char const * name, int const id; @};} + +@item @i{<st-name>}_hash() +This is the hashing function with local only scope (static). + +@item @i{<st-name>}_find() +This is the searching and validation function. The first argument +is the string to look up, the second is its length. +It returns a pointer to the corresponding @code{@i{<st-name>}_index} +entry. +@end table + +Use this in your template as follows where "@i{<st-name>}" was +set to be "@code{lookup}": + +@example +[+ (make-gperf "lookup" (join "\n" (stack "name_list"))) +(gperf-code "lookup") +] +void my_fun(char * str) @{ +struct lookup_index * li = lookup_find(str, strlen(str)); +if (li != NULL) printf("%s yields %d\n", str, li->idx); +@end example + +Arguments: +@* +st-name - the name of the gperf hash list + +@node SCM gpl +@subsection @file{gpl} - GNU General Public License +@findex gpl + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 626. +@end ignore + +Usage: (gpl prog-name prefix) +@* +Emit a string that contains the GNU General Public License. +This function is now deprecated. Please @xref{SCM license-description}. + +Arguments: +@* +prog-name - name of the program under the GPL +@* +prefix - String for starting each output line + +@node SCM hide-email +@subsection @file{hide-email} - convert eaddr to javascript +@findex hide-email + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expPrint.c line 254. +@end ignore + +Usage: (hide-email display eaddr) +@* +Hides an email address as a java scriptlett. +The 'mailto:' tag and the email address are coded bytes +rather than plain text. They are also broken up. + +Arguments: +@* +display - display text +@* +eaddr - email address + +@node SCM html-escape-encode +@subsection @file{html-escape-encode} - encode html special characters +@findex html-escape-encode + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 108. +@end ignore + +Usage: (html-escape-encode str) +@* +This function will replace replace the characters @code{'&'}, +@code{'<'} and @code{'>'} characters with the HTML/XML +escape-encoded strings (@code{"&"}, @code{"<"}, and +@code{">"}, respectively). + +Arguments: +@* +str - string to make substitutions in + +@node SCM in? +@subsection @file{in?} - test for string in list +@findex in? + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 439. +@end ignore + +Usage: (in? test-string string-list ...) +@* +Return SCM_BOOL_T if the first argument string is found +in one of the entries in the second (list-of-strings) argument. + +Arguments: +@* +test-string - string to look for +@* +string-list - list of strings to check + +@node SCM join +@subsection @file{join} - join string list with separator +@findex join + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 506. +@end ignore + +Usage: (join separator list ...) +@* +With the first argument as the separator string, +joins together an a-list of strings into one long string. +The list may contain nested lists, partly because you +cannot always control that. + +Arguments: +@* +separator - string to insert between entries +@* +list - list of strings to join + +@node SCM kr-string +@subsection @file{kr-string} - emit string for K&R C +@findex kr-string + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 914. +@end ignore + +Usage: (kr-string string) +@* +Reform a string so that, when printed, a K&R C compiler will be able +to compile the data and construct a string that contains exactly +what the current string contains. Many non-printing characters are +replaced with escape sequences. New-lines are replaced with a +backslash-n-backslash and newline sequence, + +Arguments: +@* +string - string to reformat + +@node SCM lgpl +@subsection @file{lgpl} - GNU Library General Public License +@findex lgpl + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 672. +@end ignore + +Usage: (lgpl prog_name owner prefix) +@* +Emit a string that contains the GNU Library General Public License. +This function is now deprecated. Please @xref{SCM license-description}. + +Arguments: +@* +prog_name - name of the program under the LGPL +@* +owner - Grantor of the LGPL +@* +prefix - String for starting each output line + +@node SCM license +@subsection @file{license} - an arbitrary license +@findex license + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 721. +@end ignore + +Usage: (license lic_name prog_name owner prefix) +@* +Emit a string that contains the named license. +This function is now deprecated. Please @xref{SCM license-description}. + +Arguments: +@* +lic_name - file name of the license +@* +prog_name - name of the licensed program or library +@* +owner - Grantor of the License +@* +prefix - String for starting each output line + +@node SCM license-description +@subsection @file{license-description} - Emit a license description +@findex license-description + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 550. +@end ignore + +Usage: (license-description license prog-name prefix [ owner ]) +@* +Emit a string that contains a detailed license description, with +substitutions for program name, copyright holder and a per-line prefix. +This is the text typically used as part of a source file header. +For more details, @xref{SCM license-full, the license-full command}. + +Arguments: +@* +license - name of license type +@* +prog-name - name of the program under the GPL +@* +prefix - String for starting each output line +@* +owner - Optional - owner of the program + +@node SCM license-full +@subsection @file{license-full} - Emit the licensing information and description +@findex license-full + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 493. +@end ignore + +Usage: (license-full license prog-name prefix [ owner ] [ years ]) +@* +Emit all the text that @code{license-info} and @code{license-description} +would emit (@pxref{SCM license-info, @code{license-info}}, +and @pxref{SCM license-description, @code{license-description}}), +with all the same substitutions. + +All of these depend upon the existence of a license file named after the +@code{license} argument with a @code{.lic} suffix. That file should +contain three blocks of text, each separated by two or more newline +characters. + +The first section describes copyright attribution and the name of the usage +licence. For GNU software, this should be the text that is to be displayed +with the program version. Four text markers can be replaced: <PFX>, +<program>, <years> and <owner>. + +The second section is a short description of the terms of the license. +This is typically the kind of text that gets displayed in the header of +source files. The third section is strictly the name of the license +without any substitution markers. Only the <PFX>, <owner> and <program> +markers are substituted. + +The third section is strictly the name of the license. +No marker substitutions are performed. + +@example +<PFX>Copyright (C) <years> <owner>, all rights reserved. +<PFX>This is free software. It is licensed for use, +<PFX>modification and redistribution under the terms +<PFX>of the GNU General Public License, version 3 or later +<PFX> <http://gnu.org/licenses/gpl.html> + +<PFX><program> is free software: you can redistribute it +<PFX>and/or modify it under the terms of the GNU General +<PFX>Public License as published by the Free Software ... + +the GNU General Public License, version 3 or later +@end example + +Arguments: +@* +license - name of license type +@* +prog-name - name of the program under the GPL +@* +prefix - String for starting each output line +@* +owner - Optional - owner of the program +@* +years - Optional - copyright years + +@node SCM license-info +@subsection @file{license-info} - Emit the licensing information and copyright years +@findex license-info + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 574. +@end ignore + +Usage: (license-info license prog-name prefix [ owner ] [ years ]) +@* +Emit a string that contains the licensing description, with some +substitutions for program name, copyright holder, a list of years when the +source was modified, and a per-line prefix. This text typically includes a +brief license description and is often printed out when a program starts +running or as part of the @code{--version} output. +For more details, @xref{SCM license-full, the license-full command}. + +Arguments: +@* +license - name of license type +@* +prog-name - name of the program under the GPL +@* +prefix - String for starting each output line +@* +owner - Optional - owner of the program +@* +years - Optional - copyright years + +@node SCM license-name +@subsection @file{license-name} - Emit the name of the license +@findex license-name + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expFormat.c line 601. +@end ignore + +Usage: (license-name license) +@* +Emit a string that contains the full name of the license. + +Arguments: +@* +license - name of license type + +@node SCM make-gperf +@subsection @file{make-gperf} - build a perfect hash function program +@findex make-gperf + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGperf.c line 39. +@end ignore + +Usage: (make-gperf name strings ...) +@* +Build a program to perform perfect hashes of a known list of input +strings. This function produces no output, but prepares a program +named, @file{gperf_<name>} for use by the gperf function +@xref{SCM gperf}. + +This program will be obliterated as AutoGen exits. +However, you may incorporate the generated hashing function +into your C program with commands something like the following: + +@example +[+ (shellf "sed '/^int main(/,$d;/^#line/d' $@{gpdir@}/%s.c" +name ) +] +@end example + +where @code{name} matches the name provided to this @code{make-perf} +function. @code{gpdir} is the variable used to store the name of the +temporary directory used to stash all the files. + +Arguments: +@* +name - name of hash list +@* +strings - list of strings to hash + +@node SCM makefile-script +@subsection @file{makefile-script} - create makefile script +@findex makefile-script + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expMake.c line 253. +@end ignore + +Usage: (makefile-script text) +@* +This function will take ordinary shell script text and reformat it +so that it will work properly inside of a makefile shell script. +Not every shell construct can be supported; the intent is to have +most ordinary scripts work without much, if any, alteration. + +The following transformations are performed on the source text: + +@enumerate +@item +Trailing whitespace on each line is stripped. + +@item +Except for the last line, the string, " ; \\" is appended to the end of +every line that does not end with certain special characters or keywords. +Note that this will mutilate multi-line quoted strings, but @command{make} +renders it impossible to use multi-line constructs anyway. + +@item +If the line ends with a backslash, it is left alone. + +@item +If the line ends with a semi-colon, conjunction operator, pipe (vertical +bar) or one of the keywords "then", "else" or "in", then a space and a +backslash is added, but no semi-colon. + +@item +The dollar sign character is doubled, unless it immediately precedes an +opening parenthesis or the single character make macros '*', '<', '@@', +'?' or '%'. Other single character make macros that do not have enclosing +parentheses will fail. For shell usage of the "$@@", "$?" and "$*" +macros, you must enclose them with curly braces, e.g., "$@{?@}". +The ksh construct @code{$(<command>)} will not work. Though some +@command{make}s accept @code{$@{var@}} constructs, this function will +assume it is for shell interpretation and double the dollar character. +You must use @code{$(var)} for all @command{make} substitutions. + +@item +Double dollar signs are replaced by four before the next character +is examined. + +@item +Every line is prefixed with a tab, unless the first line +already starts with a tab. + +@item +The newline character on the last line, if present, is suppressed. + +@item +Blank lines are stripped. + +@item +Lines starting with "@@ifdef", "@@ifndef", "@@else" and "@@endif" are +presumed to be autoconf "sed" expression tags. These lines will be +emitted as-is, with no tab prefix and no line splicing backslash. +These lines can then be processed at configure time with +@code{AC_CONFIG_FILES} sed expressions, similar to: + +@example +sed "/^@@ifdef foo/d;/^@@endif foo/d;/^@@ifndef foo/,/^@@endif foo/d" +@end example +@end enumerate + +@noindent +This function is intended to be used approximately as follows: + +@example +$(TARGET) : $(DEPENDENCIES) +<+ (out-push-new) +> +....mostly arbitrary shell script text.... +<+ (makefile-script (out-pop #t)) +> +@end example + +Arguments: +@* +text - the text of the script + +@node SCM max +@subsection @file{max} - maximum value in list +@findex max + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 88. +@end ignore + +Usage: (max list ...) +@* +Return the maximum value in the list + +Arguments: +@* +list - list of values. Strings are converted to numbers + +@node SCM min +@subsection @file{min} - minimum value in list +@findex min + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 147. +@end ignore + +Usage: (min list ...) +@* +Return the minimum value in the list + +Arguments: +@* +list - list of values. Strings are converted to numbers + +@node SCM prefix +@subsection @file{prefix} - prefix lines with a string +@findex prefix + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 604. +@end ignore + +Usage: (prefix prefix text) +@* +Prefix every line in the second string with the first string. + +For example, if the first string is "# " and the second contains: +@example +two +lines +@end example +@noindent +The result string will contain: +@example +# two +# lines +@end example + +Arguments: +@* +prefix - string to insert at start of each line +@* +text - multi-line block of text + +@node SCM printf +@subsection @file{printf} - format to stdout +@findex printf + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expPrint.c line 206. +@end ignore + +Usage: (printf format [ format-arg ... ]) +@* +Format a string using arguments from the alist. +Write to the standard out port. The result will NOT appear in your +output. Use this to print information messages to a template user. +Use ``(sprintf ...)'' to add text to your document. + +Arguments: +@* +format - formatting string +@* +format-arg - Optional - list of arguments to formatting string + +@node SCM raw-shell-str +@subsection @file{raw-shell-str} - single quote shell string +@findex raw-shell-str + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 686. +@end ignore + +Usage: (raw-shell-str string) +@* +Convert the text of the string into a singly quoted string +that a normal shell will process into the original string. +(It will not do macro expansion later, either.) +Contained single quotes become tripled, with the middle quote +escaped with a backslash. Normal shells will reconstitute the +original string. + +@strong{Notice}: some shells will not correctly handle unusual +non-printing characters. This routine works for most reasonably +conventional ASCII strings. + +Arguments: +@* +string - string to transform + +@node SCM shell +@subsection @file{shell} - invoke a shell script +@findex shell + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/agShell.c line 57. +@end ignore + +Usage: (shell command) +@* +Generate a string by writing the value to a server shell and reading the +output back in. The template programmer is responsible for ensuring that +it completes within 10 seconds. If it does not, the server will be +killed, the output tossed and a new server started. + +Please note: This is the same server process used by the '#shell' +definitions directive and backquoted @code{`} definitions. There may be +left over state from previous shell expressions and the @code{`} +processing in the declarations. However, a @code{cd} to the original +directory is always issued before the new command is issued. + +Also note: When initializing, autogen will set the environment +variable "AGexe" to the full path of the autogen executable. + +Arguments: +@* +command - shell command - the result value is the stdout output. + +@node SCM shell-str +@subsection @file{shell-str} - double quote shell string +@findex shell-str + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 783. +@end ignore + +Usage: (shell-str string) +@* +Convert the text of the string into a double quoted string that a normal +shell will process into the original string, almost. It will add the +escape character @code{\\} before two special characters to +accomplish this: the backslash @code{\\} and double quote @code{"}. + +@strong{Notice}: some shells will not correctly handle unusual +non-printing characters. This routine works for most reasonably +conventional ASCII strings. + +@strong{WARNING}: +@* +This function omits the extra backslash in front of a backslash, however, +if it is followed by either a backquote or a dollar sign. It must do this +because otherwise it would be impossible to protect the dollar sign or +backquote from shell evaluation. Consequently, it is not possible to +render the strings "\\$" or "\\`". The lesser of two evils. + +All others characters are copied directly into the output. + +The @code{sub-shell-str} variation of this routine behaves identically, +except that the extra backslash is omitted in front of @code{"} instead +of @code{`}. You have to think about it. I'm open to suggestions. + +Meanwhile, the best way to document is with a detailed output example. +If the backslashes make it through the text processing correctly, +below you will see what happens with three example strings. The first +example string contains a list of quoted @code{foo}s, the second is +the same with a single backslash before the quote characters and the +last is with two backslash escapes. Below each is the result of the +@code{raw-shell-str}, @code{shell-str} and @code{sub-shell-str} functions. + +@example +foo[0] ''foo'' 'foo' "foo" `foo` $foo +raw-shell-str -> \'\''foo'\'\'' '\''foo'\'' "foo" `foo` $foo' +shell-str -> "''foo'' 'foo' \"foo\" `foo` $foo" +sub-shell-str -> `''foo'' 'foo' "foo" \`foo\` $foo` + +foo[1] \'bar\' \"bar\" \`bar\` \$bar +raw-shell-str -> '\'\''bar\'\'' \"bar\" \`bar\` \$bar' +shell-str -> "\\'bar\\' \\\"bar\\\" \`bar\` \$bar" +sub-shell-str -> `\\'bar\\' \"bar\" \\\`bar\\\` \$bar` + +foo[2] \\'BAZ\\' \\"BAZ\\" \\`BAZ\\` \\$BAZ +raw-shell-str -> '\\'\''BAZ\\'\'' \\"BAZ\\" \\`BAZ\\` \\$BAZ' +shell-str -> "\\\\'BAZ\\\\' \\\\\"BAZ\\\\\" \\\`BAZ\\\` \\\$BAZ" +sub-shell-str -> `\\\\'BAZ\\\\' \\\"BAZ\\\" \\\\\`BAZ\\\\\` \\\$BAZ` +@end example + +There should be four, three, five and three backslashes for the four +examples on the last line, respectively. The next to last line should +have four, five, three and three backslashes. If this was not accurately +reproduced, take a look at the agen5/test/shell.test test. Notice the +backslashes in front of the dollar signs. It goes from zero to one to +three for the "cooked" string examples. + +Arguments: +@* +string - string to transform + +@node SCM shellf +@subsection @file{shellf} - format a string, run shell +@findex shellf + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/agShell.c line 96. +@end ignore + +Usage: (shellf format [ format-arg ... ]) +@* +Format a string using arguments from the alist, +then send the result to the shell for interpretation. + +Arguments: +@* +format - formatting string +@* +format-arg - Optional - list of arguments to formatting string + +@node SCM sprintf +@subsection @file{sprintf} - format a string +@findex sprintf + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expPrint.c line 183. +@end ignore + +Usage: (sprintf format [ format-arg ... ]) +@* +Format a string using arguments from the alist. + +Arguments: +@* +format - formatting string +@* +format-arg - Optional - list of arguments to formatting string + +@node SCM string-capitalize +@subsection @file{string-capitalize} - capitalize a new string +@findex string-capitalize + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 385. +@end ignore + +Usage: (string-capitalize str) +@* +Create a new SCM string containing the same text as the original, +only all the first letter of each word is upper cased and all +other letters are made lower case. + +Arguments: +@* +str - input string + +@node SCM string-capitalize! +@subsection @file{string-capitalize!} - capitalize a string +@findex string-capitalize! + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 342. +@end ignore + +Usage: (string-capitalize! str) +@* +capitalize all the words in an SCM string. + +Arguments: +@* +str - input/output string + +@node SCM *=* +@subsection @file{string-contains-eqv?} - caseless substring +@findex string-contains-eqv? +@findex *=* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 291. +@end ignore + +Usage: (*=* text match) +@* +string-contains-eqv?: Test to see if a string contains an equivalent string. +`equivalent' means the strings match, but without regard +to character case and certain characters are considered `equivalent'. +Viz., '-', '_' and '^' are equivalent. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM *==* +@subsection @file{string-contains?} - substring match +@findex string-contains? +@findex *==* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 158. +@end ignore + +Usage: (*==* text match) +@* +string-contains?: Test to see if a string contains a substring. "strstr(3)" +will find an address. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM string-downcase +@subsection @file{string-downcase} - lower case a new string +@findex string-downcase + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 440. +@end ignore + +Usage: (string-downcase str) +@* +Create a new SCM string containing the same text as the original, +only all the upper case letters are changed to lower case. + +Arguments: +@* +str - input string + +@node SCM string-downcase! +@subsection @file{string-downcase!} - make a string be lower case +@findex string-downcase! + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 409. +@end ignore + +Usage: (string-downcase! str) +@* +Change to lower case all the characters in an SCM string. + +Arguments: +@* +str - input/output string + +@node SCM *~ +@subsection @file{string-end-eqv-match?} - caseless regex ending +@findex string-end-eqv-match? +@findex *~ + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 563. +@end ignore + +Usage: (*~ text match) +@* +string-end-eqv-match?: Test to see if a string ends with a pattern. +Case is not significant. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM *~~ +@subsection @file{string-end-match?} - regex match end +@findex string-end-match? +@findex *~~ + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 550. +@end ignore + +Usage: (*~~ text match) +@* +string-end-match?: Test to see if a string ends with a pattern. +Case is significant. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM *= +@subsection @file{string-ends-eqv?} - caseless string ending +@findex string-ends-eqv? +@findex *= + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 339. +@end ignore + +Usage: (*= text match) +@* +string-ends-eqv?: Test to see if a string ends with an equivalent string. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM *== +@subsection @file{string-ends-with?} - string ending +@findex string-ends-with? +@findex *== + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 187. +@end ignore + +Usage: (*== text match) +@* +string-ends-with?: Test to see if a string ends with a substring. +strcmp(3) returns zero for comparing the string ends. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM == +@subsection @file{string-equals?} - string matching +@findex string-equals? +@findex == + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 262. +@end ignore + +Usage: (== text match) +@* +string-equals?: Test to see if two strings exactly match. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM ~ +@subsection @file{string-eqv-match?} - caseless regex match +@findex string-eqv-match? +@findex ~ + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 751. +@end ignore + +Usage: (~ text match) +@* +string-eqv-match?: Test to see if a string fully matches a pattern. +Case is not significant, but any character equivalences +must be expressed in your regular expression. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM = +@subsection @file{string-eqv?} - caseless match +@findex string-eqv? +@findex = + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 409. +@end ignore + +Usage: (= text match) +@* +string-eqv?: Test to see if two strings are equivalent. `equivalent' means the +strings match, but without regard to character case and certain +characters are considered `equivalent'. Viz., '-', '_' and '^' are +equivalent. If the arguments are not strings, then the result of the +numeric comparison is returned. + +This is an overloaded operation. If the arguments are both +numbers, then the query is passed through to @code{scm_num_eq_p()}, +otherwise the result depends on the SCMs being strictly equal. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM *~* +@subsection @file{string-has-eqv-match?} - caseless regex contains +@findex string-has-eqv-match? +@findex *~* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 481. +@end ignore + +Usage: (*~* text match) +@* +string-has-eqv-match?: Test to see if a string contains a pattern. +Case is not significant. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM *~~* +@subsection @file{string-has-match?} - contained regex match +@findex string-has-match? +@findex *~~* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 468. +@end ignore + +Usage: (*~~* text match) +@* +string-has-match?: Test to see if a string contains a pattern. +Case is significant. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM ~~ +@subsection @file{string-match?} - regex match +@findex string-match? +@findex ~~ + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 738. +@end ignore + +Usage: (~~ text match) +@* +string-match?: Test to see if a string fully matches a pattern. +Case is significant. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM ~* +@subsection @file{string-start-eqv-match?} - caseless regex start +@findex string-start-eqv-match? +@findex ~* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 657. +@end ignore + +Usage: (~* text match) +@* +string-start-eqv-match?: Test to see if a string starts with a pattern. +Case is not significant. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM ~~* +@subsection @file{string-start-match?} - regex match start +@findex string-start-match? +@findex ~~* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 644. +@end ignore + +Usage: (~~* text match) +@* +string-start-match?: Test to see if a string starts with a pattern. +Case is significant. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM =* +@subsection @file{string-starts-eqv?} - caseless string start +@findex string-starts-eqv? +@findex =* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 376. +@end ignore + +Usage: (=* text match) +@* +string-starts-eqv?: Test to see if a string starts with an equivalent string. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM ==* +@subsection @file{string-starts-with?} - string starting +@findex string-starts-with? +@findex ==* + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 226. +@end ignore + +Usage: (==* text match) +@* +string-starts-with?: Test to see if a string starts with a substring. + +Arguments: +@* +text - text to test for pattern +@* +match - pattern/substring to search for + +@node SCM string-substitute +@subsection @file{string-substitute} - multiple global replacements +@findex string-substitute + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 1054. +@end ignore + +Usage: (string-substitute source match repl) +@* +@code{match} and @code{repl} may be either a single string or +a list of strings. Either way, they must have the same structure +and number of elements. For example, to replace all amphersands, +less than and greater than characters, do something like this: + +@example +(string-substitute source +(list "&" "<" ">") +(list "&" "<" ">")) +@end example + +Arguments: +@* +source - string to transform +@* +match - substring or substring list to be replaced +@* +repl - replacement strings or substrings + +@node SCM string-table-add +@subsection @file{string-table-add} - Add an entry to a string table +@findex string-table-add + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 224. +@end ignore + +Usage: (string-table-add st-name str-val) +@* +Check for a duplicate string and, if none, then insert a new +string into the string table. In all cases, returns the +character index of the beginning of the string in the table. + +The returned index can be used in expressions like: +@example +string_array + <returned-value> +@end example +@noindent +that will yield the address of the first byte of the inserted +string. See the @file{strtable.test} AutoGen test for a usage +example. + +Arguments: +@* +st-name - the name of the array of characters +@* +str-val - the (possibly) new value to add + +@node SCM string-table-add-ref +@subsection @file{string-table-add-ref} - Add an entry to a string table, get reference +@findex string-table-add-ref + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 262. +@end ignore + +Usage: (string-table-add-ref st-name str-val) +@* +Identical to string-table-add, except the value returned +is the string "st-name" '+' and the index returned by +string-table-add. + +Arguments: +@* +st-name - the name of the array of characters +@* +str-val - the (possibly) new value to add + +@node SCM string-table-new +@subsection @file{string-table-new} - create a string table +@findex string-table-new + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 131. +@end ignore + +Usage: (string-table-new st-name) +@* +This function will create an array of characters. The companion +functions, (@xref{SCM string-table-add}, +@xref{SCM string-table-add-ref}, and +@pxref{SCM emit-string-table}) will insert text and emit the +populated table. + +With these functions, it should be much easier to construct +structures containing string offsets instead of string pointers. +That can be very useful when transmitting, storing or sharing data +with different address spaces. + +@noindent +Here is a brief example copied from the strtable.test test: + +@example +[+ (string-table-new "scribble") + (out-push-new) ;; redirect output to temporary + (define ct 1) +][+ + +FOR str IN that was the week that was +][+ + (set! ct (+ ct 1)) ++] + [+ (string-table-add-ref "scribble" (get "str")) +],[+ +ENDFOR +] +[+ (out-suspend "main") + (emit-string-table "scribble") + (ag-fprintf 0 "\nchar const *ap[%d] = @{" ct) + (out-resume "main") + (out-pop #t) ;; now dump out the redirected output +] + NULL @}; +@end example + +@noindent +Some explanation: + +@noindent +I added the @code{(out-push-new)} because the string table text is +diverted into an output stream named, ``scribble'' and I want to +have the string table emitted before the string table references. +The string table references are also emitted inside the @code{FOR} +loop. So, when the loop is done, the current output is suspended +under the name, ``main'' and the ``scribble'' table is then emitted +into the primary output. (@code{emit-string-table} inserts its +output directly into the current output stream. It does not need to +be the last function in an AutoGen macro block.) Next I +@code{ag-fprintf} the array-of-pointer declaration directly into the +current output. Finally I restore the ``main'' output stream and +@code{(out-pop #t)}-it into the main output stream. + +Here is the result. Note that duplicate strings are not repeated +in the string table: + +@example +static char const scribble[18] = + "that\0" "was\0" "the\0" "week\0"; + +char const *ap[7] = @{ + scribble+0, + scribble+5, + scribble+9, + scribble+13, + scribble+0, + scribble+5, + NULL @}; +@end example + +These functions use the global name space @code{stt-*} in addition to +the function names. + +If you utilize this in your programming, it is recommended that you +prevent printf format usage warnings with the GCC option +@code{-Wno-format-contains-nul} + +Arguments: +@* +st-name - the name of the array of characters + +@node SCM string-table-size +@subsection @file{string-table-size} - print the current size of a string table +@findex string-table-size + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/schemedef.scm line 311. +@end ignore + +Usage: (string-table-size st-name) +@* +Returns the current byte count of the string table. + +Arguments: +@* +st-name - the name of the array of characters + +@node SCM string->c-name! +@subsection @file{string->c-name!} - map non-name chars to underscore +@findex string->c-name! + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 248. +@end ignore + +Usage: (string->c-name! str) +@* +Change all the graphic characters that are invalid in a C name token +into underscores. Whitespace characters are ignored. Any other +character type (i.e. non-graphic and non-white) will cause a failure. + +Arguments: +@* +str - input/output string + +@node SCM string->camelcase +@subsection @file{string->camelcase} - make a string be CamelCase +@findex string->camelcase + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 463. +@end ignore + +Usage: (string->camelcase str) +@* +Capitalize the first letter of each block of letters and numbers, +and stripping out characters that are not alphanumerics. +For example, "alpha-beta0gamma" becomes "AlphaBeta0gamma". + +Arguments: +@* +str - input/output string + +@node SCM string-tr +@subsection @file{string-tr} - convert characters with new result +@findex string-tr + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 1034. +@end ignore + +Usage: (string-tr source match translation) +@* +This is identical to @code{string-tr!}, except that it does not +over-write the previous value. + +Arguments: +@* +source - string to transform +@* +match - characters to be converted +@* +translation - conversion list + +@node SCM string-tr! +@subsection @file{string-tr!} - convert characters +@findex string-tr! + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 963. +@end ignore + +Usage: (string-tr! source match translation) +@* +This is the same as the @code{tr(1)} program, except the +string to transform is the first argument. The second and +third arguments are used to construct mapping arrays for the +transformation of the first argument. + +It is too bad this little program has so many different +and incompatible implementations! + +Arguments: +@* +source - string to transform +@* +match - characters to be converted +@* +translation - conversion list + +@node SCM string-upcase +@subsection @file{string-upcase} - upper case a new string +@findex string-upcase + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 319. +@end ignore + +Usage: (string-upcase str) +@* +Create a new SCM string containing the same text as the original, +only all the lower case letters are changed to upper case. + +Arguments: +@* +str - input string + +@node SCM string-upcase! +@subsection @file{string-upcase!} - make a string be upper case +@findex string-upcase! + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 288. +@end ignore + +Usage: (string-upcase! str) +@* +Change to upper case all the characters in an SCM string. + +Arguments: +@* +str - input/output string + +@node SCM sub-shell-str +@subsection @file{sub-shell-str} - back quoted (sub-)shell string +@findex sub-shell-str + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 853. +@end ignore + +Usage: (sub-shell-str string) +@* +This function is substantially identical to @code{shell-str}, except +that the quoting character is @code{`} and the "leave the escape alone" +character is @code{"}. + +Arguments: +@* +string - string to transform + +@node SCM sum +@subsection @file{sum} - sum of values in list +@findex sum + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expGuile.c line 206. +@end ignore + +Usage: (sum list ...) +@* +Compute the sum of the list of expressions. + +Arguments: +@* +list - list of values. Strings are converted to numbers + +@node SCM time-string->number +@subsection @file{time-string->number} - duration string to seconds +@findex time-string->number + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expString.c line 1096. +@end ignore + +Usage: (time-string->number time_spec) +@* +Convert the argument string to a time period in seconds. +The string may use multiple parts consisting of days, hours +minutes and seconds. These are indicated with a suffix of +@code{d}, @code{h}, @code{m} and @code{s} respectively. +Hours, minutes and seconds may also be represented with +@code{HH:MM:SS} or, without hours, as @code{MM:SS}. + +Arguments: +@* +time_spec - string to parse + +@node SCM version-compare +@subsection @file{version-compare} - compare two version numbers +@findex version-compare + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/expState.c line 226. +@end ignore + +Usage: (version-compare op v1 v2) +@* +Converts v1 and v2 strings into 64 bit values and returns the +result of running 'op' on those values. It assumes that the version +is a 1 to 4 part dot-separated series of numbers. Suffixes like, +"5pre4" or "5-pre4" will be interpreted as two numbers. The first +number ("5" in this case) will be decremented and the number after +the "pre" will be added to 0xC000. (Unless your platform is unable +to support 64 bit integer arithmetic. Then it will be added to 0xC0.) +Consequently, these yield true: +@example +(version-compare > "5.8.5" "5.8.5-pre4") +(version-compare > "5.8.5-pre10" "5.8.5-pre4") +@end example + +Arguments: +@* +op - comparison operator +@* +v1 - first version +@* +v2 - compared-to version +@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 +@menu +* AGMacro syntax:: AutoGen Macro Syntax +* BREAK:: BREAK - Leave a FOR or WHILE macro +* CASE:: CASE - Select one of several template blocks +* COMMENT:: COMMENT - A block of comment to be ignored +* CONTINUE:: CONTINUE - Skip to end of a FOR or WHILE macro. +* DEBUG:: DEBUG - Print debug message to trace output +* DEFINE:: DEFINE - Define a user AutoGen macro +* ELIF:: ELIF - Alternate Conditional Template Block +* ELSE:: ELSE - Alternate Template Block +* ENDDEF:: ENDDEF - Ends a macro definition. +* ENDFOR:: ENDFOR - Terminates the @code{FOR} function template block +* ENDIF:: ENDIF - Terminate the @code{IF} Template Block +* ENDWHILE:: ENDWHILE - Terminate the @code{WHILE} Template Block +* ESAC:: ESAC - Terminate the @code{CASE} Template Block +* EXPR:: EXPR - Evaluate and emit an Expression +* FOR:: FOR - Emit a template block multiple times +* IF:: IF - Conditionally Emit a Template Block +* INCLUDE:: INCLUDE - Read in and emit a template block +* INVOKE:: INVOKE - Invoke a User Defined Macro +* RETURN:: RETURN - Leave an INVOKE-d (DEFINE) macro +* SELECT:: SELECT - Selection block for CASE function +* UNKNOWN:: UNKNOWN - Either a user macro or a value name. +* WHILE:: WHILE - Conditionally loop over a Template Block +@end menu +@node AGMacro syntax +@subsection AutoGen Macro Syntax +@cindex macro syntax + +The general syntax is: + +@example +[ @{ <native-macro-name> | <user-defined-name> @} ] [ <arg> ... ] +@end example + +@noindent +The syntax for @code{<arg>} depends on the particular macro, +but is generally a full expression (@pxref{expression syntax}). +Here are the exceptions to that general rule: + +@enumerate +@item +@code{INVOKE} macros, implicit or explicit, must be followed by +a list of name/string value pairs. The string values are +@i{simple expressions}, as described above. + +That is, the @code{INVOKE} syntax is one of these two: +@example +<user-macro-name> [ <name> [ = <expression> ] ... ] + +INVOKE <name-expression> [ <name> [ = <expression> ] ... ] +@end example + +@item +AutoGen FOR macros must be in one of three forms: + +@example +FOR <name> [ <separator-string> ] + +FOR <name> (...Scheme expression list) + +FOR <name> IN <string-entry> [ ... ] +@end example +@noindent +where: +@table @samp +@item <name> +must be a simple name. +@item <separator-string> +is inserted between copies of the enclosed block. Do not try to use ``IN'' +as your separator string. It won't work. +@item <string-entry> +is an entry in a list of strings. ``@code{<name>}'' is assigned +each value from the ``@code{IN}'' list before expanding the @code{FOR} block. +@item (...Scheme expression list) +is expected to contain one or more of the @code{for-from}, +@code{for-to}, @code{for-by}, and @code{for-sep} functions. +(@xref{FOR}, and @ref{AutoGen Functions}) +@end table + +The first two forms iterate over the @code{FOR} block if @code{<name>} +is found in the AutoGen values. The last form will create the AutoGen +value named @code{<name>}. + +@item +AutoGen @code{DEFINE} macros must be followed by a simple name. +Anything after that is ignored. Consequently, that ``comment space'' +may be used to document any named values the macro expects to have +set up as arguments. @xref{DEFINE}. + +@item +The AutoGen @code{COMMENT}, @code{ELSE}, @code{ESAC} and the @code{END*} +macros take no arguments and ignore everything after the macro name +(e.g. see @ref{COMMENT}) +@end enumerate + +@node BREAK +@subsection BREAK - Leave a FOR or WHILE macro + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/functions.c line 36. +@end ignore + +@findex BREAK + +This will unwind the loop context and resume after ENDFOR/ENDWHILE. +Note that unless this happens to be the last iteration anyway, +the (last-for?) function will never yield "#t". + +@node CASE +@subsection CASE - Select one of several template blocks + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 880. +@end ignore + +@findex CASE + +The arguments are evaluated and converted to a string, if necessary. A +simple name will be interpreted as an AutoGen value name and its value will +be used by the @code{SELECT} macros (see the example below and the +expression evaluation function, @pxref{EXPR}). The scope of the macro is +up to the matching @code{ESAC} macro. Within the scope of a @code{CASE}, +this string is matched against case selection macros. There are sixteen +match macros that are derived from four different ways matches may be +performed, plus an "always true", "true if the AutoGen value was found", +and "true if no AutoGen value was found" matches. The codes for the +nineteen match macros are formed as follows: + +@enumerate +@item +Must the match start matching from the beginning of the string? +If not, then the match macro code starts with an asterisk (@code{*}). +@item +Must the match finish matching at the end of the string? +If not, then the match macro code ends with an asterisk (@code{*}). +@item +Is the match a pattern match or a string comparison? +If a comparison, use an equal sign (@code{=}). +If a pattern match, use a tilde (@code{~}). +@item +Is the match case sensitive? +If alphabetic case is important, double the tilde or equal sign. +@item +Do you need a default match when none of the others match? +Use a single asterisk (@code{*}). +@item +Do you need to distinguish between an empty string value and a value +that was not found? Use the non-existence test (@code{!E}) before +testing a full match against an empty string (@code{== ''}). +There is also an existence test (@code{+E}), more for symmetry than +for practical use. +@end enumerate + +@noindent +For example: + +@example +[+ CASE <full-expression> +] +[+ ~~* "[Tt]est" +]reg exp must match at start, not at end +[+ == "TeSt" +]a full-string, case sensitive compare +[+ = "TEST" +]a full-string, case insensitive compare +[+ !E +]not exists - matches if no AutoGen value found +[+ == "" +]expression yielded a zero-length string +[+ +E +]exists - matches if there is any value result +[+ * +]always match - no testing +[+ ESAC +] +@end example + +@code{<full-expression>} (@pxref{expression syntax}) may be any expression, +including the use of apply-codes and value-names. If the expression yields +a number, it is converted to a decimal string. + +These case selection codes have also been implemented as +Scheme expression functions using the same codes. They are documented +in this texi doc as ``string-*?'' predicates (@pxref{Common Functions}). + +@node COMMENT +@subsection COMMENT - A block of comment to be ignored + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/functions.c line 348. +@end ignore + +@findex COMMENT + +This function can be specified by the user, but there will +never be a situation where it will be invoked at emit time. +The macro is actually removed from the internal representation. + +If the native macro name code is @code{#}, then the +entire macro function is treated as a comment and ignored. + +@example +[+ # say what you want, but no '+' before any ']' chars +] +@end example + +@node CONTINUE +@subsection CONTINUE - Skip to end of a FOR or WHILE macro. + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/functions.c line 26. +@end ignore + +@findex CONTINUE + +This will skip the remainder of the loop and start the next. + +@node DEBUG +@subsection DEBUG - Print debug message to trace output + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcDef.c line 387. +@end ignore + +@findex DEBUG + +If the tracing level is at "debug-message" or above +(@pxref{autogen trace}), this macro prints a debug message to trace +output. This message is not evaluated. This macro can also be used to +set useful debugger breakpoints. By inserting [+DEBUG n+] into your +template, you can set a debugger breakpoint on the #n case element +below (in the AutoGen source) and step through the processing of +interesting parts of your template. + +To be useful, you have to have access to the source tree where autogen +was built and the template being processed. The definitions are also +helpful, but not crucial. Please contact the author if you think you +might actually want to use this. + +@node DEFINE +@subsection DEFINE - Define a user AutoGen macro + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcDef.c line 531. +@end ignore + +@findex DEFINE +@cindex define macro + +This function will define a new macro. You must provide a name for the +macro. You do not specify any arguments, though the invocation may +specify a set of name/value pairs that are to be active during the +processing of the macro. + +@example +[+ define foo +] +... macro body with macro functions ... +[+ enddef +] +... [+ foo bar='raw text' baz=<<text expression>> +] +@end example + +Once the macro has been defined, this new macro can be invoked by +specifying the macro name as the first token after the start macro marker. +Alternatively, you may make the invocation explicitly invoke a defined +macro by specifying @code{INVOKE} (@pxref{INVOKE}) in the macro +invocation. If you do that, the macro name can be computed with an +expression that gets evaluated every time the INVOKE macro is encountered. + +Any remaining text in the macro invocation will be used to create new +name/value pairs that only persist for the duration of the processing of +the macro. The expressions are evaluated the same way basic +expressions are evaluated. @xref{expression syntax}. + +The resulting definitions are handled much like regular +definitions, except: + +@enumerate +@item +The values may not be compound. That is, they may not contain +nested name/value pairs. +@item +The bindings go away when the macro is complete. +@item +The name/value pairs are separated by whitespace instead of +semi-colons. +@item +Sequences of strings are not concatenated. +@end enumerate + +@quotation +@strong{NB:} The macro is extracted from the template as the template is +scanned. You cannot conditionally define a macro by enclosing it in an +@code{IF}/@code{ENDIF} (@pxref{IF}) macro pair. If you need to dynamically +select the format of a @code{DEFINE}d macro, then put the flavors into +separate template files that simply define macros. @code{INCLUDE} +(@pxref{INCLUDE}) the appropriate template when you have computed which +you need. +@end quotation + +Due to this, it is acceptable and even a good idea to place all the +@code{DEFINE} macros at the end of the template. That puts the main +body of the template at the beginning of the file. + +@node ELIF +@subsection ELIF - Alternate Conditional Template Block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcIf.c line 258. +@end ignore + +@findex ELIF + +This macro must only appear after an @code{IF} function, and +before any associated @code{ELSE} or @code{ENDIF} functions. +It denotes the start of an alternate template block for the +@code{IF} function. Its expression argument is evaluated as are +the arguments to @code{IF}. For a complete description @xref{IF}. + +@node ELSE +@subsection ELSE - Alternate Template Block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcIf.c line 286. +@end ignore + +@findex ELSE + +This macro must only appear after an @code{IF} function, +and before the associated @code{ENDIF} function. +It denotes the start of an alternate template block for +the @code{IF} function. For a complete description @xref{IF}. + +@node ENDDEF +@subsection ENDDEF - Ends a macro definition. + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcDef.c line 595. +@end ignore + +@findex ENDDEF + +This macro ends the @code{DEFINE} function template block. +For a complete description @xref{DEFINE}. + +@node ENDFOR +@subsection ENDFOR - Terminates the @code{FOR} function template block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 678. +@end ignore + +@findex ENDFOR + +This macro ends the @code{FOR} function template block. +For a complete description @xref{FOR}. + +@node ENDIF +@subsection ENDIF - Terminate the @code{IF} Template Block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcIf.c line 132. +@end ignore + +@findex ENDIF + +This macro ends the @code{IF} function template block. +For a complete description @xref{IF}. + +@node ENDWHILE +@subsection ENDWHILE - Terminate the @code{WHILE} Template Block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcIf.c line 215. +@end ignore + +@findex ENDWHILE + +This macro ends the @code{WHILE} function template block. +For a complete description @xref{WHILE}. + +@node ESAC +@subsection ESAC - Terminate the @code{CASE} Template Block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 947. +@end ignore + +@findex ESAC + +This macro ends the @code{CASE} function template block. +For a complete description, @xref{CASE}. + +@node EXPR +@subsection EXPR - Evaluate and emit an Expression + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcEval.c line 453. +@end ignore + +@findex EXPR + +This macro does not have a name to cause it to be invoked +explicitly, though if a macro starts with one of the apply codes +or one of the simple expression markers, then an expression +macro is inferred. The result of the expression evaluation +(@pxref{expression syntax}) is written to the current output. + +@node FOR +@subsection FOR - Emit a template block multiple times + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcFor.c line 599. +@end ignore + +@findex FOR +@cindex looping, for +@cindex for loop + +This macro has a slight variation on the standard syntax: +@example +FOR <value-name> [ <separator-string> ] + +FOR <value-name> (...Scheme expression list) + +FOR <value-name> IN "string" [ ... ] +@end example + +Other than for the last form, the first macro argument must be the name of +an AutoGen value. If there is no value associated with the name, the +@code{FOR} template block is skipped entirely. The scope of the @code{FOR} +macro extends to the corresponding @code{ENDFOR} macro. The last form will +create an array of string values named @code{<value-name>} that only exists +within the context of this @code{FOR} loop. With this form, in order to +use a @code{separator-string}, you must code it into the end of the +template block using the @code{(last-for?)} predicate function +(@pxref{SCM last-for?}). + +If there are any arguments after the @code{value-name}, the initial +characters are used to determine the form. If the first character is +either a semi-colon (@code{;}) or an opening parenthesis (@code{(}), then +it is presumed to be a Scheme expression containing the FOR macro specific +functions @code{for-from}, @code{for-by}, @code{for-to}, and/or +@code{for-sep}. @xref{AutoGen Functions}. If it consists of an '@code{i}' +an '@code{n}' and separated by white space from more text, then the +@code{FOR x IN} form is processed. Otherwise, the remaining text is +presumed to be a string for inserting between each iteration of the loop. +This string will be emitted one time less than the number of iterations of +the loop. That is, it is emitted after each loop, excepting for the last +iteration. + +If the from/by/to functions are invoked, they will specify which copies of +the named value are to be processed. If there is no copy of the named +value associated with a particular index, the @code{FOR} template block +will be instantiated anyway. The template must use methods for detecting +missing definitions and emitting default text. In this fashion, you can +insert entries from a sparse or non-zero based array into a dense, zero +based array. + +@strong{NB:} the @code{for-from}, @code{for-to}, @code{for-by} and +@code{for-sep} functions are disabled outside of the context of the +@code{FOR} macro. Likewise, the @code{first-for}, @code{last-for} +and @code{for-index} functions are disabled outside of the range +of a @code{FOR} block. + +@strong{Also:} the @code{<value-name>} must be a single level name, +not a compound name (@pxref{naming values}). + +@example +[+FOR var (for-from 0) (for-to <number>) (for-sep ",") +] +... text with @code{var}ious substitutions ...[+ +ENDFOR var+] +@end example + +@noindent +this will repeat the @code{... text with @code{var}ious +substitutions ...} <number>+1 times. Each repetition, +except for the last, will have a comma @code{,} after it. + +@example +[+FOR var ",\n" +] +... text with @code{var}ious substitutions ...[+ +ENDFOR var +] +@end example + +@noindent +This will do the same thing, but only for the index +values of @code{var} that have actually been defined. + +@node IF +@subsection IF - Conditionally Emit a Template Block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcIf.c line 96. +@end ignore + +@findex IF +@cindex conditional emit +@cindex if test + +Conditional block. Its arguments are evaluated (@pxref{EXPR}) and +if the result is non-zero or a string with one or more bytes, +then the condition is true and the text from that point +until a matched @code{ELIF}, @code{ELSE} or @code{ENDIF} is emitted. +@code{ELIF} introduces a conditional alternative if the @code{IF} +clause evaluated FALSE and @code{ELSE} introduces an unconditional +alternative. + +@example +[+IF <full-expression> +] +emit things that are for the true condition[+ + +ELIF <full-expression-2> +] +emit things that are true maybe[+ + +ELSE "This may be a comment" +] +emit this if all but else fails[+ + +ENDIF "This may *also* be a comment" +] +@end example + +@noindent +@code{<full-expression>} may be any expression described in the +@code{EXPR} expression function, including the use of apply-codes +and value-names. If the expression yields an empty string, it +is interpreted as @i{false}. + +@node INCLUDE +@subsection INCLUDE - Read in and emit a template block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/functions.c line 177. +@end ignore + +@findex INCLUDE + +The entire contents of the named file is inserted at this point. +The contents of the file are processed for macro expansion. The +arguments are eval-ed, so you may compute the name of the file to +be included. The included file must not contain any incomplete +function blocks. Function blocks are template text beginning with +any of the macro functions @samp{CASE}, @samp{DEFINE}, @samp{FOR}, +@samp{IF} and @samp{WHILE}; extending through their respective +terminating macro functions. + +@node INVOKE +@subsection INVOKE - Invoke a User Defined Macro + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcDef.c line 667. +@end ignore + +@findex INVOKE + +User defined macros may be invoked explicitly or implicitly. +If you invoke one implicitly, the macro must begin with the +name of the defined macro. Consequently, this may @strong{not} +be a computed value. If you explicitly invoke a user defined macro, +the macro begins with the macro name @code{INVOKE} followed by +a @i{basic expression} that must yield a known user defined macro. +A macro name _must_ be found, or AutoGen will issue a diagnostic +and exit. + +Arguments are passed to the invoked macro by name. +The text following the macro name must consist of a series of +names each of which is followed by an equal sign (@code{=}) and +a @i{basic expression} that yields a string. + +The string values may contain template macros that are parsed +the first time the macro is processed and evaluated again every +time the macro is evaluated. + +@node RETURN +@subsection RETURN - Leave an INVOKE-d (DEFINE) macro + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/functions.c line 93. +@end ignore + +@findex RETURN + +This will unwind looping constructs inside of a DEFINE-d macro and +return to the invocation point. The output files and diversions +@i{are left alone}. This means it is unwise to start diversions +in a DEFINEd macro and RETURN from it before you have handled the +diversion. Unless you are careful. Here is some rope for you. +Please be careful using it. + +@node SELECT +@subsection SELECT - Selection block for CASE function + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcCase.c line 1280. +@end ignore + +@findex SELECT + +This macro selects a block of text by matching an expression +against the sample text expression evaluated in the @code{CASE} +macro. @xref{CASE}. + +You do not specify a @code{SELECT} macro with the word ``select''. +Instead, you must use one of the 19 match operators described in +the @code{CASE} macro description. + +@node UNKNOWN +@subsection UNKNOWN - Either a user macro or a value name. + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/functions.c line 241. +@end ignore + +@findex UNKNOWN + +The macro text has started with a name not known to AutoGen. If, at run +time, it turns out to be the name of a defined macro, then that macro is +invoked. If it is not, then it is a conditional expression that is +evaluated only if the name is defined at the time the macro is invoked. + +You may not specify @code{UNKNOWN} explicitly. + +@node WHILE +@subsection WHILE - Conditionally loop over a Template Block + +@ignore +Generated from auto_gen.tpl line 538. +Extracted from /old-home/bkorb/ag/ag/agen5/funcIf.c line 188. +@end ignore + +@findex WHILE +@cindex conditional emit +@cindex while test + +Conditionally repeated block. Its arguments are evaluated (@pxref{EXPR}) +and as long as the result is non-zero or a string with one or more bytes, +then the condition is true and the text from that point +until a matched @code{ENDWHILE} is emitted. + +@example +[+WHILE <full-expression> +] +emit things that are for the true condition[+ + +ENDWHILE +] +@end example + +@noindent +@code{<full-expression>} may be any expression described in the +@code{EXPR} expression function, including the use of apply-codes +and value-names. If the expression yields an empty string, it +is interpreted as @i{false}. +@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 + +Invocation section from invoke-autogen.texi + +@end ignore +@page + +@include invoke-autogen.texi + +@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@page +@node AutoOpts +@chapter Automated Option Processing +@cindex autoopts + +AutoOpts 36.5 is bundled with AutoGen. It is a tool that virtually eliminates the +hassle of processing options and keeping man pages, info docs and usage text +up to date. This package allows you to specify several program attributes, up +to a hundred option types and many option attributes. From this, it then +produces all the code necessary to parse and handle the command line and +configuration file options, and the documentation that should go with your +program as well. +@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 +@noindent +First, specify your program attributes and its options to AutoOpts, +as with the following example. + +@example +AutoGen Definitions options; +prog-name = check; +prog-title = "Checkout Automated Options"; +long-opts; +gnu-usage; /* GNU style preferred to default */ + +main = @{ main-type = shell-process; @}; + +flag = @{ + name = check-dirs; + value = L; /* flag style option character */ + arg-type = string; /* option argument indication */ + max = NOLIMIT; /* occurrence limit (none) */ + stack-arg; /* save opt args in a stack */ + descrip = "Checkout directory list"; + doc = 'name of each directory that is to be "checked out".'; +@}; + +flag = @{ + name = show_defs; + descrip = "Show the definition tree"; + disable = dont; /* mark as enable/disable type */ + /* option. Disable as `dont-' */ + doc = 'disable, if you do not want to see the tree.'; +@}; +@end example + +@noindent +This program will produce a program that digests its options and +writes the values as shell script code to stdout. +Run the following short script to produce this program: + +@example +base=check +BASE=`echo $base | tr a-z- A-Z_` +cflags="-DTEST_$@{BASE@} `autoopts-config cflags`" +ldflags="`autoopts-config ldflags`" +autogen $@{base@}.def +cc -o $@{base@} -g $@{cflags@} $@{base@}.c $@{ldflags@} +./$@{base@} --help +@end example + +@noindent +Running those commands yields: + +@example +check - Checkout Automated Options +USAGE: check [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... + + -L, --check-dirs=str Checkout directory list + - may appear multiple times + --show-defs Show the definition tree + - disabled as --dont-show-defs + -?, --help Display extended usage information and exit + -!, --more-help Extended usage information passed thru pager + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. +Packaged by Bruce (2012-08-11) +Report check bugs to bkorb@@gnu.org +@end example +@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 +Here is an example program that uses the following set of definitions: + +@example +AutoGen Definitions options; + +prog-name = default-test; +prog-title = 'Default Option Example'; +homerc = '$$/../share/default-test', '$HOME', '.'; +environrc; +long-opts; +gnu-usage; +usage-opt; +version = '1.0'; +main = @{ + main-type = shell-process; +@}; +#define DEBUG_FLAG +#define WARN_FLAG +#define WARN_LEVEL +#define VERBOSE_FLAG +#define VERBOSE_ENUM +#define DRY_RUN_FLAG +#define OUTPUT_FLAG +#define INPUT_FLAG +#define DIRECTORY_FLAG +#define INTERACTIVE_FLAG +#include stdoptions.def +@end example + +@noindent +Running a few simple commands on that definition file: + +@example +autogen default-test.def +copts="-DTEST_DEFAULT_TEST_OPTS `autoopts-config cflags`" +lopts="`autoopts-config ldflags`" +cc -o default-test $@{copts@} default-test.c $@{lopts@} +@end example + +@noindent +Yields a program which, when run with @file{--help}, prints out: + +@example +default-test - Default Option Example - Ver. 1.0 +USAGE: default-test [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... + + +The following options are commonly used and are provided and supported +by AutoOpts: + + -D, --debug run program with debugging info + -V, --verbose=KWd run program with progress info + -w, --warn=num specify a warning-level threshhold + - disabled as --no-warn + -R, --dry-run program will make no changes + -I, --interactive=str prompt for confirmation + -i, --input=str redirect input from file + -o, --output=str redirect output to file + -d, --directory=str use specified dir for I/O + +version, usage and configuration options: + + -v, --version[=arg] Output version information and exit + -?, --help Display extended usage information and exit + -!, --more-help Extended usage information passed thru pager + -u, --usage Abbreviated usage to stdout + ->, --save-opts[=arg] Save the option state to a config file + -<, --load-opts=str Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +The following option preset mechanisms are supported: + - reading file $$/../share/default-test + - reading file $HOME/.default_testrc + - reading file ./.default_testrc + - examining environment variables named DEFAULT_TEST_* + +The valid "verbose" option keywords are: + silent quiet brief informative verbose + or an integer from 0 through 4 +Packaged by Bruce (2012-08-11) +Report default_test bugs to bkorb@@gnu.org +@end example +@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 +@node libopts procedures +@subsection libopts External Procedures + +These are the routines that libopts users may call directly from their +code. There are several other routines that can be called by code +generated by the libopts option templates, but they are not to be +called from any other user code. The @file{options.h} header is +fairly clear about this, too. + +@menu +* libopts-ao_string_tokenize:: ao_string_tokenize +* libopts-configFileLoad:: configFileLoad +* libopts-optionFileLoad:: optionFileLoad +* libopts-optionFindNextValue:: optionFindNextValue +* libopts-optionFindValue:: optionFindValue +* libopts-optionFree:: optionFree +* libopts-optionGetValue:: optionGetValue +* libopts-optionLoadLine:: optionLoadLine +* libopts-optionNextValue:: optionNextValue +* libopts-optionOnlyUsage:: optionOnlyUsage +* libopts-optionProcess:: optionProcess +* libopts-optionRestore:: optionRestore +* libopts-optionSaveFile:: optionSaveFile +* libopts-optionSaveState:: optionSaveState +* libopts-optionUnloadNested:: optionUnloadNested +* libopts-optionVersion:: optionVersion +* libopts-pathfind:: pathfind +* libopts-strequate:: strequate +* libopts-streqvcmp:: streqvcmp +* libopts-streqvmap:: streqvmap +* libopts-strneqvcmp:: strneqvcmp +* libopts-strtransform:: strtransform +@end menu + +This subsection was automatically generated by AutoGen +using extracted information and the aginfo3.tpl template. + +@node libopts-ao_string_tokenize +@subsubsection ao_string_tokenize +@findex ao_string_tokenize + +tokenize an input string + +@noindent +Usage: +@example +token_list_t* res = ao_string_tokenize( string ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab string @tab @code{char const*} +@tab string to be tokenized +@item @tab returns @tab token_list_t* +@tab pointer to a structure that lists each token +@end multitable + +This function will convert one input string into a list of strings. +The list of strings is derived by separating the input based on +white space separation. However, if the input contains either single +or double quote characters, then the text after that character up to +a matching quote will become the string in the list. + +The returned pointer should be deallocated with @code{free(3C)} when +are done using the data. The data are placed in a single block of +allocated memory. Do not deallocate individual token/strings. + +The structure pointed to will contain at least these two fields: +@table @samp +@item tkn_ct +The number of tokens found in the input string. +@item tok_list +An array of @code{tkn_ct + 1} pointers to substring tokens, with +the last pointer set to NULL. +@end table + +There are two types of quoted strings: single quoted (@code{'}) and +double quoted (@code{"}). Singly quoted strings are fairly raw in that +escape characters (@code{\\}) are simply another character, except when +preceding the following characters: +@example +@code{\\} double backslashes reduce to one +@code{'} incorporates the single quote into the string +@code{\n} suppresses both the backslash and newline character +@end example + +Double quote strings are formed according to the rules of string +constants in ANSI-C programs. + +NULL is returned and @code{errno} will be set to indicate the problem: +@itemize @bullet +@item +@code{EINVAL} - There was an unterminated quoted string. +@item +@code{ENOENT} - The input string was empty. +@item +@code{ENOMEM} - There is not enough memory. +@end itemize + + +@node libopts-configFileLoad +@subsubsection configFileLoad +@findex configFileLoad + +parse a configuration file + +@noindent +Usage: +@example +const tOptionValue* res = configFileLoad( pzFile ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pzFile @tab @code{char const*} +@tab the file to load +@item @tab returns @tab const tOptionValue* +@tab An allocated, compound value structure +@end multitable + +This routine will load a named configuration file and parse the +text as a hierarchically valued option. The option descriptor +created from an option definition file is not used via this interface. +The returned value is "named" with the input file name and is of +type "@code{OPARG_TYPE_HIERARCHY}". It may be used in calls to +@code{optionGetValue()}, @code{optionNextValue()} and +@code{optionUnloadNested()}. + +If the file cannot be loaded or processed, @code{NULL} is returned and +@var{errno} is set. It may be set by a call to either @code{open(2)} +@code{mmap(2)} or other file system calls, or it may be: +@itemize @bullet +@item +@code{ENOENT} - the file was not found. +@item +@code{ENOMSG} - the file was empty. +@item +@code{EINVAL} - the file contents are invalid -- not properly formed. +@item +@code{ENOMEM} - not enough memory to allocate the needed structures. +@end itemize + + +@node libopts-optionFileLoad +@subsubsection optionFileLoad +@findex optionFileLoad + +Load the locatable config files, in order + +@noindent +Usage: +@example +int res = optionFileLoad( pOpts, pzProg ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab pzProg @tab @code{char const*} +@tab program name +@item @tab returns @tab int +@tab 0 -> SUCCESS, -1 -> FAILURE +@end multitable + +This function looks in all the specified directories for a configuration +file ("rc" file or "ini" file) and processes any found twice. The first +time through, they are processed in reverse order (last file first). At +that time, only "immediate action" configurables are processed. For +example, if the last named file specifies not processing any more +configuration files, then no more configuration files will be processed. +Such an option in the @strong{first} named directory will have no effect. + +Once the immediate action configurables have been handled, then the +directories are handled in normal, forward order. In that way, later +config files can override the settings of earlier config files. + +See the AutoOpts documentation for a thorough discussion of the +config file format. + +Configuration files not found or not decipherable are simply ignored. + +Returns the value, "-1" if the program options descriptor +is out of date or indecipherable. Otherwise, the value "0" will +always be returned. + + +@node libopts-optionFindNextValue +@subsubsection optionFindNextValue +@findex optionFindNextValue + +find a hierarcicaly valued option instance + +@noindent +Usage: +@example +const tOptionValue* res = optionFindNextValue( pOptDesc, pPrevVal, name, value ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptDesc @tab @code{const tOptDesc*} +@tab an option with a nested arg type + +@item @tab pPrevVal @tab @code{const tOptionValue*} +@tab the last entry + +@item @tab name @tab @code{char const*} +@tab name of value to find + +@item @tab value @tab @code{char const*} +@tab the matching value +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +This routine will find the next entry in a nested value option or +configurable. It will search through the list and return the next entry +that matches the criteria. + +The returned result is NULL and errno is set: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value. +@item +@code{ENOENT} - no entry matched the given name. +@end itemize + + +@node libopts-optionFindValue +@subsubsection optionFindValue +@findex optionFindValue + +find a hierarcicaly valued option instance + +@noindent +Usage: +@example +const tOptionValue* res = optionFindValue( pOptDesc, name, value ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptDesc @tab @code{const tOptDesc*} +@tab an option with a nested arg type + +@item @tab name @tab @code{char const*} +@tab name of value to find + +@item @tab value @tab @code{char const*} +@tab the matching value +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +This routine will find an entry in a nested value option or configurable. +It will search through the list and return a matching entry. + +The returned result is NULL and errno is set: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value. +@item +@code{ENOENT} - no entry matched the given name. +@end itemize + + +@node libopts-optionFree +@subsubsection optionFree +@findex optionFree + +free allocated option processing memory + +@noindent +Usage: +@example +optionFree( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +AutoOpts sometimes allocates memory and puts pointers to it in the +option state structures. This routine deallocates all such memory. + +As long as memory has not been corrupted, +this routine is always successful. + + +@node libopts-optionGetValue +@subsubsection optionGetValue +@findex optionGetValue + +get a specific value from a hierarcical list + +@noindent +Usage: +@example +const tOptionValue* res = optionGetValue( pOptValue, valueName ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptValue @tab @code{const tOptionValue*} +@tab a hierarchcal value + +@item @tab valueName @tab @code{char const*} +@tab name of value to get +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +This routine will find an entry in a nested value option or configurable. +If "valueName" is NULL, then the first entry is returned. Otherwise, +the first entry with a name that exactly matches the argument will be +returned. If there is no matching value, NULL is returned and errno is +set to ENOENT. If the provided option value is not a hierarchical value, +NULL is also returned and errno is set to EINVAL. + +The returned result is NULL and errno is set: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value. +@item +@code{ENOENT} - no entry matched the given name. +@end itemize + + +@node libopts-optionLoadLine +@subsubsection optionLoadLine +@findex optionLoadLine + +process a string for an option name and value + +@noindent +Usage: +@example +optionLoadLine( opts, line ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab opts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab line @tab @code{char const*} +@tab NUL-terminated text +@end multitable + +This is a client program callable routine for setting options from, for +example, the contents of a file that they read in. Only one option may +appear in the text. It will be treated as a normal (non-preset) option. + +When passed a pointer to the option struct and a string, it will find +the option named by the first token on the string and set the option +argument to the remainder of the string. The caller must NUL terminate +the string. The caller need not skip over any introductory hyphens. +Any embedded new lines will be included in the option +argument. If the input looks like one or more quoted strings, then the +input will be "cooked". The "cooking" is identical to the string +formation used in AutoGen definition files (@pxref{basic expression}), +except that you may not use backquotes. + +Invalid options are silently ignored. Invalid option arguments +will cause a warning to print, but the function should return. + + +@node libopts-optionNextValue +@subsubsection optionNextValue +@findex optionNextValue + +get the next value from a hierarchical list + +@noindent +Usage: +@example +const tOptionValue* res = optionNextValue( pOptValue, pOldValue ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptValue @tab @code{const tOptionValue*} +@tab a hierarchcal list value + +@item @tab pOldValue @tab @code{const tOptionValue*} +@tab a value from this list +@item @tab returns @tab const tOptionValue* +@tab a compound value structure +@end multitable + +This routine will return the next entry after the entry passed in. At the +end of the list, NULL will be returned. If the entry is not found on the +list, NULL will be returned and "@var{errno}" will be set to EINVAL. +The "@var{pOldValue}" must have been gotten from a prior call to this +routine or to "@code{opitonGetValue()}". + +The returned result is NULL and errno is set: +@itemize @bullet +@item +@code{EINVAL} - the @code{pOptValue} does not point to a valid +hierarchical option value or @code{pOldValue} does not point to a +member of that option value. +@item +@code{ENOENT} - the supplied @code{pOldValue} pointed to the last entry. +@end itemize + + +@node libopts-optionOnlyUsage +@subsubsection optionOnlyUsage +@findex optionOnlyUsage + +Print usage text for just the options + +@noindent +Usage: +@example +optionOnlyUsage( pOpts, ex_code ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab ex_code @tab @code{int} +@tab exit code for calling exit(3) +@end multitable + +This routine will print only the usage for each option. +This function may be used when the emitted usage must incorporate +information not available to AutoOpts. + + +@node libopts-optionProcess +@subsubsection optionProcess +@findex optionProcess + +this is the main option processing routine + +@noindent +Usage: +@example +int res = optionProcess( pOpts, argc, argv ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor + +@item @tab argc @tab @code{int} +@tab program arg count + +@item @tab argv @tab @code{char**} +@tab program arg vector +@item @tab returns @tab int +@tab the count of the arguments processed +@end multitable + +This is the main entry point for processing options. It is intended +that this procedure be called once at the beginning of the execution of +a program. Depending on options selected earlier, it is sometimes +necessary to stop and restart option processing, or to select completely +different sets of options. This can be done easily, but you generally +do not want to do this. + +The number of arguments processed always includes the program name. +If one of the arguments is "--", then it is counted and the processing +stops. If an error was encountered and errors are to be tolerated, then +the returned value is the index of the argument causing the error. +A hyphen by itself ("-") will also cause processing to stop and will +@emph{not} be counted among the processed arguments. A hyphen by itself +is treated as an operand. Encountering an operand stops option +processing. + +Errors will cause diagnostics to be printed. @code{exit(3)} may +or may not be called. It depends upon whether or not the options +were generated with the "allow-errors" attribute, or if the +ERRSKIP_OPTERR or ERRSTOP_OPTERR macros were invoked. + + +@node libopts-optionRestore +@subsubsection optionRestore +@findex optionRestore + +restore option state from memory copy + +@noindent +Usage: +@example +optionRestore( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +Copy back the option state from saved memory. +The allocated memory is left intact, so this routine can be +called repeatedly without having to call optionSaveState again. +If you are restoring a state that was saved before the first call +to optionProcess(3AO), then you may change the contents of the +argc/argv parameters to optionProcess. + +If you have not called @code{optionSaveState} before, a diagnostic is +printed to @code{stderr} and exit is called. + + +@node libopts-optionSaveFile +@subsubsection optionSaveFile +@findex optionSaveFile + +saves the option state to a file + +@noindent +Usage: +@example +optionSaveFile( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +This routine will save the state of option processing to a file. The name +of that file can be specified with the argument to the @code{--save-opts} +option, or by appending the @code{rcfile} attribute to the last +@code{homerc} attribute. If no @code{rcfile} attribute was specified, it +will default to @code{.@i{programname}rc}. If you wish to specify another +file, you should invoke the @code{SET_OPT_SAVE_OPTS(@i{filename})} macro. + +The recommend usage is as follows: +@example +optionProcess(&progOptions, argc, argv); +if (i_want_a_non_standard_place_for_this) +SET_OPT_SAVE_OPTS("myfilename"); +optionSaveFile(&progOptions); +@end example + +If no @code{homerc} file was specified, this routine will silently return +and do nothing. If the output file cannot be created or updated, a message +will be printed to @code{stderr} and the routine will return. + + +@node libopts-optionSaveState +@subsubsection optionSaveState +@findex optionSaveState + +saves the option state to memory + +@noindent +Usage: +@example +optionSaveState( pOpts ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOpts @tab @code{tOptions*} +@tab program options descriptor +@end multitable + +This routine will allocate enough memory to save the current option +processing state. If this routine has been called before, that memory +will be reused. You may only save one copy of the option state. This +routine may be called before optionProcess(3AO). If you do call it +before the first call to optionProcess, then you may also change the +contents of argc/argv after you call optionRestore(3AO) + +In fact, more strongly put: it is safest to only use this function +before having processed any options. In particular, the saving and +restoring of stacked string arguments and hierarchical values is +disabled. The values are not saved. + +If it fails to allocate the memory, +it will print a message to stderr and exit. +Otherwise, it will always succeed. + + +@node libopts-optionUnloadNested +@subsubsection optionUnloadNested +@findex optionUnloadNested + +Deallocate the memory for a nested value + +@noindent +Usage: +@example +optionUnloadNested( pOptVal ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab pOptVal @tab @code{tOptionValue const *} +@tab the hierarchical value +@end multitable + +A nested value needs to be deallocated. The pointer passed in should +have been gotten from a call to @code{configFileLoad()} (See +@pxref{libopts-configFileLoad}). + + +@node libopts-optionVersion +@subsubsection optionVersion +@findex optionVersion + +return the compiled AutoOpts version number + +@noindent +Usage: +@example +char const* res = optionVersion(); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab returns @tab char const* +@tab the version string in constant memory +@end multitable + +Returns the full version string compiled into the library. +The returned string cannot be modified. + + +@node libopts-pathfind +@subsubsection pathfind +@findex pathfind + +fild a file in a list of directories + +@noindent +Usage: +@example +char* res = pathfind( path, file, mode ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab path @tab @code{char const*} +@tab colon separated list of search directories + +@item @tab file @tab @code{char const*} +@tab the name of the file to look for + +@item @tab mode @tab @code{char const*} +@tab the mode bits that must be set to match +@item @tab returns @tab char* +@tab the path to the located file +@end multitable + +pathfind looks for a a file with name "FILE" and "MODE" access +along colon delimited "PATH", and returns the full pathname as a +string, or NULL if not found. If "FILE" contains a slash, then +it is treated as a relative or absolute path and "PATH" is ignored. + +@strong{NOTE}: this function is compiled into @file{libopts} only if +it is not natively supplied. + +The "MODE" argument is a string of option letters chosen from the +list below: +@example +Letter Meaning +r readable +w writable +x executable +f normal file (NOT IMPLEMENTED) +b block special (NOT IMPLEMENTED) +c character special (NOT IMPLEMENTED) +d directory (NOT IMPLEMENTED) +p FIFO (pipe) (NOT IMPLEMENTED) +u set user ID bit (NOT IMPLEMENTED) +g set group ID bit (NOT IMPLEMENTED) +k sticky bit (NOT IMPLEMENTED) +s size nonzero (NOT IMPLEMENTED) +@end example + +returns NULL if the file is not found. + + +@node libopts-strequate +@subsubsection strequate +@findex strequate + +map a list of characters to the same value + +@noindent +Usage: +@example +strequate( ch_list ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab ch_list @tab @code{char const*} +@tab characters to equivalence +@end multitable + +Each character in the input string get mapped to the first character +in the string. +This function name is mapped to option_strequate so as to not conflict +with the POSIX name space. + +none. + + +@node libopts-streqvcmp +@subsubsection streqvcmp +@findex streqvcmp + +compare two strings with an equivalence mapping + +@noindent +Usage: +@example +int res = streqvcmp( str1, str2 ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab str1 @tab @code{char const*} +@tab first string + +@item @tab str2 @tab @code{char const*} +@tab second string +@item @tab returns @tab int +@tab the difference between two differing characters +@end multitable + +Using a character mapping, two strings are compared for "equivalence". +Each input character is mapped to a comparison character and the +mapped-to characters are compared for the two NUL terminated input strings. +This function name is mapped to option_streqvcmp so as to not conflict +with the POSIX name space. + +none checked. Caller responsible for seg faults. + + +@node libopts-streqvmap +@subsubsection streqvmap +@findex streqvmap + +Set the character mappings for the streqv functions + +@noindent +Usage: +@example +streqvmap( From, To, ct ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab From @tab @code{char} +@tab Input character + +@item @tab To @tab @code{char} +@tab Mapped-to character + +@item @tab ct @tab @code{int} +@tab compare length +@end multitable + +Set the character mapping. If the count (@code{ct}) is set to zero, then +the map is cleared by setting all entries in the map to their index +value. Otherwise, the "@code{From}" character is mapped to the "@code{To}" +character. If @code{ct} is greater than 1, then @code{From} and @code{To} +are incremented and the process repeated until @code{ct} entries have been +set. For example, +@example +streqvmap('a', 'A', 26); +@end example +@noindent +will alter the mapping so that all English lower case letters +will map to upper case. + +This function name is mapped to option_streqvmap so as to not conflict +with the POSIX name space. + +none. + + +@node libopts-strneqvcmp +@subsubsection strneqvcmp +@findex strneqvcmp + +compare two strings with an equivalence mapping + +@noindent +Usage: +@example +int res = strneqvcmp( str1, str2, ct ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab str1 @tab @code{char const*} +@tab first string + +@item @tab str2 @tab @code{char const*} +@tab second string + +@item @tab ct @tab @code{int} +@tab compare length +@item @tab returns @tab int +@tab the difference between two differing characters +@end multitable + +Using a character mapping, two strings are compared for "equivalence". +Each input character is mapped to a comparison character and the +mapped-to characters are compared for the two NUL terminated input strings. +The comparison is limited to @code{ct} bytes. +This function name is mapped to option_strneqvcmp so as to not conflict +with the POSIX name space. + +none checked. Caller responsible for seg faults. + + +@node libopts-strtransform +@subsubsection strtransform +@findex strtransform + +convert a string into its mapped-to value + +@noindent +Usage: +@example +strtransform( dest, src ); +@end example +@noindent +Where the arguments are: +@multitable @columnfractions .05 .15 .20 .55 +@item @tab Name @tab Type @tab Description +@item @tab ----- @tab ----- @tab ------------- +@item @tab dest @tab @code{char*} +@tab output string + +@item @tab src @tab @code{char const*} +@tab input string +@end multitable + +Each character in the input string is mapped and the mapped-to +character is put into the output. +This function name is mapped to option_strtransform so as to not conflict +with the POSIX name space. + +The source and destination may be the same. + +none. +@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 +@noindent +Doing so with getdefs' option definitions yields this sample-getdefsrc file. +I tend to be wordy in my @code{doc} attributes: + +@example +# getdefs sample configuration file +## This source file is copyrighted and licensed under the following terms: +# +# Copyright (C) 1999-2012 Bruce Korb, all rights reserved. +# This is free software. It is licensed for use, modification and +# redistribution under the terms of the +# GNU General Public License, version 3 or later +# <http://gnu.org/licenses/gpl.html> +# +# getdefs is free software: you can redistribute it and/or modify it +# under the terms of the GNU General Public License as published by the +# Free Software Foundation, either version 3 of the License, or +# (at your option) any later version. +# +# getdefs is distributed in the hope that it will be useful, but +# WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. +# See the GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program. If not, see <http://www.gnu.org/licenses/>. + +# defs_to_get -- Regexp to look for after the "/*=" +# +# +# +# +# If you want definitions only from a particular category, or even +# with names matching particular patterns, then specify this regular +# expression for the text that must follow the @@code@{/*=@}. +# Example: +# +#defs_to_get reg-ex + +# subblock -- subblock definition names +# +# +# +# +# This option is used to create shorthand entries for nested definitions. +# For example, with: +# @@table @@r +# @@item using subblock thus +# @@code@{--subblock=arg=argname,type,null@} +# @@item and defining an @@code@{arg@} thus +# @@code@{arg: this, char *@} +# @@item will then expand to: +# @@code@{arg = @@@{ argname = this; type = "char *"; @@@};@} +# @@end table +# The "this, char *" string is separated at the commas, with the +# white space removed. You may use characters other than commas by +# starting the value string with a punctuation character other than +# a single or double quote character. You may also omit intermediate +# values by placing the commas next to each other with no intervening +# white space. For example, "+mumble++yes+" will expand to: +# @@* +# @@code@{arg = @@@{ argname = mumble; null = "yes"; @@@};@}. +# Example: +# +#subblock sub-def + +# listattr -- attribute with list of values +# +# +# +# +# This option is used to create shorthand entries for definitions +# that generally appear several times. That is, they tend to be +# a list of values. For example, with: +# @@* +# @@code@{listattr=foo@} defined, the text: +# @@* +# @@code@{foo: this, is, a, multi-list@} will then expand to: +# @@* +# @@code@{foo = 'this', 'is', 'a', 'multi-list';@} +# @@* +# The texts are separated by the commas, with the +# white space removed. You may use characters other than commas by +# starting the value string with a punctuation character other than +# a single or double quote character. +# Example: +# +#listattr def + +# ordering -- Alphabetize or use named file +# +# +# +# +# By default, ordering is alphabetical by the entry name. Use, +# @@code@{no-ordering@} if order is unimportant. Use @@code@{ordering@} +# with no argument to order without case sensitivity. Use +# @@code@{ordering=<file-name>@} if chronological order is important. +# getdefs will maintain the text content of @@code@{file-name@}. +# @@code@{file-name@} need not exist. +# Example: +# +#ordering file-name + +# first_index -- The first index to apply to groups +# +# This configuration value takes an integer number as its argument. +# +# +# By default, the first occurrence of a named definition will have an +# index of zero. Sometimes, that needs to be a reserved value. Provide +# this option to specify a different starting point. +# Example: +# +#first_index 0 + +# filelist -- Insert source file names into defs +# +# +# +# +# Inserts the name of each input file into the output definitions. +# If no argument is supplied, the format will be: +# @@example +# infile = '%s'; +# @@end example +# If an argument is supplied, that string will be used for the entry +# name instead of @@var@{infile@}. +# Example: +# +#filelist file + +# assign -- Global assignments +# +# +# +# +# The argument to each copy of this option will be inserted into +# the output definitions, with only a semicolon attached. +# Example: +# +#assign ag-def + +# common_assign -- Assignments common to all blocks +# +# +# +# +# The argument to each copy of this option will be inserted into +# each output definition, with only a semicolon attached. +# Example: +# +#common_assign ag-def + +# copy -- File(s) to copy into definitions +# +# +# +# +# The content of each file named by these options will be inserted into +# the output definitions. +# Example: +# +#copy file + +# srcfile -- Insert source file name into each def +# +# +# +# +# Inserts the name of the input file where a definition was found +# into the output definition. +# If no argument is supplied, the format will be: +# @@example +# srcfile = '%s'; +# @@end example +# If an argument is supplied, that string will be used for the entry +# name instead of @@var@{srcfile@}. +# Example: +# +#srcfile file + +# linenum -- Insert source line number into each def +# +# +# +# +# Inserts the line number in the input file where a definition +# was found into the output definition. +# If no argument is supplied, the format will be: +# @@example +# linenum = '%s'; +# @@end example +# If an argument is supplied, that string will be used for the entry +# name instead of @@var@{linenum@}. +# Example: +# +#linenum def-name + +# input -- Input file to search for defs +# +# +# +# +# All files that are to be searched for definitions must be named on +# the command line or read from @@code@{stdin@}. If there is only one +# @@code@{input@} option and it is the string, "-", then the input file +# list is read from @@code@{stdin@}. If a command line argument is not +# an option name and does not contain an assignment operator +# (@@code@{=@}), then it defaults to being an input file name. +# At least one input file must be specified. +# Example: +# +#input src-file + +# output -- Output file to open +# +# +# +# +# If you are not sending the output to an AutoGen process, +# you may name an output file instead. +# Example: +# +#output file + +# autogen -- Invoke AutoGen with defs +# +# +# +# +# This is the default output mode. Specifying @@code@{no-autogen@} is +# equivalent to @@code@{output=-@}. If you supply an argument to this +# option, that program will be started as if it were AutoGen and +# its standard in will be set to the output definitions of this program. +# Example: +# +#autogen ag-cmd + +# template -- Template Name +# +# +# +# +# Specifies the template name to be used for generating the final output. +# Example: +# +#template file + +# agarg -- AutoGen Argument +# +# +# +# +# This is a pass-through argument. It allows you to specify any +# arbitrary argument to be passed to AutoGen. +# Example: +# +#agarg ag-opt + +# base_name -- Base name for output file(s) +# +# +# +# +# When output is going to AutoGen, a base name must either be supplied +# or derived. If this option is not supplied, then it is taken from +# the @@code@{template@} option. If that is not provided either, then +# it is set to the base name of the current directory. +# Example: +# +#base_name name +@end example +@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 +@example +#include <config.h> +#include <sys/types.h> +#include <stdio.h> +#include <pwd.h> +#include <string.h> +#ifdef HAVE_UNISTD_H +#include <unistd.h> +#endif +#include <autoopts/options.h> +int main(int argc, char ** argv) @{ + char const * greeting = "Hello"; + char const * greeted = "World"; + tOptionValue const * pOV = configFileLoad("hello.conf"); + + if (pOV != NULL) @{ + const tOptionValue* pGetV = optionGetValue(pOV, "greeting"); + + if ( (pGetV != NULL) + && (pGetV->valType == OPARG_TYPE_STRING)) + greeting = strdup(pGetV->v.strVal); + + pGetV = optionGetValue(pOV, "personalize"); + if (pGetV != NULL) @{ + struct passwd * pwe = getpwuid(getuid()); + if (pwe != NULL) + greeted = strdup(pwe->pw_gecos); + @} + + optionUnloadNested(pOV); /* deallocate config data */ + @} + printf("%s, %s!\n", greeting, greeted); + return 0; +@} +@end example + +@noindent +With that text in a file named ``hello.c'', this short script: + +@example +cc -o hello hello.c `autoopts-config cflags ldflags` +./hello +echo 'greeting Buzz off' > hello.conf +./hello +echo personalize > hello.conf +./hello +@end example + +@noindent +will produce the following output: + +@example +Hello, World! +Buzz off, World! +Hello, Bruce Korb! +@end example +@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 + +Here is the usage output example from AutoOpts error handling +tests. The option definition has argument reordering enabled: + +@example +test_errors - Test AutoOpts for errors +USAGE: errors [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... arg ... + Flg Arg Option-Name Description + -o no option The option option descrip + -s Str second The second option descrip + - may appear up to 10 times + -i --- ignored we have dumped this + -X no another Another option descrip + - may appear up to 5 times + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + -> opt save-opts Save the option state to a config file + -< Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. +Operands and options may be intermixed. They will be reordered. + +The following option preset mechanisms are supported: + - reading file errorsRC +Packaged by Bruce (2012-08-11) +Report test_errors bugs to bkorb@@gnu.org +@end example + +Using the invocation, +@example + test-errors operand1 -s first operand2 -X -- -s operand3 +@end example +you get the following output for your shell script to evaluate: + +@example +OPTION_CT=4 +export OPTION_CT +TEST_ERRORS_SECOND='first' +export TEST_ERRORS_SECOND +TEST_ERRORS_ANOTHER=1 # 0x1 +export TEST_ERRORS_ANOTHER +set -- 'operand1' 'operand2' '-s' 'operand3' +OPTION_CT=0 +@end example +@node script-parser +@subsection Parsing with a Portable Script + +If you had used @code{test-main = optionParseShell} instead, then you can, +at this point, merely run the program and it will write the parsing +script to standard out. You may also provide this program with command +line options to specify the shell script file to create or edit, and you +may specify the shell program to use on the first shell script line. +That program's usage text would look something like the following +and the script parser itself would be very verbose: + +@example +genshellopt - Generate Shell Option Processing Script - Ver. 1 +USAGE: genshellopt [ -<flag> [<val>] | --<name>[@{=| @}<val>] ]... + Flg Arg Option-Name Description + -o Str script Output Script File + -s Str shell Shell name (follows "#!" magic) + - disabled as --no-shell + - enabled by default + -v opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +Note that ``shell'' is only useful if the output file does not already +exist. If it does, then the shell name and optional first argument will be +extracted from the script file. + +If the script file already exists and contains Automated Option Processing +text, the second line of the file through the ending tag will be replaced +by the newly generated text. The first ``#!'' line will be regenerated. +Packaged by Bruce (2012-08-11) +Report genshellopt bugs to bkorb@@gnu.org + += = = = = = = = + +This incarnation of genshell will produce +a shell script to parse the options for getdefs: + +getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5 +USAGE: getdefs [ <option-name>[@{=| @}<val>] ]... + Arg Option-Name Description + Str defs-to-get Regexp to look for after the "/*=" + Str subblock subblock definition names + Str listattr attribute with list of values + opt ordering Alphabetize or use named file + Num first-index The first index to apply to groups + opt filelist Insert source file names into defs + Str assign Global assignments + Str common-assign Assignments common to all blocks + Str copy File(s) to copy into definitions + opt srcfile Insert source file name into each def + opt linenum Insert source line number into each def + Str input Input file to search for defs + Str output Output file to open + opt autogen Invoke AutoGen with defs + Str template Template Name + Str agarg AutoGen Argument + Str base-name Base name for output file(s) + opt version Output version information and exit + no help Display extended usage information and exit + no more-help Extended usage information passed thru pager + opt save-opts Save the option state to a config file + Str load-opts Load options from a config file + +All arguments are named options. + +If no ``input'' argument is provided or is set to simply "-", and if +``stdin'' is not a ``tty'', then the list of input files will be read from +``stdin''. +Packaged by Bruce (2012-08-11) +Report getdefs bugs to bkorb@@gnu.org +@end example + +@noindent +Resulting in the following script: +@example +#! /bin/sh +# # # # # # # # # # -- do not modify this marker -- +# +# DO NOT EDIT THIS SECTION OF /old-home/bkorb/ag/ag/doc/ag-texi-30133.d/.ag-eFukQW/genshellopt.sh +# +# From here to the next `-- do not modify this marker --', +# the text has been generated Saturday August 11, 2012 at 09:42:46 AM PDT +# From the GETDEFS option definitions +# +GETDEFS_LONGUSAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5 +USAGE: getdefs [ <option-name>[@{=| @}<val>] ]... + +Specify which definitions are of interest and what to say about them: + + Arg Option-Name Description + Str defs-to-get Regexp to look for after the "/*=" + Str subblock subblock definition names + - may appear multiple times + Str listattr attribute with list of values + - may appear multiple times + +specify how to number the definitions: + + Arg Option-Name Description + opt ordering Alphabetize or use named file + - disabled as --no-ordering + - enabled by default + Num first-index The first index to apply to groups + +Definition insertion options: + + Arg Option-Name Description + opt filelist Insert source file names into defs + Str assign Global assignments + - may appear multiple times + Str common-assign Assignments common to all blocks + - may appear multiple times + Str copy File(s) to copy into definitions + - may appear multiple times + opt srcfile Insert source file name into each def + opt linenum Insert source line number into each def + +specify which files to search for markers: + + Arg Option-Name Description + Str input Input file to search for defs + - may appear multiple times + - default option for unnamed options + +Definition output disposition options:: + + Arg Option-Name Description + Str output Output file to open + - an alternate for autogen + opt autogen Invoke AutoGen with defs + - disabled as --no-autogen + - enabled by default + Str template Template Name + Str agarg AutoGen Argument + - prohibits these options: + output + - may appear multiple times + Str base-name Base name for output file(s) + - prohibits these options: + output + +version, usage and configuration options: + + Arg Option-Name Description + opt version Output version information and exit + no help Display extended usage information and exit + no more-help Extended usage information passed thru pager + opt save-opts Save the option state to a config file + Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +All arguments are named options. + +If no ``input'\'''\'' argument is provided or is set to simply "-", and if +``stdin'\'''\'' is not a ``tty'\'''\'', then the list of input files will be read from +``stdin'\'''\''. + +The following option preset mechanisms are supported: + - reading file /dev/null + +This program extracts AutoGen definitions from a list of source files. +Definitions are delimited by ``/*=<entry-type> <entry-name>\n'\'''\'' and +``=*/\n'\'''\''. +Packaged by Bruce (2012-08-11) +Report getdefs bugs to bkorb@@gnu.org' + +GETDEFS_USAGE_TEXT='getdefs (GNU AutoGen) - AutoGen Definition Extraction Tool - Ver. 1.5 +USAGE: getdefs [ <option-name>[@{=| @}<val>] ]... + Arg Option-Name Description + Str defs-to-get Regexp to look for after the "/*=" + Str subblock subblock definition names + Str listattr attribute with list of values + opt ordering Alphabetize or use named file + Num first-index The first index to apply to groups + opt filelist Insert source file names into defs + Str assign Global assignments + Str common-assign Assignments common to all blocks + Str copy File(s) to copy into definitions + opt srcfile Insert source file name into each def + opt linenum Insert source line number into each def + Str input Input file to search for defs + Str output Output file to open + opt autogen Invoke AutoGen with defs + Str template Template Name + Str agarg AutoGen Argument + Str base-name Base name for output file(s) + opt version Output version information and exit + no help Display extended usage information and exit + no more-help Extended usage information passed thru pager + opt save-opts Save the option state to a config file + Str load-opts Load options from a config file + +All arguments are named options. + +If no ``input'\'''\'' argument is provided or is set to simply "-", and if +``stdin'\'''\'' is not a ``tty'\'''\'', then the list of input files will be read from +``stdin'\'''\''. +Packaged by Bruce (2012-08-11) +Report getdefs bugs to bkorb@@gnu.org' + + +GETDEFS_DEFS_TO_GET=$@{GETDEFS_DEFS_TO_GET@} +GETDEFS_DEFS_TO_GET_set=false +export GETDEFS_DEFS_TO_GET + +if test -z "$@{GETDEFS_SUBBLOCK@}" +then + GETDEFS_SUBBLOCK_CT=0 +else + GETDEFS_SUBBLOCK_CT=1 + GETDEFS_SUBBLOCK_1=$@{GETDEFS_SUBBLOCK@} +fi +export GETDEFS_SUBBLOCK_CT +if test -z "$@{GETDEFS_LISTATTR@}" +then + GETDEFS_LISTATTR_CT=0 +else + GETDEFS_LISTATTR_CT=1 + GETDEFS_LISTATTR_1=$@{GETDEFS_LISTATTR@} +fi +export GETDEFS_LISTATTR_CT +GETDEFS_ORDERING=$@{GETDEFS_ORDERING@} +GETDEFS_ORDERING_set=false +export GETDEFS_ORDERING + +GETDEFS_FIRST_INDEX=$@{GETDEFS_FIRST_INDEX-'0'@} +GETDEFS_FIRST_INDEX_set=false +export GETDEFS_FIRST_INDEX +GETDEFS_FILELIST=$@{GETDEFS_FILELIST@} +GETDEFS_FILELIST_set=false +export GETDEFS_FILELIST + +if test -z "$@{GETDEFS_ASSIGN@}" +then + GETDEFS_ASSIGN_CT=0 +else + GETDEFS_ASSIGN_CT=1 + GETDEFS_ASSIGN_1=$@{GETDEFS_ASSIGN@} +fi +export GETDEFS_ASSIGN_CT +if test -z "$@{GETDEFS_COMMON_ASSIGN@}" +then + GETDEFS_COMMON_ASSIGN_CT=0 +else + GETDEFS_COMMON_ASSIGN_CT=1 + GETDEFS_COMMON_ASSIGN_1=$@{GETDEFS_COMMON_ASSIGN@} +fi +export GETDEFS_COMMON_ASSIGN_CT +if test -z "$@{GETDEFS_COPY@}" +then + GETDEFS_COPY_CT=0 +else + GETDEFS_COPY_CT=1 + GETDEFS_COPY_1=$@{GETDEFS_COPY@} +fi +export GETDEFS_COPY_CT +GETDEFS_SRCFILE=$@{GETDEFS_SRCFILE@} +GETDEFS_SRCFILE_set=false +export GETDEFS_SRCFILE + +GETDEFS_LINENUM=$@{GETDEFS_LINENUM@} +GETDEFS_LINENUM_set=false +export GETDEFS_LINENUM + +if test -z "$@{GETDEFS_INPUT@}" +then + GETDEFS_INPUT_CT=0 +else + GETDEFS_INPUT_CT=1 + GETDEFS_INPUT_1=$@{GETDEFS_INPUT@} +fi +export GETDEFS_INPUT_CT +GETDEFS_OUTPUT=$@{GETDEFS_OUTPUT@} +GETDEFS_OUTPUT_set=false +export GETDEFS_OUTPUT + +GETDEFS_AUTOGEN=$@{GETDEFS_AUTOGEN@} +GETDEFS_AUTOGEN_set=false +export GETDEFS_AUTOGEN + +GETDEFS_TEMPLATE=$@{GETDEFS_TEMPLATE@} +GETDEFS_TEMPLATE_set=false +export GETDEFS_TEMPLATE + +if test -z "$@{GETDEFS_AGARG@}" +then + GETDEFS_AGARG_CT=0 +else + GETDEFS_AGARG_CT=1 + GETDEFS_AGARG_1=$@{GETDEFS_AGARG@} +fi +export GETDEFS_AGARG_CT +GETDEFS_BASE_NAME=$@{GETDEFS_BASE_NAME@} +GETDEFS_BASE_NAME_set=false +export GETDEFS_BASE_NAME + +OPT_ARG=$1 +while [ $# -gt 0 ] +do + OPT_ELEMENT='' + OPT_ARG_VAL='' + OPT_ARG=$@{1@} + OPT_CODE=`echo "X$@{OPT_ARG@}"|sed 's/^X-*//'` + shift + OPT_ARG=$1 + case "$@{OPT_CODE@}" in *=* ) + OPT_ARG_VAL=`echo "$@{OPT_CODE@}"|sed 's/^[^=]*=//'` + OPT_CODE=`echo "$@{OPT_CODE@}"|sed 's/=.*$//'` ;; esac + case "$@{OPT_CODE@}" in + 'de' | \ + 'def' | \ + 'defs' | \ + 'defs-' | \ + 'defs-t' | \ + 'defs-to' | \ + 'defs-to-' | \ + 'defs-to-g' | \ + 'defs-to-ge' | \ + 'defs-to-get' ) + if [ -n "$@{GETDEFS_DEFS_TO_GET@}" ] && $@{GETDEFS_DEFS_TO_GET_set@} ; then + echo Error: duplicate DEFS_TO_GET option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_DEFS_TO_GET_set=true + OPT_NAME='DEFS_TO_GET' + OPT_ARG_NEEDED=YES + ;; + + 'su' | \ + 'sub' | \ + 'subb' | \ + 'subbl' | \ + 'subblo' | \ + 'subbloc' | \ + 'subblock' ) + GETDEFS_SUBBLOCK_CT=`expr $@{GETDEFS_SUBBLOCK_CT@} + 1` + OPT_ELEMENT="_$@{GETDEFS_SUBBLOCK_CT@}" + OPT_NAME='SUBBLOCK' + OPT_ARG_NEEDED=YES + ;; + + 'lis' | \ + 'list' | \ + 'lista' | \ + 'listat' | \ + 'listatt' | \ + 'listattr' ) + GETDEFS_LISTATTR_CT=`expr $@{GETDEFS_LISTATTR_CT@} + 1` + OPT_ELEMENT="_$@{GETDEFS_LISTATTR_CT@}" + OPT_NAME='LISTATTR' + OPT_ARG_NEEDED=YES + ;; + + 'or' | \ + 'ord' | \ + 'orde' | \ + 'order' | \ + 'orderi' | \ + 'orderin' | \ + 'ordering' ) + if [ -n "$@{GETDEFS_ORDERING@}" ] && $@{GETDEFS_ORDERING_set@} ; then + echo Error: duplicate ORDERING option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_ORDERING_set=true + OPT_NAME='ORDERING' + eval GETDEFS_ORDERING$@{OPT_ELEMENT@}=true + export GETDEFS_ORDERING$@{OPT_ELEMENT@} + OPT_ARG_NEEDED=OK + ;; + + 'no-o' | \ + 'no-or' | \ + 'no-ord' | \ + 'no-orde' | \ + 'no-order' | \ + 'no-orderi' | \ + 'no-orderin' | \ + 'no-ordering' ) + if [ -n "$@{GETDEFS_ORDERING@}" ] && $@{GETDEFS_ORDERING_set@} ; then + echo 'Error: duplicate ORDERING option' >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_ORDERING_set=true + GETDEFS_ORDERING='no' + export GETDEFS_ORDERING + OPT_NAME='ORDERING' + OPT_ARG_NEEDED=NO + ;; + + 'fir' | \ + 'firs' | \ + 'first' | \ + 'first-' | \ + 'first-i' | \ + 'first-in' | \ + 'first-ind' | \ + 'first-inde' | \ + 'first-index' ) + if [ -n "$@{GETDEFS_FIRST_INDEX@}" ] && $@{GETDEFS_FIRST_INDEX_set@} ; then + echo Error: duplicate FIRST_INDEX option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_FIRST_INDEX_set=true + OPT_NAME='FIRST_INDEX' + OPT_ARG_NEEDED=YES + ;; + + 'fil' | \ + 'file' | \ + 'filel' | \ + 'fileli' | \ + 'filelis' | \ + 'filelist' ) + if [ -n "$@{GETDEFS_FILELIST@}" ] && $@{GETDEFS_FILELIST_set@} ; then + echo Error: duplicate FILELIST option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_FILELIST_set=true + OPT_NAME='FILELIST' + eval GETDEFS_FILELIST$@{OPT_ELEMENT@}=true + export GETDEFS_FILELIST$@{OPT_ELEMENT@} + OPT_ARG_NEEDED=OK + ;; + + 'as' | \ + 'ass' | \ + 'assi' | \ + 'assig' | \ + 'assign' ) + GETDEFS_ASSIGN_CT=`expr $@{GETDEFS_ASSIGN_CT@} + 1` + OPT_ELEMENT="_$@{GETDEFS_ASSIGN_CT@}" + OPT_NAME='ASSIGN' + OPT_ARG_NEEDED=YES + ;; + + 'com' | \ + 'comm' | \ + 'commo' | \ + 'common' | \ + 'common-' | \ + 'common-a' | \ + 'common-as' | \ + 'common-ass' | \ + 'common-assi' | \ + 'common-assig' | \ + 'common-assign' ) + GETDEFS_COMMON_ASSIGN_CT=`expr $@{GETDEFS_COMMON_ASSIGN_CT@} + 1` + OPT_ELEMENT="_$@{GETDEFS_COMMON_ASSIGN_CT@}" + OPT_NAME='COMMON_ASSIGN' + OPT_ARG_NEEDED=YES + ;; + + 'cop' | \ + 'copy' ) + GETDEFS_COPY_CT=`expr $@{GETDEFS_COPY_CT@} + 1` + OPT_ELEMENT="_$@{GETDEFS_COPY_CT@}" + OPT_NAME='COPY' + OPT_ARG_NEEDED=YES + ;; + + 'sr' | \ + 'src' | \ + 'srcf' | \ + 'srcfi' | \ + 'srcfil' | \ + 'srcfile' ) + if [ -n "$@{GETDEFS_SRCFILE@}" ] && $@{GETDEFS_SRCFILE_set@} ; then + echo Error: duplicate SRCFILE option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_SRCFILE_set=true + OPT_NAME='SRCFILE' + eval GETDEFS_SRCFILE$@{OPT_ELEMENT@}=true + export GETDEFS_SRCFILE$@{OPT_ELEMENT@} + OPT_ARG_NEEDED=OK + ;; + + 'lin' | \ + 'line' | \ + 'linen' | \ + 'linenu' | \ + 'linenum' ) + if [ -n "$@{GETDEFS_LINENUM@}" ] && $@{GETDEFS_LINENUM_set@} ; then + echo Error: duplicate LINENUM option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_LINENUM_set=true + OPT_NAME='LINENUM' + eval GETDEFS_LINENUM$@{OPT_ELEMENT@}=true + export GETDEFS_LINENUM$@{OPT_ELEMENT@} + OPT_ARG_NEEDED=OK + ;; + + 'in' | \ + 'inp' | \ + 'inpu' | \ + 'input' ) + GETDEFS_INPUT_CT=`expr $@{GETDEFS_INPUT_CT@} + 1` + OPT_ELEMENT="_$@{GETDEFS_INPUT_CT@}" + OPT_NAME='INPUT' + OPT_ARG_NEEDED=YES + ;; + + 'ou' | \ + 'out' | \ + 'outp' | \ + 'outpu' | \ + 'output' ) + if [ -n "$@{GETDEFS_OUTPUT@}" ] && $@{GETDEFS_OUTPUT_set@} ; then + echo Error: duplicate OUTPUT option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_OUTPUT_set=true + OPT_NAME='OUTPUT' + OPT_ARG_NEEDED=YES + ;; + + 'au' | \ + 'aut' | \ + 'auto' | \ + 'autog' | \ + 'autoge' | \ + 'autogen' ) + if [ -n "$@{GETDEFS_AUTOGEN@}" ] && $@{GETDEFS_AUTOGEN_set@} ; then + echo Error: duplicate AUTOGEN option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_AUTOGEN_set=true + OPT_NAME='AUTOGEN' + eval GETDEFS_AUTOGEN$@{OPT_ELEMENT@}=true + export GETDEFS_AUTOGEN$@{OPT_ELEMENT@} + OPT_ARG_NEEDED=OK + ;; + + 'no-a' | \ + 'no-au' | \ + 'no-aut' | \ + 'no-auto' | \ + 'no-autog' | \ + 'no-autoge' | \ + 'no-autogen' ) + if [ -n "$@{GETDEFS_AUTOGEN@}" ] && $@{GETDEFS_AUTOGEN_set@} ; then + echo 'Error: duplicate AUTOGEN option' >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_AUTOGEN_set=true + GETDEFS_AUTOGEN='no' + export GETDEFS_AUTOGEN + OPT_NAME='AUTOGEN' + OPT_ARG_NEEDED=NO + ;; + + 'te' | \ + 'tem' | \ + 'temp' | \ + 'templ' | \ + 'templa' | \ + 'templat' | \ + 'template' ) + if [ -n "$@{GETDEFS_TEMPLATE@}" ] && $@{GETDEFS_TEMPLATE_set@} ; then + echo Error: duplicate TEMPLATE option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_TEMPLATE_set=true + OPT_NAME='TEMPLATE' + OPT_ARG_NEEDED=YES + ;; + + 'ag' | \ + 'aga' | \ + 'agar' | \ + 'agarg' ) + GETDEFS_AGARG_CT=`expr $@{GETDEFS_AGARG_CT@} + 1` + OPT_ELEMENT="_$@{GETDEFS_AGARG_CT@}" + OPT_NAME='AGARG' + OPT_ARG_NEEDED=YES + ;; + + 'ba' | \ + 'bas' | \ + 'base' | \ + 'base-' | \ + 'base-n' | \ + 'base-na' | \ + 'base-nam' | \ + 'base-name' ) + if [ -n "$@{GETDEFS_BASE_NAME@}" ] && $@{GETDEFS_BASE_NAME_set@} ; then + echo Error: duplicate BASE_NAME option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 ; fi + GETDEFS_BASE_NAME_set=true + OPT_NAME='BASE_NAME' + OPT_ARG_NEEDED=YES + ;; + + 've' | \ + 'ver' | \ + 'vers' | \ + 'versi' | \ + 'versio' | \ + 'version' ) + echo "$GETDEFS_LONGUSAGE_TEXT" + exit 0 + ;; + + 'he' | \ + 'hel' | \ + 'help' ) + echo "$GETDEFS_LONGUSAGE_TEXT" + exit 0 + ;; + + 'mo' | \ + 'mor' | \ + 'more' | \ + 'more-' | \ + 'more-h' | \ + 'more-he' | \ + 'more-hel' | \ + 'more-help' ) + echo "$GETDEFS_LONGUSAGE_TEXT" | $@{PAGER-more@} + exit 0 + ;; + + 'sa' | \ + 'sav' | \ + 'save' | \ + 'save-' | \ + 'save-o' | \ + 'save-op' | \ + 'save-opt' | \ + 'save-opts' ) + echo 'Warning: Cannot save options files' >&2 + OPT_ARG_NEEDED=OK + ;; + + 'lo' | \ + 'loa' | \ + 'load' | \ + 'load-' | \ + 'load-o' | \ + 'load-op' | \ + 'load-opt' | \ + 'load-opts' ) + echo 'Warning: Cannot load options files' >&2 + OPT_ARG_NEEDED=YES + ;; + + 'no-l' | \ + 'no-lo' | \ + 'no-loa' | \ + 'no-load' | \ + 'no-load-' | \ + 'no-load-o' | \ + 'no-load-op' | \ + 'no-load-opt' | \ + 'no-load-opts' ) + echo 'Warning: Cannot suppress the loading of options files' >&2 + OPT_ARG_NEEDED=NO + ;; + + * ) + echo Unknown option: "$@{OPT_CODE@}" >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 + ;; + esac + + case "$@{OPT_ARG_NEEDED@}" in + NO ) + OPT_ARG_VAL='' + ;; + YES ) + if [ -z "$@{OPT_ARG_VAL@}" ] + then + if [ $# -eq 0 ] + then + echo No argument provided for $@{OPT_NAME@} option >&2 + echo "$GETDEFS_USAGE_TEXT" + exit 1 + fi + OPT_ARG_VAL=$@{OPT_ARG@} + shift + OPT_ARG=$1 + fi + ;; + OK ) + if [ -z "$@{OPT_ARG_VAL@}" ] && [ $# -gt 0 ] + then + case "$@{OPT_ARG@}" in -* ) ;; * ) + OPT_ARG_VAL=$@{OPT_ARG@} + shift + OPT_ARG=$1 ;; esac + fi + ;; + esac + if [ -n "$@{OPT_ARG_VAL@}" ] + then + eval GETDEFS_$@{OPT_NAME@}$@{OPT_ELEMENT@}="'$@{OPT_ARG_VAL@}'" + export GETDEFS_$@{OPT_NAME@}$@{OPT_ELEMENT@} + fi +done +unset OPT_PROCESS || : +unset OPT_ELEMENT || : +unset OPT_ARG || : +unset OPT_ARG_NEEDED || : +unset OPT_NAME || : +unset OPT_CODE || : +unset OPT_ARG_VAL || : + +# # # # # # # # # # +# +# END OF AUTOMATED OPTION PROCESSING +# +# # # # # # # # # # -- do not modify this marker -- + +env | grep '^GETDEFS_' +@end example +@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 +@page +@node Add-Ons +@chapter Add-on packages for AutoGen + +This chapter includes several programs that either work closely +with AutoGen (extracting definitions or providing special formatting +functions), or leverage off of AutoGen technology. There is also +a formatting library that helps make AutoGen possible. + +AutoOpts ought to appear in this list as well, but since it is +the primary reason why many people would even look into AutoGen +at all, I decided to leave it in the list of chapters. + +@menu +* AutoFSM:: Automated Finite State Machine. +* AutoXDR:: Combined RPC Marshalling. +* AutoEvents:: Automated Event Management. +* columns Invocation:: Invoking columns. +* getdefs Invocation:: Invoking getdefs. +* xml2ag Invocation:: Invoking xml2ag. +* snprintfv:: The extensible format printing library. +@end menu +@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 +@page +@ignore +* * * * * * * * * * * * * * * * * +@end ignore +@include invoke-columns.texi + +@page +@ignore +* * * * * * * * * * * * * * * * * +@end ignore +@include invoke-getdefs.texi + +@page +@ignore +* * * * * * * * * * * * * * * * * +@end ignore +@include invoke-xml2ag.texi + +@page +@ignore +* * * * * * * * * * * * * * * * * +@end ignore +@include invoke-snprintfv.texi +@ignore +START == FUTURE == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore +@ignore +END == FUTURE == DO NOT CHANGE THIS COMMENT or the surrounding 'ignore's +Extraction from autogen.texi +@end ignore +@page +@node Future +@chapter Some ideas for the future. +@cindex futures + +Here are some things that might happen in the distant future. + +@itemize @bullet +@item +Fix up current tools that contain +miserably complex perl, shell, sed, awk and m4 scripts +to instead use this tool. +@end itemize +@node Copying This Manual +@appendix Copying This Manual + +You may copy this manual under the terms of the FDL +(@url{http://gnu.org/licenses/fdl.texi,the GNU Free Documentation License}). + + +@cindex FDL, GNU Free Documentation License +@center Version 1.2, November 2002 + +@display +Copyright @copyright{} 2000,2001,2002 Free Software Foundation, Inc. +51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document except +as expressly provided for under this License. Any other attempt to +copy, modify, sublicense or distribute the Document is void, and will +automatically terminate your rights under this License. However, +parties who have received copies, or rights, from you under this +License will not have their licenses terminated so long as such +parties remain in full compliance. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + copyright (c) 1992-2012 by Bruce Korb - all rights reserved + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with...Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: + +@page +@node Concept Index +@unnumbered Concept Index + +@printindex cp +@page +@node Function Index +@unnumbered Function Index + +@printindex fn +@page +@contents +@bye + |