From 7c432b265ed7ca5f8304938db73912df8ce35032 Mon Sep 17 00:00:00 2001 From: Lorry Tar Creator Date: Sat, 11 Aug 2012 16:45:31 +0000 Subject: Imported from /srv/lorry/lorry-area/autogen/autogen-5.16.2.tar.gz. --- doc/agdoc.texi | 13607 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 13607 insertions(+) create mode 100644 doc/agdoc.texi (limited to 'doc/agdoc.texi') 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 . + +@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 . + +@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) | +@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{} 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 [ ] +@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 [ ] +@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 [ ] +@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 [ ] +@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 + + + + + +@end example + +A more XML-normal form might look like this: +@example + +some alpha stuff +more beta stuff +final omega stuff + +@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 +[[ ] ] [ [ ]] +@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 +The result is the value of @code{value-name}, if defined. +Otherwise it is the empty string. + +@item +The result of the basic expression is the result of the full expression, +@xref{basic expression}. + +@item +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 % +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 ? +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 - +Evaluate @code{basic-expr} only if @code{value-name} is @i{not} defined. + +@item ?% +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 ) (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: # "" 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: # "" + +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{}_index +containg the fields: @code{@{char const * name, int const id; @};} + +@item @i{}_hash() +This is the hashing function with local only scope (static). + +@item @i{}_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{}_index} +entry. +@end table + +Use this in your template as follows where "@i{}" 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: , +, and . + +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 , and +markers are substituted. + +The third section is strictly the name of the license. +No marker substitutions are performed. + +@example +Copyright (C) , 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 + + + 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 ... + +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_} 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{$()} 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 + +@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 +[ @{ | @} ] [ ... ] +@end example + +@noindent +The syntax for @code{} 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 + [ [ = ] ... ] + +INVOKE [ [ = ] ... ] +@end example + +@item +AutoGen FOR macros must be in one of three forms: + +@example +FOR [ ] + +FOR (...Scheme expression list) + +FOR IN [ ... ] +@end example +@noindent +where: +@table @samp +@item +must be a simple name. +@item +is inserted between copies of the enclosed block. Do not try to use ``IN'' +as your separator string. It won't work. +@item +is an entry in a list of strings. ``@code{}'' 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{} +is found in the AutoGen values. The last form will create the AutoGen +value named @code{}. + +@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 +] +[+ ~~* "[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{} (@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=<> +] +@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 [ ] + +FOR (...Scheme expression list) + +FOR 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{} 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{} must be a single level name, +not a compound name (@pxref{naming values}). + +@example +[+FOR var (for-from 0) (for-to ) (for-sep ",") +] +... text with @code{var}ious substitutions ...[+ +ENDFOR var+] +@end example + +@noindent +this will repeat the @code{... text with @code{var}ious +substitutions ...} +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 +] +emit things that are for the true condition[+ + +ELIF +] +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{} 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 +] +emit things that are for the true condition[+ + +ENDWHILE +] +@end example + +@noindent +@code{} 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 + * + * what: + * general_use: + * string: + * exparg: , [, ['optional'] [, 'list']] + * doc: A long description telling people how to use + * this function. +=*/ +SCM +ag_scm_( SCM arg_name[, ...] ) +@{ @} +@end example + +@table @samp +@item gfunc +You must have this exactly thus. + +@item +This must follow C syntax for variable names + +@item +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 +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 } 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 + + +@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 +/configure [ ] +@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{/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{}'', @xref{loading rcfile}. + +@item +Config files may contain AutoOpts directives. +``@code{}'' 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 [ - [] | --[@{=| @}] ]... + + -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: .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* <>_<>_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{<>_<>_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( &<>Options, argc, argv ); + argc -= ct; + argv += ct; + @} +<> +@} +@end example + +@noindent +so you can most conveniently set the value with a ``@code{here string}'' +(@pxref{here-string}): + +@example +code = <<- _EndOfMainProc_ + <> + _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{}_@i{}} 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(tOptions* pOptions, tOptDesc* pOptDesc) +@{ + + + +@} +@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}. 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 [ - [] | --[@{=| @}] ]... + + +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{} 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( ) - Clear Option Markings +* COUNT_OPT:: COUNT_OPT( ) - Definition Count +* DESC:: DESC( ) - Option Descriptor +* DISABLE_OPT_name:: DISABLE_OPT_name - Disable an option +* ENABLED_OPT:: ENABLED_OPT( ) - Is Option Enabled? +* ERRSKIP_OPTERR:: ERRSKIP_OPTERR - Ignore Option Errors +* ERRSTOP_OPTERR:: ERRSTOP_OPTERR - Stop on Errors +* HAVE_OPT:: HAVE_OPT( ) - Have this option? +* ISSEL_OPT:: ISSEL_OPT( ) - Is Option Selected? +* ISUNUSED_OPT:: ISUNUSED_OPT( ) - Never Specified? +* OPTION_CT:: OPTION_CT - Full Count of Options +* OPT_ARG:: OPT_ARG( ) - 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( ) - Stacked Arg Count +* STACKLST_OPT:: STACKLST_OPT( ) - Argument Stack +* START_OPT:: START_OPT - Restart Option Processing +* STATE_OPT:: STATE_OPT( ) - 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( ) - Clear Option Markings +@findex CLEAR_OPT + +Make as if the option had never been specified. +@code{HAVE_OPT()} will yield @code{FALSE} +after invoking this macro. + +@node COUNT_OPT +@subsection COUNT_OPT( ) - 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( ) - 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( ) - 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( ) - 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 )) @{ + ; +@} +@end example + +@node ISSEL_OPT +@subsection ISSEL_OPT( ) - 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( ) - 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( ) - 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 ); + ; +@} +@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( ) - 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()} 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( ) - 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(