diff options
Diffstat (limited to 'doc/autogen.info-1')
| -rw-r--r-- | doc/autogen.info-1 | 7460 |
1 files changed, 7460 insertions, 0 deletions
diff --git a/doc/autogen.info-1 b/doc/autogen.info-1 new file mode 100644 index 0000000..306718c --- /dev/null +++ b/doc/autogen.info-1 @@ -0,0 +1,7460 @@ +This is autogen.info, produced by makeinfo version 4.13 from +/old-home/bkorb/ag/ag/doc//agdoc.texi. + +This manual is for GNU AutoGen version 5.16, updated August 2012. + + Copyright (C) 1992-2012 by Bruce Korb. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.2 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. + +INFO-DIR-SECTION GNU programming tools +START-INFO-DIR-ENTRY +* AutoGen: (autogen). The Automated Program Generator +END-INFO-DIR-ENTRY + + This file documents GNU AutoGen Version 5.16. + + AutoGen copyright (C) 1992-2012 Bruce Korb AutoOpts copyright (C) +1992-2012 Bruce Korb snprintfv copyright (C) 1999-2000 Gary V. Vaughan + + AutoGen is free software: you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation, either version 3 of the License, or (at your +option) any later version. + + AutoGen is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + + You should have received a copy of the GNU General Public License +along with this program. If not, see <http://www.gnu.org/licenses/>. + + +File: autogen.info, Node: Top, Next: Introduction, Up: (dir) + +The Automated Program Generator +******************************* + +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, *Note 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, *Note AutoOpts::, which also +includes stand-alone support for configuration file parsing, *Note +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 + + +File: autogen.info, Node: Introduction, Next: Definitions File, Prev: Top, Up: Top + +1 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: + + 1. The flag character in the flag string, + + 2. code to process the flag when it is encountered, + + 3. a global state variable or two, and + + 4. a line in the usage text. + +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 +*Note AutoOpts::. For a simple example of Automated Option processing, +*Note Quick Start::. For a full list of the Automated Option features, +*Note 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 + + +File: autogen.info, Node: Generalities, Next: Example Usage, Up: Introduction + +1.1 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. + + AutoGen was designed with the following features: + + 1. 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. + + 2. 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! + + 3. 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. + + 4. 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. + + 5. The template has special markers to indicate where substitutions + are required, much like the `${VAR}' construct in a shell `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. + + 6. 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 unvarying, mechanical substitution process. + + 7. 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. + + +File: autogen.info, Node: Example Usage, Next: csh/zsh caveat, Prev: Generalities, Up: Introduction + +1.2 A Simple Example +==================== + +This is just one simple example that shows a few basic features. If +you are interested, you also may run "make check" with the `VERBOSE' +environment variable set and see a number of other examples in the +`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. + +In a header file, `list.h', you define the enumeration and the global +array containing the associated strings: + + typedef enum { + IDX_ALPHA, + IDX_BETA, + IDX_OMEGA } list_enum; + + extern char const* az_name_list[ 3 ]; + +Then you also have `list.c' that defines the actual strings: + + #include "list.h" + char const* az_name_list[] = { + "some alpha stuff", + "more beta stuff", + "final omega stuff" }; + +First, we will define the information that is unique for each +enumeration name/string pair. This would be placed in a file named, +`list.def', for 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"; }; + + The `autogen definitions list;' entry defines the file as an AutoGen +definition file that uses a template named `list'. That is followed by +three `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 +`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 `list' template, so it would normally be +named, `list.tpl'. + + It looks something like this. (For a full description, *Note +Template File::.) + + [+ 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 +] + + The `[+ 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 `[+'; and the end marker is `+]'. The +template will be processed first with a suffix value of `h' and then +with `c'. Normally, the suffix values are appended to the `base-name' +to create the output file name. + + The `[+ == h +]' and `[+ == c +]' `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 `[+FOR list "," +]' and `[+ ENDFOR list +]' clauses delimit a +block of text that will be repeated for every definition of `list'. +Inside of that block, the definition name-value pairs that are members +of each `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, `[+list_info+]' will result in the value associated with the +name `list_info' being inserted between the double quotes and +`(string-upcase! (get "list_element"))' will first "get" the value +associated with the name `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 `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. + + +File: autogen.info, Node: csh/zsh caveat, Next: Testimonial, Prev: Example Usage, Up: Introduction + +1.3 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: + + 1. It handles `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. + + 2. At the beginning of each scriptlet, the command `\\cd $PWD' is + inserted. This ensures that `cd' is not aliased to something + peculiar and each scriptlet starts life in the execution directory. + + 3. At the end of each scriptlet, the command `echo mumble' is + appended. The program you use as a shell must emit the single + argument `mumble' on a line by itself. + + +File: autogen.info, Node: Testimonial, Prev: csh/zsh caveat, Up: Introduction + +1.4 A User's Perspective +======================== + +Alexandre wrote: +> +> I'd appreciate opinions from others about advantages/disadvantages of +> each of these macro packages. + + 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. + + 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| + +Sincerely, + Gary V. Vaughan + + +File: autogen.info, Node: Definitions File, Next: Template File, Prev: Introduction, Up: Top + +2 Definitions 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: + + prog-name = "autogen"; + flag = { + name = templ_dirs; + value = L; + descrip = "Template search directory list"; + }; + + 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 `#if' directive is ignored, +along with all following text through the matching `#endif' directive. +The C preprocessor is not actually invoked, so C macro substitution is +*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 + + +File: autogen.info, Node: Identification, Next: Definitions, Up: Definitions File + +2.1 The Identification Definition +================================= + +The first definition in this file is used to identify it as a AutoGen +file. It consists of the two keywords, `autogen' and `definitions' +followed by the default template name and a terminating semi-colon +(`;'). That is: + + AutoGen Definitions TEMPLATE-NAME; + +Note that, other than the name TEMPLATE-NAME, the words `AutoGen' and +`Definitions' are searched for without case sensitivity. Most lookups +in this program are case insensitive. + +Also, if the input contains more identification definitions, they will +be ignored. This is done so that you may include (*note Directives::) +other definition files without an identification conflict. + +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: + + 1. It tries to open `./TEMPLATE-NAME'. If it fails, + + 2. it tries `./TEMPLATE-NAME.tpl'. + + 3. It searches for either of these files in the directories listed in + the templ-dirs command line option. + + If AutoGen fails to find the template file in one of these places, +it prints an error message and exits. + + +File: autogen.info, Node: Definitions, Next: Index Assignments, Prev: Identification, Up: Definitions File + +2.2 Named Definitions +===================== + +A name is a sequence of characters beginning with an alphabetic +character (`a' through `z') followed by zero or more alpha-numeric +characters and/or separator characters: hyphen (`-'), underscore (`_') +or carat (`^'). 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 `[index]' or by iterating over them using the FOR (*note FOR::) +AutoGen macro on it, as described in the next chapter. Sparse arrays +are specified by specifying an index when defining an entry (*note +Assigning an Index to a Definition: Index Assignments.). + + There are two kinds of definitions, `simple' and `compound'. They +are defined thus (*note Full Syntax::): + + compound_name '=' '{' definition-list '}' ';' + + simple-name[2] '=' string ';' + + no^text^name ';' + +`simple-name' has the third index (index number 2) defined here. +`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 + + +File: autogen.info, Node: def-list, Next: double-quote-string, Up: Definitions + +2.2.1 Definition List +--------------------- + +`definition-list' is a list of definitions that may or may not contain +nested compound definitions. Any such definitions may *only* be +expanded within a `FOR' block iterating over the containing compound +definition. *Note FOR::. + + Here is, again, the example definitions from the previous chapter, +with three additional name value pairs. Two with an empty value +assigned (FIRST and LAST), and a "global" GROUP_NAME. + + 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"; }; + + +File: autogen.info, Node: double-quote-string, Next: single-quote-string, Prev: def-list, Up: Definitions + +2.2.2 Double Quote String +------------------------- + +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. `\n', `\f', `\t', etc.). `x' introduces a +two character hex 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: `"\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. + + +File: autogen.info, Node: single-quote-string, Next: simple-string, Prev: double-quote-string, Up: Definitions + +2.2.3 Single Quote String +------------------------- + +This is similar to the shell single-quote string. However, escapes `\' +are honored before another escape, single quotes `'' and hash +characters `#'. This latter is done specifically to disambiguate lines +starting with a hash character inside of a quoted string. In other +words, + + fumble = ' + #endif + '; + + could be misinterpreted by the definitions scanner, whereas this +would not: + + fumble = ' + \#endif + '; + +As with the double quote string, a series of these, even intermixed +with double quote strings, will be concatenated together. + + +File: autogen.info, Node: simple-string, Next: shell-generated, Prev: single-quote-string, Up: Definitions + +2.2.4 An Unquoted String +------------------------ + +A simple string that does not contain white space may be left unquoted. +The string must not contain any of the characters special to the +definition text (i.e., `"', `#', `'', `(', `)', `,', `;', `<', `=', +`>', `[', `]', ``', `{', or `}'). This list is subject to change, but +it will never contain underscore (`_'), period (`.'), slash (`/'), +colon (`:'), hyphen (`-') or backslash (`\\'). 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 (`autogen' or `definitions') then it is +OK to not quote it, otherwise you should. + + +File: autogen.info, Node: shell-generated, Next: scheme-generated, Prev: simple-string, Up: Definitions + +2.2.5 Shell Output String +------------------------- + +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 `cd' to the original +directory is always issued before the new command is issued. + + +File: autogen.info, Node: scheme-generated, Next: here-string, Prev: shell-generated, Up: Definitions + +2.2.6 Scheme Result String +-------------------------- + +A scheme result string must begin with an open parenthesis `('. The +scheme expression will be evaluated by Guile and the value will be the +result. The AutoGen expression functions are *dis*abled at this stage, +so do not use them. + + +File: autogen.info, Node: here-string, Next: concat-string, Prev: scheme-generated, Up: Definitions + +2.2.7 A Here String +------------------- + +A `here string' is formed in much the same way as a shell here doc. It +is denoted with two less than characters(`<<') 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: + str1 = <<- STR_END + $quotes = " ' ` + STR_END; + + str2 = << STR_END + $quotes = " ' ` + STR_END; + STR_END; + 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 `STR_END'. That `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. + + +File: autogen.info, Node: concat-string, Prev: here-string, Up: Definitions + +2.2.8 Concatenated Strings +-------------------------- + +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 *cannot* use directives to alter the string content. That +is, + + str = "fumble" + #ifdef LATER + "stumble" + #endif + ; + +will result in a syntax error. The preprocessing directives are not +carried out by the C preprocessor. However, + + str = '"fumble\n" + #ifdef LATER + " stumble\n" + #endif + '; + +*Will* work. It will enclose the `#ifdef LATER' and `#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 `\' or join them with previous lines: +`"fumble\n#ifdef LATER...'. + + +File: autogen.info, Node: Index Assignments, Next: Dynamic Text, Prev: Definitions, Up: Definitions File + +2.3 Assigning an Index to a Definition +====================================== + +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: + + mumble[9] = stumble; + mumble[0] = grumble; + +If, subsequently, you assign a value to `mumble' without an index, its +index will be `10', not `1'. If indexes are specified, they must not +cause conflicts. + + `#define'-d names may also be used for index values. This is +equivalent to the above: + + #define FIRST 0 + #define LAST 9 + mumble[LAST] = stumble; + mumble[FIRST] = grumble; + + All values in a range do *not* have to be filled in. If you leave +gaps, then you will have a sparse array. This is fine (*note FOR::). +You have your choice of iterating over all the defined values, or +iterating over a range of slots. This: + + [+ FOR mumble +][+ ENDFOR +] + +iterates over all and only the defined entries, whereas this: + + [+ FOR mumble (for-by 1) +][+ ENDFOR +] + +will iterate over all 10 "slots". Your template will likely have to +contain something like this: + + [+ IF (exist? (sprintf "mumble[%d]" (for-index))) +] + +or else "mumble" will have to be a compound value that, say, always +contains a "grumble" value: + + [+ IF (exist? "grumble") +] + + +File: autogen.info, Node: Dynamic Text, Next: Directives, Prev: Index Assignments, Up: Definitions File + +2.4 Dynamic Text +================ + +There are several methods for including dynamic content inside a +definitions file. Three of them are mentioned above (*note +shell-generated:: and *note scheme-generated::) in the discussion of +string formation rules. Another method uses the `#shell' processing +directive. It will be discussed in the next section (*note +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. + +This method can be be used as follows: + + \'( (name (value-expression)) + (name2 (another-expr)) ) + +This is entirely equivalent to: + + name = (value-expression); + name2 = (another-expr); + +Under the covers, the expression gets handed off to a Guile function +named `alist->autogen-def' in an expression that looks like this: + + (alist->autogen-def + ( (name (value-expression)) (name2 (another-expr)) ) ) + + +File: autogen.info, Node: Directives, Next: Predefines, Prev: Dynamic Text, Up: Definitions File + +2.5 Controlling What Gets Processed +=================================== + +Definition processing directives can *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 `\', or by +embedding it in the string as in `"\n#"'. + + All of the normal C preprocessing directives are recognized, though +several are ignored. There is also an additional `#shell' - +`#endshell' pair. Another minor difference is that AutoGen directives +must have the hash character (`#') in column 1. + + The final tweak is that `#!' is treated as a comment line. Using +this feature, you can use: `#! /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: `#ident', `#let', `#pragma', and `#if'. +Note that when ignoring the `#if' directive, all intervening text +through its matching `#endif' is also ignored, including the `#else' +clause. + + The AutoGen directives that affect the processing of definitions are: + +`#assert `shell-script` | (scheme-expr) | <anything else>' + If the `shell-script' or `scheme-expr' do not yield `true' valued + results, autogen will be aborted. If `<anything else>' or nothing + at all is provided, then this directive is ignored. + + When writing the shell script, remember this is on a preprocessing + line. Multiple lines must be backslash continued and the result + is a single long line. Separate multiple commands with + semi-colons. + + The result is `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"). + +`#define name [ <text> ]' + 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 *not* processed. + + After the definitions file has been processed, any remaining + entries in the define list will be added to the environment. + +`#elif' + This must follow an `#if' otherwise it will generate an error. It + will be ignored. + +`#else' + This must follow an `#if', `#ifdef' or `#ifndef'. If it follows + the `#if', then it will be ignored. Otherwise, it will change the + processing state to the reverse of what it was. + +`#endif' + This must follow an `#if', `#ifdef' or `#ifndef'. In all cases, + this will resume normal processing of text. + +`#endmac' + This terminates a "macdef", but must not ever be encountered + directly. + +`#endshell' + Ends the text processed by a command shell into autogen + definitions. + +`#error [ <descriptive text> ]' + This directive will cause AutoGen to stop processing and exit with + a status of EXIT_FAILURE. + +`#if [ <ignored conditional expression> ]' + `#if' expressions are not analyzed. *Everything* from here to the + matching `#endif' is skipped. + +`#ifdef name-to-test' + The definitions that follow, up to the matching `#endif' will be + processed only if there is a corresponding `-Dname' command line + option or if a `#define' of that name has been previously + encountered. + +`#ifndef name-to-test' + The definitions that follow, up to the matching `#endif' will be + processed only if there is *not* a corresponding `-Dname' command + line option or there was a canceling `-Uname' option. + +`#include unadorned-file-name' + 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. + +`#line' + Alters the current line number and/or file name. You may wish to + use this directive if you extract definition source from other + files. `getdefs' uses this mechanism so AutoGen will report the + correct file and approximate line number of any errors found in + extracted definitions. + +`#macdef' + This is a new AT&T research preprocessing directive. Basically, + it is a multi-line #define that may include other preprocessing + directives. + +`#option opt-name [ <text> ]' + This directive will pass the option name and associated text to the + AutoOpts optionLoadLine routine (*note 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: + + #option templ-dirs $ENVVAR/dirname + will direct autogen to use the `ENVVAR' environment variable to + find a directory named `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. + +`#shell' + Invokes `$SHELL' or `/bin/sh' on a script that should generate + AutoGen definitions. It does this using the same server process + that handles the back-quoted ``' text. *CAUTION* let not your + `$SHELL' be `csh'. + +`#undef name-to-undefine' + Will remove any entries from the define list that match the undef + name pattern. + + +File: autogen.info, Node: Predefines, Next: Comments, Prev: Directives, Up: Definitions File + +2.6 Pre-defined Names +===================== + +When AutoGen starts, it tries to determine several names from the +operating environment and put them into environment variables for use in +both `#ifdef' tests in the definitions files and in shell scripts with +environment variable tests. `__autogen__' is always defined. For +other names, AutoGen will first try to use the POSIX version of the +`sysinfo(2)' system call. Failing that, it will try for the POSIX +`uname(2)' call. If neither is available, then only "`__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, `sysinfo(2)' is available. The +following strings are used: + + * `SI_SYSNAME' (e.g., "__sunos__") + + * `SI_HOSTNAME' (e.g., "__ellen__") + + * `SI_ARCHITECTURE' (e.g., "__sparc__") + + * `SI_HW_PROVIDER' (e.g., "__sun_microsystems__") + + * `SI_PLATFORM' (e.g., "__sun_ultra_5_10__") + + * `SI_MACHINE' (e.g., "__sun4u__") + + For Linux and other operating systems that only support the +`uname(2)' call, AutoGen will use these values: + + * `sysname' (e.g., "__linux__") + + * `machine' (e.g., "__i586__") + + * `nodename' (e.g., "__bach__") + + 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 `uname(1)'. You can also segregate real C +code from autogen definitions by testing for "`__autogen__'". + + #ifdef __bach__ + location = home; + #else + location = work; + #endif + + +File: autogen.info, Node: Comments, Next: Example, Prev: Predefines, Up: Definitions File + +2.7 Commenting Your Definitions +=============================== + +The definitions file may contain C and C++ style comments. + + /* + * This is a comment. It continues for several lines and closes + * when the characters '*' and '/' appear together. + */ + // this comment is a single line comment + + +File: autogen.info, Node: Example, Next: Full Syntax, Prev: Comments, Up: Definitions File + +2.8 What it all looks like. +=========================== + +This is an extended example: + + autogen definitions `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 + + }; + + +File: autogen.info, Node: Full Syntax, Next: Alternate Definition, Prev: Example, Up: Definitions File + +2.9 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. + + 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: ] */ + + +File: autogen.info, Node: Alternate Definition, Prev: Full Syntax, Up: Definitions File + +2.10 Alternate Definition Forms +=============================== + +There are several methods for supplying data values for templates. + +`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 `--override-tpl' and + `--no-definitions' options on the command line. *Note autogen + Invocation::. + +`CGI' + AutoGen behaves as a CGI server if the definitions input is from + stdin and the environment variable `REQUEST_METHOD' is defined and + set to either "GET" or "POST", *Note AutoGen CGI::. Obviously, + all the values are constrained to strings because there is no way + to represent nested values. + +`XML' + AutoGen comes with a program named, `xml2ag'. Its output can + either be redirected to a file for later use, or the program can + be used as an AutoGen wrapper. *Note xml2ag Invocation::. + + The introductory template example (*note Example Usage::) can be + rewritten in XML as follows: + + <EXAMPLE template="list.tpl"> + <LIST list_element="alpha" + list_info="some alpha stuff"/> + <LIST list_info="more beta stuff" + list_element="beta"/> + <LIST list_element="omega" + list_info="final omega stuff"/> + </EXAMPLE> + + A more XML-normal form might look like this: + <EXAMPLE template="list.tpl"> + <LIST list_element="alpha">some alpha stuff</LIST> + <LIST list_element="beta" >more beta stuff</LIST> + <LIST list_element="omega">final omega stuff</LIST> + </EXAMPLE> + but you would have to change the template `list_info' references + into `text' references. + +`standard AutoGen definitions' + Of course. :-) + + + +File: autogen.info, Node: Template File, Next: Augmenting AutoGen, Prev: Definitions File, Up: Top + +3 Template 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. + + 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, *Note 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 + + +File: autogen.info, Node: pseudo macro, Next: naming values, Up: Template File + +3.1 Format of the Pseudo Macro +============================== + +The pseudo macro is used to tell AutoGen how to process a template. It +tells autogen: + + 1. 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. + + 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. + `{', `(', `[', or even `<' in the starting macro). It helps both + visually and with editors capable of finding a balancing + parenthesis. + + 2. That start marker must be immediately followed by the identifier + strings "AutoGen5" and then "template", though capitalization is + not important. + +The next several components may be intermingled: + + 3. 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 `stdout'. The current suffix for each pass can be + determined with the `(suffix)' scheme function (*note 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 (`.'), hyphen (`-') and underscore + (`_') 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. + + 4. 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 `CONFIG_SHELL'. This + will usually be `/bin/sh'. The shell is specified by a hash mark + (`#') followed by an exclamation mark (`!') followed by a + full-path file name (e.g. `/usr/xpg4/bin/sh' on Solaris): + [= Autogen5 Template c + #!/usr/xpg4/bin/sh + =] + + 5. Comments: blank lines, lines starting with a hash mark (`#') and + not specifying a shell, and edit mode markers (text between pairs + of `-*-' strings) are all treated as comments. + + 6. Some scheme expressions may be inserted in order to make + configuration changes before template processing begins. "before + template processing begins" means that there is no current output + file, no current suffix and, basically, none of the AutoGen + specific functions (*note 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 (*note SCM + extract::). + + (shellf "mv -f %1$s.c %1$s.sav" (base-name)) + +After these must come the end macro marker: + + 6. The punctuation characters used to demarcate the end of a macro. + Like the start marker, it must consist of seven or fewer + punctuation characters. + + 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. + + * It must not begin with a POSIX file name character (hyphen `-', + underscore `_' or period `.'), the backslash (`\') or open + parenthesis (`('). These are used to identify a suffix + specification, indicate Scheme code and trim white space. + + * If it begins with an equal sign, then it must be separated from + any suffix specification by white space. + + * The closing marker may not begin with an open parenthesis, as that + is used to enclose a scheme expression. + + * 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 (`\') before the end + macro mark, then any white space characters after the mark and + through the newline character are trimmed. + + * It is also helpful to avoid using the comment marker (`#'). It + might be seen as a comment within the pseudo macro. + + * 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. + + As an example, assume we want to use `[+' and `+]' as the start and +end macro markers, and we wish to produce a `.c' and a `.h' file, then +the pseudo macro might look something like this: + + [+ AutoGen5 template -*- Mode: emacs-mode-of-choice -*- + h=chk-%s.h + c + # make sure we don't use csh: + (setenv "SHELL" "/bin/sh") +] + + 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. + + +File: autogen.info, Node: naming values, Next: expression syntax, Prev: pseudo macro, Up: Template File + +3.2 Naming a value +================== + +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. + +It looks like this: + + comp-name-1 . comp-name-2 [ 2 ] + + Note that if there are multiple components to a name, each component +name is separated by a dot (`.'). Indexes follow a component name, +enclosed in square brackets (`[' and `]'). 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 (`.'), then the value +search is started in the current context only. Backtracking into other +definition levels is prevented. + + If someone rewrites this, I'll incorporate it. :-) + + +File: autogen.info, Node: expression syntax, Next: AutoGen Functions, Prev: naming values, Up: Template File + +3.3 Macro 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, *note 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, *Note DEFINE::. + + The syntax of a full AutoGen expression is: + + [[ <apply-code> ] <value-name> ] [ <basic-expr-1> [ <basic-expr-2> ]] + + 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 `value-name' or a `basic-expr'. + +* Menu: + +* apply code:: Apply Code +* basic expression:: Basic Expression + + +File: autogen.info, Node: apply code, Next: basic expression, Up: expression syntax + +3.3.1 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. + +`no apply code' + This is the most common expression type. Expressions of this sort + come in three flavors: + + `<value-name>' + The result is the value of `value-name', if defined. + Otherwise it is the empty string. + + `<basic-expr>' + The result of the basic expression is the result of the full + expression, *Note basic expression::. + + `<value-name> <basic-expr>' + If there is a defined value for `value-name', then the + `basic-expr' is evaluated. Otherwise, the result is the + empty string. + +`% <value-name> <basic-expr>' + If `value-name' is defined, use `basic-expr' as a format string + for sprintf. Then, if the `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 `value-name' is not defined, the + result is the empty string. + + For example, assume that `fumble' had the string value, `stumble': + [+ % fumble `printf '%%x\\n' $%s` +] + This would cause the shell to evaluate "`printf '%x\n' $stumble'". + Assuming that the shell variable `stumble' had a numeric value, + the expression result would be that number, in hex. Note the need + for doubled percent characters and backslashes. + +`? <value-name> <basic-expr-1> <basic-expr-2>' + Two `basic-expr'-s are required. If the `value-name' is defined, + then the first `basic-expr-1' is evaluated, otherwise + `basic-expr-2' is. + +`- <value-name> <basic-expr>' + Evaluate `basic-expr' only if `value-name' is not defined. + +`?% <value-name> <basic-expr-1> <basic-expr-2>' + This combines the functions of `?' and `%'. If `value-name' is + defined, it behaves exactly like `%', above, using `basic-expr-1'. + If not defined, then `basic-expr-2' is evaluated. + + For example, assume again that `fumble' had the string value, + `stumble': + [+ ?% fumble `cat $%s` `pwd` +] + This would cause the shell to evaluate "`cat $stumble'". If + `fumble' were not defined, then the result would be the name of + our current directory. + + +File: autogen.info, Node: basic expression, Prev: apply code, Up: expression syntax + +3.3.2 Basic Expression +---------------------- + +A basic expression can have one of the following forms: + +`'STRING'' + A single quoted string. Backslashes can be used to protect single + quotes (`''), hash characters (`#'), or backslashes (`\') 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. + +`"STRING"' + A double quoted string. This is a cooked text string as in C, + except that they are not concatenated with adjacent strings. + Evaluating "`STRING'" will output STRING with all backslash + sequences interpreted. + +``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 `stdout' output of the shell. + +`(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, + [+ (define my-var "some-string-value") +] + can have that string inserted later, but only as in: + [+ (. my-var) +] + + Additionally, other than in the `%' and `?%' expressions, the + Guile expressions may be introduced with the Guile comment + character (`;') 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 `(begin ...)' expression. The result + will be the result of the last Guile expression evaluated. + + +File: autogen.info, Node: AutoGen Functions, Next: Common Functions, Prev: expression syntax, Up: Template File + +3.4 AutoGen Scheme Functions +============================ + +AutoGen uses Guile to interpret Scheme expressions within AutoGen +macros. All of the normal Guile functions are available, plus several +extensions (*note 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:: `ag-fprintf' - format to autogen stream +* SCM ag-function?:: `ag-function?' - test for function +* SCM base-name:: `base-name' - base output name +* SCM chdir:: `chdir' - Change current directory +* SCM count:: `count' - definition count +* SCM def-file:: `def-file' - definitions file name +* SCM def-file-line:: `def-file-line' - get a definition file+line number +* SCM dne:: `dne' - "Do Not Edit" warning +* SCM emit:: `emit' - emit the text for each argument +* SCM emit-string-table:: `emit-string-table' - output a string table +* SCM error:: `error' - display message and exit +* SCM exist?:: `exist?' - test for value name +* SCM find-file:: `find-file' - locate a file in the search path +* SCM first-for?:: `first-for?' - detect first iteration +* SCM for-by:: `for-by' - set iteration step +* SCM for-from:: `for-from' - set initial index +* SCM for-index:: `for-index' - get current loop index +* SCM for-sep:: `for-sep' - set loop separation string +* SCM for-to:: `for-to' - set ending index +* SCM get:: `get' - get named value +* SCM get-c-name:: `get-c-name' - get named value, mapped to C name syntax +* SCM get-down-name:: `get-down-name' - get lower cased named value, mapped to C name syntax +* SCM get-up-name:: `get-up-name' - get upper cased named value, mapped to C name syntax +* SCM high-lim:: `high-lim' - get highest value index +* SCM last-for?:: `last-for?' - detect last iteration +* SCM len:: `len' - get count of values +* SCM low-lim:: `low-lim' - get lowest value index +* SCM make-header-guard:: `make-header-guard' - make self-inclusion guard +* SCM make-tmp-dir:: `make-tmp-dir' - create a temporary directory +* SCM match-value?:: `match-value?' - test for matching value +* SCM out-delete:: `out-delete' - delete current output file +* SCM out-depth:: `out-depth' - output file stack depth +* SCM out-emit-suspended:: `out-emit-suspended' - emit the text of suspended output +* SCM out-line:: `out-line' - output file line number +* SCM out-move:: `out-move' - change name of output file +* SCM out-name:: `out-name' - current output file name +* SCM out-pop:: `out-pop' - close current output file +* SCM out-push-add:: `out-push-add' - append output to file +* SCM out-push-new:: `out-push-new' - purge and create output file +* SCM out-resume:: `out-resume' - resume suspended output file +* SCM out-suspend:: `out-suspend' - suspend current output file +* SCM out-switch:: `out-switch' - close and create new output +* SCM output-file-next-line:: `output-file-next-line' - print the file name and next line number +* SCM set-option:: `set-option' - Set a command line option +* SCM set-writable:: `set-writable' - Make the output file be writable +* SCM stack:: `stack' - make list of AutoGen values +* SCM stack-join:: `stack-join' - stack values then join them +* SCM suffix:: `suffix' - get the current suffix +* SCM tpl-file:: `tpl-file' - get the template file name +* SCM tpl-file-line:: `tpl-file-line' - get the template file+line number +* SCM tpl-file-next-line:: `tpl-file-next-line' - get the template file plus next line number +* SCM autogen-version:: `autogen-version' - ``5.16.2'' +* SCM c-file-line-fmt:: format file info as, ```#line nn "file"''' + + +File: autogen.info, Node: SCM ag-fprintf, Next: SCM ag-function?, Up: AutoGen Functions + +3.4.1 `ag-fprintf' - format to autogen stream +--------------------------------------------- + +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 (*note SCM out-suspend::) or an index into the output stack +(*note SCM out-push-new::). `(ag-fprintf 0 ...)' is equivalent to +`(emit (sprintf ...))', and `(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 + + +File: autogen.info, Node: SCM ag-function?, Next: SCM base-name, Prev: SCM ag-fprintf, Up: AutoGen Functions + +3.4.2 `ag-function?' - test for function +---------------------------------------- + +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 + + +File: autogen.info, Node: SCM base-name, Next: SCM chdir, Prev: SCM ag-function?, Up: AutoGen Functions + +3.4.3 `base-name' - base output name +------------------------------------ + +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. + + +File: autogen.info, Node: SCM chdir, Next: SCM count, Prev: SCM base-name, Up: AutoGen Functions + +3.4.4 `chdir' - Change current directory +---------------------------------------- + +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 + + +File: autogen.info, Node: SCM count, Next: SCM def-file, Prev: SCM chdir, Up: AutoGen Functions + +3.4.5 `count' - definition count +-------------------------------- + +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 + + +File: autogen.info, Node: SCM def-file, Next: SCM def-file-line, Prev: SCM count, Up: AutoGen Functions + +3.4.6 `def-file' - definitions file name +---------------------------------------- + +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. + + +File: autogen.info, Node: SCM def-file-line, Next: SCM dne, Prev: SCM def-file, Up: AutoGen Functions + +3.4.7 `def-file-line' - get a definition file+line number +--------------------------------------------------------- + +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 *Note SCM +c-file-line-fmt::. You may use it thus: + + (def-file-line "ag-def-name" c-file-line-fmt) + + It is also safe to use the formatting string, "%2$d". AutoGen uses +an argument vector version of printf: *Note snprintfv::. + + Arguments: +ag-name - name of AutoGen value +msg-fmt - Optional - formatting for line message + + +File: autogen.info, Node: SCM dne, Next: SCM emit, Prev: SCM def-file-line, Up: AutoGen Functions + +3.4.8 `dne' - "Do Not Edit" warning +----------------------------------- + +Usage: (dne prefix [ first_prefix ] [ optpfx ]) +Generate a "DO NOT EDIT" or "EDIT WITH CARE" warning string. Which +depends on whether or not the `--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. + -*- buffer-read-only: t -*- vi: set ro: +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, "`-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 + + +File: autogen.info, Node: SCM emit, Next: SCM emit-string-table, Prev: SCM dne, Up: AutoGen Functions + +3.4.9 `emit' - emit the text for each argument +---------------------------------------------- + +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 + + +File: autogen.info, Node: SCM emit-string-table, Next: SCM error, Prev: SCM emit, Up: AutoGen Functions + +3.4.10 `emit-string-table' - output a string table +-------------------------------------------------- + +Usage: (emit-string-table st-name) +Emit into the current output stream a `static char const' array named +`st-name' that will have `NUL' bytes between each inserted string. + + Arguments: +st-name - the name of the array of characters + + +File: autogen.info, Node: SCM error, Next: SCM exist?, Prev: SCM emit-string-table, Up: AutoGen Functions + +3.4.11 `error' - display message and exit +----------------------------------------- + +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: + + DEFINITIONS ERROR in %s line %d for %s: %s\n + + 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 + + +File: autogen.info, Node: SCM exist?, Next: SCM find-file, Prev: SCM error, Up: AutoGen Functions + +3.4.12 `exist?' - test for value name +------------------------------------- + +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: + (exist? "foo[3].bar.baz") + will yield true if all of the following is true: +There is a member value of either group or string type named `baz' for +some group value `bar' that is a member of the `foo' group with index +`3'. There may be multiple entries of `bar' within `foo', only one +needs to contain a value for `baz'. + + Arguments: +ag-name - name of AutoGen value + + +File: autogen.info, Node: SCM find-file, Next: SCM first-for?, Prev: SCM exist?, Up: AutoGen Functions + +3.4.13 `find-file' - locate a file in the search path +----------------------------------------------------- + +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-name', both +with and without the `.suffix', if provided. + + Arguments: +file-name - name of file with text +suffix - Optional - file suffix to try, too + + +File: autogen.info, Node: SCM first-for?, Next: SCM for-by, Prev: SCM find-file, Up: AutoGen Functions + +3.4.14 `first-for?' - detect first iteration +-------------------------------------------- + +Usage: (first-for? [ for_var ]) +Returns `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 `FOR' loop, it returns `SCM_UNDEFINED', *note FOR::. + + Arguments: +for_var - Optional - which for loop + + +File: autogen.info, Node: SCM for-by, Next: SCM for-from, Prev: SCM first-for?, Up: AutoGen Functions + +3.4.15 `for-by' - set iteration step +------------------------------------ + +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. *Note FOR::. + + Arguments: +by - the iteration increment for the AutoGen FOR macro + + +File: autogen.info, Node: SCM for-from, Next: SCM for-index, Prev: SCM for-by, Up: AutoGen Functions + +3.4.16 `for-from' - set initial index +------------------------------------- + +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. *Note FOR::. + + Arguments: +from - the initial index for the AutoGen FOR macro + + +File: autogen.info, Node: SCM for-index, Next: SCM for-sep, Prev: SCM for-from, Up: AutoGen Functions + +3.4.17 `for-index' - get current loop index +------------------------------------------- + +Usage: (for-index [ for_var ]) +Returns the current index for the named `FOR' loop. If not named, then +the index for the innermost loop. Outside of any FOR loop, it returns +`SCM_UNDEFINED', *Note FOR::. + + Arguments: +for_var - Optional - which for loop + + +File: autogen.info, Node: SCM for-sep, Next: SCM for-to, Prev: SCM for-index, Up: AutoGen Functions + +3.4.18 `for-sep' - set loop separation string +--------------------------------------------- + +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 + + +File: autogen.info, Node: SCM for-to, Next: SCM get, Prev: SCM for-sep, Up: AutoGen Functions + +3.4.19 `for-to' - set ending index +---------------------------------- + +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. *Note FOR::. + + Arguments: +to - the final index for the AutoGen FOR macro + + +File: autogen.info, Node: SCM get, Next: SCM get-c-name, Prev: SCM for-to, Up: AutoGen Functions + +3.4.20 `get' - get named value +------------------------------ + +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 + + +File: autogen.info, Node: SCM get-c-name, Next: SCM get-down-name, Prev: SCM get, Up: AutoGen Functions + +3.4.21 `get-c-name' - get named value, mapped to C name syntax +-------------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM get-down-name, Next: SCM get-up-name, Prev: SCM get-c-name, Up: AutoGen Functions + +3.4.22 `get-down-name' - get lower cased named value, mapped to C name syntax +----------------------------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM get-up-name, Next: SCM high-lim, Prev: SCM get-down-name, Up: AutoGen Functions + +3.4.23 `get-up-name' - get upper cased named value, mapped to C name syntax +--------------------------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM high-lim, Next: SCM last-for?, Prev: SCM get-up-name, Up: AutoGen Functions + +3.4.24 `high-lim' - get highest value index +------------------------------------------- + +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 `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: + + tMyStruct myVals[ [+ (+ 1 (high-lim "my-val-list")) +] ]; + + Arguments: +ag-name - name of AutoGen value + + +File: autogen.info, Node: SCM last-for?, Next: SCM len, Prev: SCM high-lim, Up: AutoGen Functions + +3.4.25 `last-for?' - detect last iteration +------------------------------------------ + +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. *Note FOR::. + + Arguments: +for_var - Optional - which for loop + + +File: autogen.info, Node: SCM len, Next: SCM low-lim, Prev: SCM last-for?, Up: AutoGen Functions + +3.4.26 `len' - get count of values +---------------------------------- + +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 `(string-length (get "ag-name"))'. + + Arguments: +ag-name - name of AutoGen value + + +File: autogen.info, Node: SCM low-lim, Next: SCM make-header-guard, Prev: SCM len, Up: AutoGen Functions + +3.4.27 `low-lim' - get lowest value index +----------------------------------------- + +Usage: (low-lim ag-name) +Returns the lowest index associated with an array of definitions. + + Arguments: +ag-name - name of AutoGen value + + +File: autogen.info, Node: SCM make-header-guard, Next: SCM make-tmp-dir, Prev: SCM low-lim, Up: AutoGen Functions + +3.4.28 `make-header-guard' - make self-inclusion guard +------------------------------------------------------ + +Usage: (make-header-guard name) +This function will create a `#ifndef'/`#define' sequence for protecting +a header from multiple evaluation. It will also set the Scheme +variable `header-file' to the name of the file being protected and it +will set `header-guard' to the name of the `#define' being used to +protect it. It is expected that this will be used as follows: + [+ (make-header-guard "group_name") +] + ... + #endif /* [+ (. header-guard) +] */ + + #include "[+ (. header-file) +]" + The `#define' name is composed as follows: + + 1. The first element is the string argument and a separating + underscore. + + 2. That is followed by the name of the header file with illegal + characters mapped to underscores. + + 3. The end of the name is always, "`_GUARD'". + + 4. Finally, the entire string is mapped to upper case. + + The final `#define' name is stored in an SCM symbol named +`header-guard'. Consequently, the concluding `#endif' for the file +should read something like: + + #endif /* [+ (. header-guard) +] */ + + The name of the header file (the current output file) is also stored +in an SCM symbol, `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: + + #include "[+ (. header-file) +]" + + 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 + + +File: autogen.info, Node: SCM make-tmp-dir, Next: SCM match-value?, Prev: SCM make-header-guard, Up: AutoGen Functions + +3.4.29 `make-tmp-dir' - create a temporary directory +---------------------------------------------------- + +Usage: (make-tmp-dir) +Create a directory that will be cleaned up upon exit. + + This Scheme function takes no arguments. + + +File: autogen.info, Node: SCM match-value?, Next: SCM out-delete, Prev: SCM make-tmp-dir, Up: AutoGen Functions + +3.4.30 `match-value?' - test for matching value +----------------------------------------------- + +Usage: (match-value? op ag-name test-str) +This function answers the question, "Is there an AutoGen value named +`ag-name' with a value that matches the pattern `test-str' using the +match function `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 `ag-name' argument for +`exist?' (*note SCM exist?::). + + Arguments: +op - boolean result operator +ag-name - name of AutoGen value +test-str - string to test against + + +File: autogen.info, Node: SCM out-delete, Next: SCM out-depth, Prev: SCM match-value?, Up: AutoGen Functions + +3.4.31 `out-delete' - delete current output file +------------------------------------------------ + +Usage: (out-delete) +Remove the current output file. Cease processing the template for the +current suffix. It is an error if there are `push'-ed output files. +Use the `(error "0")' scheme function instead. *Note output controls::. + + This Scheme function takes no arguments. + + +File: autogen.info, Node: SCM out-depth, Next: SCM out-emit-suspended, Prev: SCM out-delete, Up: AutoGen Functions + +3.4.32 `out-depth' - output file stack depth +-------------------------------------------- + +Usage: (out-depth) +Returns the depth of the output file stack. *Note output controls::. + + This Scheme function takes no arguments. + + +File: autogen.info, Node: SCM out-emit-suspended, Next: SCM out-line, Prev: SCM out-depth, Up: AutoGen Functions + +3.4.33 `out-emit-suspended' - emit the text of suspended output +--------------------------------------------------------------- + +Usage: (out-emit-suspended susp_nm) +This function is equivalent to `(begin (out-resume <name>) (out-pop +#t))' + + Arguments: +susp_nm - A name tag of suspended output + + +File: autogen.info, Node: SCM out-line, Next: SCM out-move, Prev: SCM out-emit-suspended, Up: AutoGen Functions + +3.4.34 `out-line' - output file line number +------------------------------------------- + +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. + + +File: autogen.info, Node: SCM out-move, Next: SCM out-name, Prev: SCM out-line, Up: AutoGen Functions + +3.4.35 `out-move' - change name of output file +---------------------------------------------- + +Usage: (out-move new-name) +Rename current output file. *Note output controls::. Please note: +changing the name will not save a temporary file from being deleted. +It may, however, be used on the root output file. + + Arguments: +new-name - new name for the current output file + + +File: autogen.info, Node: SCM out-name, Next: SCM out-pop, Prev: SCM out-move, Up: AutoGen Functions + +3.4.36 `out-name' - current output file name +-------------------------------------------- + +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. *Note output controls::. + + This Scheme function takes no arguments. + + +File: autogen.info, Node: SCM out-pop, Next: SCM out-push-add, Prev: SCM out-name, Up: AutoGen Functions + +3.4.37 `out-pop' - close current output file +-------------------------------------------- + +Usage: (out-pop [ disp ]) +If there has been a `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 `push'. *Note output controls::. + + If there is no argument, no further action is taken. Otherwise, the +argument should be `#t' and the contents of the file are returned by +the function. + + Arguments: +disp - Optional - return contents of the file + + +File: autogen.info, Node: SCM out-push-add, Next: SCM out-push-new, Prev: SCM out-pop, Up: AutoGen Functions + +3.4.38 `out-push-add' - append output to file +--------------------------------------------- + +Usage: (out-push-add file-name) +Identical to `push-new', except the contents are *not* purged, but +appended to. *Note output controls::. + + Arguments: +file-name - name of the file to append text to + + +File: autogen.info, Node: SCM out-push-new, Next: SCM out-resume, Prev: SCM out-push-add, Up: AutoGen Functions + +3.4.39 `out-push-new' - purge and create output file +---------------------------------------------------- + +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 `pop' `delete' or `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. *Note output +controls::. + + Arguments: +file-name - Optional - name of the file to create + + +File: autogen.info, Node: SCM out-resume, Next: SCM out-suspend, Prev: SCM out-push-new, Up: AutoGen Functions + +3.4.40 `out-resume' - resume suspended output file +-------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM out-suspend, Next: SCM out-switch, Prev: SCM out-resume, Up: AutoGen Functions + +3.4.41 `out-suspend' - suspend current output file +-------------------------------------------------- + +Usage: (out-suspend suspName) +If there has been a `push' on the output, then set aside the output +descriptor for later reactiviation with `(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 + + +File: autogen.info, Node: SCM out-switch, Next: SCM output-file-next-line, Prev: SCM out-suspend, Up: AutoGen Functions + +3.4.42 `out-switch' - close and create new output +------------------------------------------------- + +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 `out-pop' +followed by `out-push-new', except that you may not pop the base level +output file, but you may `switch' it. *Note output controls::. + + Arguments: +file-name - name of the file to create + + +File: autogen.info, Node: SCM output-file-next-line, Next: SCM set-option, Prev: SCM out-switch, Up: AutoGen Functions + +3.4.43 `output-file-next-line' - print the file name and next line number +------------------------------------------------------------------------- + +Usage: (output-file-next-line [ line_off ] [ alt_fmt ]) +Returns a string with the current output file name and line number. +The default format is: # <line+1> "<output-file-name>" The argument may +be either a number indicating an offset from the current output line +number or an alternate formatting string. If both are provided, then +the first must be a numeric offset. + + Be careful that you are directing output to the final output file. +Otherwise, you will get the file name and line number of the temporary +file. That won't be what you want. + + Arguments: +line_off - Optional - offset to line number +alt_fmt - Optional - alternate format string + + +File: autogen.info, Node: SCM set-option, Next: SCM set-writable, Prev: SCM output-file-next-line, Up: AutoGen Functions + +3.4.44 `set-option' - Set a command line option +----------------------------------------------- + +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 + + +File: autogen.info, Node: SCM set-writable, Next: SCM stack, Prev: SCM set-option, Up: AutoGen Functions + +3.4.45 `set-writable' - Make the output file be writable +-------------------------------------------------------- + +Usage: (set-writable [ set? ]) +This function will set the current output file to be writable (or not). +This is only effective if neither the `--writable' nor `--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 + + +File: autogen.info, Node: SCM stack, Next: SCM stack-join, Prev: SCM set-writable, Up: AutoGen Functions + +3.4.46 `stack' - make list of AutoGen values +-------------------------------------------- + +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 + + +File: autogen.info, Node: SCM stack-join, Next: SCM suffix, Prev: SCM stack, Up: AutoGen Functions + +3.4.47 `stack-join' - stack values then join them +------------------------------------------------- + +Usage: (stack-join join ag-name) +This function will collect all the values named `ag-name' (see the +*note stack function: SCM stack.) and join them separated by the `join' +string (see the *note join function: SCM join.). + + Arguments: +join - string between each element +ag-name - name of autogen values to stack + + +File: autogen.info, Node: SCM suffix, Next: SCM tpl-file, Prev: SCM stack-join, Up: AutoGen Functions + +3.4.48 `suffix' - get the current suffix +---------------------------------------- + +Usage: (suffix) +Returns the current active suffix (*note pseudo macro::). + + This Scheme function takes no arguments. + + +File: autogen.info, Node: SCM tpl-file, Next: SCM tpl-file-line, Prev: SCM suffix, Up: AutoGen Functions + +3.4.49 `tpl-file' - get the template file name +---------------------------------------------- + +Usage: (tpl-file [ full_path ]) +Returns the name of the current template file. If `#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 + + +File: autogen.info, Node: SCM tpl-file-line, Next: SCM tpl-file-next-line, Prev: SCM tpl-file, Up: AutoGen Functions + +3.4.50 `tpl-file-line' - get the template file+line number +---------------------------------------------------------- + +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 *Note SCM +c-file-line-fmt::. You may use it thus: + (tpl-file-line c-file-line-fmt) + + It is also safe to use the formatting string, "%2$d". AutoGen uses +an argument vector version of printf: *Note 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 + + +File: autogen.info, Node: SCM tpl-file-next-line, Next: SCM autogen-version, Prev: SCM tpl-file-line, Up: AutoGen Functions + +3.4.51 `tpl-file-next-line' - get the template file plus next line number +------------------------------------------------------------------------- + +Usage: (tpl-file-next-line [ msg-fmt ]) +This is almost the same as *Note SCM tpl-file-line::, except that the +line referenced is the next line, per C compiler conventions, and +consequently defaults to the format: # <line-no+1> "<file-name>" + + Arguments: +msg-fmt - Optional - formatting for line message + + +File: autogen.info, Node: SCM autogen-version, Next: SCM c-file-line-fmt, Prev: SCM tpl-file-next-line, Up: AutoGen Functions + +3.4.52 `autogen-version' - autogen version number +------------------------------------------------- + +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". + + +File: autogen.info, Node: SCM c-file-line-fmt, Prev: SCM autogen-version, Up: AutoGen Functions + +3.4.53 format file info as, "`#line nn "file"'" +----------------------------------------------- + +This is a symbol that can easily be used with the functions *Note SCM +tpl-file-line::, and *Note SCM def-file-line::. These will emit C +program `#line' directives pointing to template and definitions text, +respectively. + + +File: autogen.info, Node: Common Functions, Next: native macros, Prev: AutoGen Functions, Up: Template File + +3.5 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 (*note AutoGen Functions::), +these functions are available for direct use during definition load +time. The equality test (*note 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:: `agpl' - GNU Affero General Public License +* SCM bsd:: `bsd' - BSD Public License +* SCM c-string:: `c-string' - emit string for ANSI C +* SCM error-source-line:: `error-source-line' - display of file & line +* SCM extract:: `extract' - extract text from another file +* SCM format-arg-count:: `format-arg-count' - count the args to a format +* SCM fprintf:: `fprintf' - format to a file +* SCM gperf:: `gperf' - perform a perfect hash function +* SCM gperf-code:: `gperf-code' - emit the source of the generated gperf program +* SCM gpl:: `gpl' - GNU General Public License +* SCM hide-email:: `hide-email' - convert eaddr to javascript +* SCM html-escape-encode:: `html-escape-encode' - encode html special characters +* SCM in?:: `in?' - test for string in list +* SCM join:: `join' - join string list with separator +* SCM kr-string:: `kr-string' - emit string for K&R C +* SCM lgpl:: `lgpl' - GNU Library General Public License +* SCM license:: `license' - an arbitrary license +* SCM license-description:: `license-description' - Emit a license description +* SCM license-full:: `license-full' - Emit the licensing information and description +* SCM license-info:: `license-info' - Emit the licensing information and copyright years +* SCM license-name:: `license-name' - Emit the name of the license +* SCM make-gperf:: `make-gperf' - build a perfect hash function program +* SCM makefile-script:: `makefile-script' - create makefile script +* SCM max:: `max' - maximum value in list +* SCM min:: `min' - minimum value in list +* SCM prefix:: `prefix' - prefix lines with a string +* SCM printf:: `printf' - format to stdout +* SCM raw-shell-str:: `raw-shell-str' - single quote shell string +* SCM shell:: `shell' - invoke a shell script +* SCM shell-str:: `shell-str' - double quote shell string +* SCM shellf:: `shellf' - format a string, run shell +* SCM sprintf:: `sprintf' - format a string +* SCM string-capitalize:: `string-capitalize' - capitalize a new string +* SCM string-capitalize!:: `string-capitalize!' - capitalize a string +* SCM *=*:: `string-contains-eqv?' - caseless substring +* SCM *==*:: `string-contains?' - substring match +* SCM string-downcase:: `string-downcase' - lower case a new string +* SCM string-downcase!:: `string-downcase!' - make a string be lower case +* SCM *~:: `string-end-eqv-match?' - caseless regex ending +* SCM *~~:: `string-end-match?' - regex match end +* SCM *=:: `string-ends-eqv?' - caseless string ending +* SCM *==:: `string-ends-with?' - string ending +* SCM ==:: `string-equals?' - string matching +* SCM ~:: `string-eqv-match?' - caseless regex match +* SCM =:: `string-eqv?' - caseless match +* SCM *~*:: `string-has-eqv-match?' - caseless regex contains +* SCM *~~*:: `string-has-match?' - contained regex match +* SCM ~~:: `string-match?' - regex match +* SCM ~*:: `string-start-eqv-match?' - caseless regex start +* SCM ~~*:: `string-start-match?' - regex match start +* SCM =*:: `string-starts-eqv?' - caseless string start +* SCM ==*:: `string-starts-with?' - string starting +* SCM string-substitute:: `string-substitute' - multiple global replacements +* SCM string-table-add:: `string-table-add' - Add an entry to a string table +* SCM string-table-add-ref:: `string-table-add-ref' - Add an entry to a string table, get reference +* SCM string-table-new:: `string-table-new' - create a string table +* SCM string-table-size:: `string-table-size' - print the current size of a string table +* SCM string->c-name!:: `string->c-name!' - map non-name chars to underscore +* SCM string->camelcase:: `string->camelcase' - make a string be CamelCase +* SCM string-tr:: `string-tr' - convert characters with new result +* SCM string-tr!:: `string-tr!' - convert characters +* SCM string-upcase:: `string-upcase' - upper case a new string +* SCM string-upcase!:: `string-upcase!' - make a string be upper case +* SCM sub-shell-str:: `sub-shell-str' - back quoted (sub-)shell string +* SCM sum:: `sum' - sum of values in list +* SCM time-string->number:: `time-string->number' - duration string to seconds +* SCM version-compare:: `version-compare' - compare two version numbers + + +File: autogen.info, Node: SCM agpl, Next: SCM bsd, Up: Common Functions + +3.5.1 `agpl' - GNU Affero General Public License +------------------------------------------------ + +Usage: (agpl prog-name prefix) +Emit a string that contains the GNU Affero General Public License. +This function is now deprecated. Please *Note SCM +license-description::. + + Arguments: +prog-name - name of the program under the GPL +prefix - String for starting each output line + + +File: autogen.info, Node: SCM bsd, Next: SCM c-string, Prev: SCM agpl, Up: Common Functions + +3.5.2 `bsd' - BSD Public License +-------------------------------- + +Usage: (bsd prog_name owner prefix) +Emit a string that contains the Free BSD Public License. This function +is now deprecated. Please *Note 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 + + +File: autogen.info, Node: SCM c-string, Next: SCM error-source-line, Prev: SCM bsd, Up: Common Functions + +3.5.3 `c-string' - emit string for ANSI C +----------------------------------------- + +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 `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 `kr-string' for that compiler. + + Arguments: +string - string to reformat + + +File: autogen.info, Node: SCM error-source-line, Next: SCM extract, Prev: SCM c-string, Up: Common Functions + +3.5.4 `error-source-line' - display of file & line +-------------------------------------------------- + +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. + + +File: autogen.info, Node: SCM extract, Next: SCM format-arg-count, Prev: SCM error-source-line, Up: Common Functions + +3.5.5 `extract' - extract text from another file +------------------------------------------------ + +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: + + * The `file-name' argument is used to name the file that contains + the demarcated text. + + * The `marker-fmt' is a formatting string that is used to construct + the starting and ending demarcation strings. The sprintf function + is given the `marker-fmt' with two arguments. The first is either + "START" or "END". The second is either "DO NOT CHANGE THIS + COMMENT" or the optional `caveat' argument. + + * `caveat' is presumed to be absent if it is the empty string + (`""'). If absent, "DO NOT CHANGE THIS COMMENT" is used as the + second string argument to the `marker-fmt'. + + * When a `default' argument is supplied and no pre-existing text is + found, then this text will be inserted between the START and END + markers. + +The resulting strings are presumed to be unique within the subject +file. As a simplified example: + + [+ (extract "fname" "// %s - SOMETHING - %s" "" + "example default") +] + will result in the following text being inserted into the output: + + // START - SOMETHING - DO NOT CHANGE THIS COMMENT + example default + // END - SOMETHING - DO NOT CHANGE THIS COMMENT + +The "`example default'" string can then be carried forward to the next +generation of the output, *provided* the output is not named "`fname'" +and the old output is renamed to "`fname'" before AutoGen-eration +begins. + +*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: + + [+ 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)) + +] + + 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. + +*also NB:* + This function presumes that the output file ought to be editable so + that the code between the `START' and `END' marks can be edited by + the template user. Consequently, when the `(extract ...)' function + is invoked, if the `writable' option has not been specified, then + it will be set at that point. If this is not the desired + behavior, the `--not-writable' command line option will override + this. Also, you may use the guile function `(chmod "file" + mode-value)' to override whatever AutoGen is using for the result + mode. + + 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 + + +File: autogen.info, Node: SCM format-arg-count, Next: SCM fprintf, Prev: SCM extract, Up: Common Functions + +3.5.6 `format-arg-count' - count the args to a format +----------------------------------------------------- + +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: + + /*=fumble bumble + * fmt: 'stumble %s: %d\n' + =*/ + +You may wish to generate a macro: + + #define BUMBLE(a1,a2) printf_like(something,(a1),(a2)) + +You can do this by knowing that the format needs two arguments. + + Arguments: +format - formatting string + + +File: autogen.info, Node: SCM fprintf, Next: SCM gperf, Prev: SCM format-arg-count, Up: Common Functions + +3.5.7 `fprintf' - format to a file +---------------------------------- + +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 + + +File: autogen.info, Node: SCM gperf, Next: SCM gperf-code, Prev: SCM fprintf, Up: Common Functions + +3.5.8 `gperf' - perform a perfect hash function +----------------------------------------------- + +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 `make-gperf' +function *Note SCM make-gperf::. The `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 `make-gperf' string list. The result +will be a perfect hash index. + + See the documentation for `gperf(1GNU)' for more details. + + Arguments: +name - name of hash list +str - string to hash + + +File: autogen.info, Node: SCM gperf-code, Next: SCM gpl, Prev: SCM gperf, Up: Common Functions + +3.5.9 `gperf-code' - emit the source of the generated gperf program +------------------------------------------------------------------- + +Usage: (gperf-code st-name) +Returns the contents of the emitted code, suitable for inclusion in +another program. The interface contains the following elements: + +`struct <st-name>_index' + containg the fields: `{char const * name, int const id; };' + +`<st-name>_hash()' + This is the hashing function with local only scope (static). + +`<st-name>_find()' + This is the searching and validation function. The first argument + is the string to look up, the second is its length. It returns a + pointer to the corresponding `<st-name>_index' entry. + + Use this in your template as follows where "<st-name>" was set to be +"`lookup'": + + [+ (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); + + Arguments: +st-name - the name of the gperf hash list + + +File: autogen.info, Node: SCM gpl, Next: SCM hide-email, Prev: SCM gperf-code, Up: Common Functions + +3.5.10 `gpl' - GNU General Public License +----------------------------------------- + +Usage: (gpl prog-name prefix) +Emit a string that contains the GNU General Public License. This +function is now deprecated. Please *Note SCM license-description::. + + Arguments: +prog-name - name of the program under the GPL +prefix - String for starting each output line + + +File: autogen.info, Node: SCM hide-email, Next: SCM html-escape-encode, Prev: SCM gpl, Up: Common Functions + +3.5.11 `hide-email' - convert eaddr to javascript +------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM html-escape-encode, Next: SCM in?, Prev: SCM hide-email, Up: Common Functions + +3.5.12 `html-escape-encode' - encode html special characters +------------------------------------------------------------ + +Usage: (html-escape-encode str) +This function will replace replace the characters `'&'', `'<'' and +`'>'' characters with the HTML/XML escape-encoded strings (`"&"', +`"<"', and `">"', respectively). + + Arguments: +str - string to make substitutions in + + +File: autogen.info, Node: SCM in?, Next: SCM join, Prev: SCM html-escape-encode, Up: Common Functions + +3.5.13 `in?' - test for string in list +-------------------------------------- + +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 + + +File: autogen.info, Node: SCM join, Next: SCM kr-string, Prev: SCM in?, Up: Common Functions + +3.5.14 `join' - join string list with separator +----------------------------------------------- + +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 + + +File: autogen.info, Node: SCM kr-string, Next: SCM lgpl, Prev: SCM join, Up: Common Functions + +3.5.15 `kr-string' - emit string for K&R C +------------------------------------------ + +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 + + +File: autogen.info, Node: SCM lgpl, Next: SCM license, Prev: SCM kr-string, Up: Common Functions + +3.5.16 `lgpl' - GNU Library General Public License +-------------------------------------------------- + +Usage: (lgpl prog_name owner prefix) +Emit a string that contains the GNU Library General Public License. +This function is now deprecated. Please *Note 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 + + +File: autogen.info, Node: SCM license, Next: SCM license-description, Prev: SCM lgpl, Up: Common Functions + +3.5.17 `license' - an arbitrary license +--------------------------------------- + +Usage: (license lic_name prog_name owner prefix) +Emit a string that contains the named license. This function is now +deprecated. Please *Note 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 + + +File: autogen.info, Node: SCM license-description, Next: SCM license-full, Prev: SCM license, Up: Common Functions + +3.5.18 `license-description' - Emit a license description +--------------------------------------------------------- + +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, *Note the license-full command: SCM license-full. + + 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 + + +File: autogen.info, Node: SCM license-full, Next: SCM license-info, Prev: SCM license-description, Up: Common Functions + +3.5.19 `license-full' - Emit the licensing information and description +---------------------------------------------------------------------- + +Usage: (license-full license prog-name prefix [ owner ] [ years ]) +Emit all the text that `license-info' and `license-description' would +emit (*note `license-info': SCM license-info, and *note +`license-description': SCM license-description.), with all the same +substitutions. + + All of these depend upon the existence of a license file named after +the `license' argument with a `.lic' suffix. That file should contain +three blocks of text, each separated by two or more newline characters. + + The first section describes copyright attribution and the name of +the usage licence. For GNU software, this should be the text that is +to be displayed with the program version. Four text markers can be +replaced: <PFX>, <program>, <years> and <owner>. + + The second section is a short description of the terms of the +license. This is typically the kind of text that gets displayed in the +header of source files. The third section is strictly the name of the +license without any substitution markers. Only the <PFX>, <owner> and +<program> markers are substituted. + + The third section is strictly the name of the license. No marker +substitutions are performed. + + <PFX>Copyright (C) <years> <owner>, all rights reserved. + <PFX>This is free software. It is licensed for use, + <PFX>modification and redistribution under the terms + <PFX>of the GNU General Public License, version 3 or later + <PFX> <http://gnu.org/licenses/gpl.html> + + <PFX><program> is free software: you can redistribute it + <PFX>and/or modify it under the terms of the GNU General + <PFX>Public License as published by the Free Software ... + + the GNU General Public License, version 3 or later + + 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 + + +File: autogen.info, Node: SCM license-info, Next: SCM license-name, Prev: SCM license-full, Up: Common Functions + +3.5.20 `license-info' - Emit the licensing information and copyright years +-------------------------------------------------------------------------- + +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 `--version' output. For more +details, *Note the license-full command: SCM license-full. + + 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 + + +File: autogen.info, Node: SCM license-name, Next: SCM make-gperf, Prev: SCM license-info, Up: Common Functions + +3.5.21 `license-name' - Emit the name of the license +---------------------------------------------------- + +Usage: (license-name license) +Emit a string that contains the full name of the license. + + Arguments: +license - name of license type + + +File: autogen.info, Node: SCM make-gperf, Next: SCM makefile-script, Prev: SCM license-name, Up: Common Functions + +3.5.22 `make-gperf' - build a perfect hash function program +----------------------------------------------------------- + +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, `gperf_<name>' for use by the gperf function *Note 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: + + [+ (shellf "sed '/^int main(/,$d;/^#line/d' ${gpdir}/%s.c" + name ) +] + + where `name' matches the name provided to this `make-perf' function. +`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 + + +File: autogen.info, Node: SCM makefile-script, Next: SCM max, Prev: SCM make-gperf, Up: Common Functions + +3.5.23 `makefile-script' - create makefile script +------------------------------------------------- + +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: + + 1. Trailing whitespace on each line is stripped. + + 2. 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 `make' renders it impossible to use multi-line + constructs anyway. + + 3. If the line ends with a backslash, it is left alone. + + 4. 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. + + 5. 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 + `$(<command>)' will not work. Though some `make's accept `${var}' + constructs, this function will assume it is for shell + interpretation and double the dollar character. You must use + `$(var)' for all `make' substitutions. + + 6. Double dollar signs are replaced by four before the next character + is examined. + + 7. Every line is prefixed with a tab, unless the first line already + starts with a tab. + + 8. The newline character on the last line, if present, is suppressed. + + 9. Blank lines are stripped. + + 10. 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 + `AC_CONFIG_FILES' sed expressions, similar to: + + sed "/^@ifdef foo/d;/^@endif foo/d;/^@ifndef foo/,/^@endif foo/d" + +This function is intended to be used approximately as follows: + + $(TARGET) : $(DEPENDENCIES) + <+ (out-push-new) +> + ....mostly arbitrary shell script text.... + <+ (makefile-script (out-pop #t)) +> + + Arguments: +text - the text of the script + + +File: autogen.info, Node: SCM max, Next: SCM min, Prev: SCM makefile-script, Up: Common Functions + +3.5.24 `max' - maximum value in list +------------------------------------ + +Usage: (max list ...) +Return the maximum value in the list + + Arguments: +list - list of values. Strings are converted to numbers + + +File: autogen.info, Node: SCM min, Next: SCM prefix, Prev: SCM max, Up: Common Functions + +3.5.25 `min' - minimum value in list +------------------------------------ + +Usage: (min list ...) +Return the minimum value in the list + + Arguments: +list - list of values. Strings are converted to numbers + + +File: autogen.info, Node: SCM prefix, Next: SCM printf, Prev: SCM min, Up: Common Functions + +3.5.26 `prefix' - prefix lines with a string +-------------------------------------------- + +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: + two + lines + The result string will contain: + # two + # lines + + Arguments: +prefix - string to insert at start of each line +text - multi-line block of text + + +File: autogen.info, Node: SCM printf, Next: SCM raw-shell-str, Prev: SCM prefix, Up: Common Functions + +3.5.27 `printf' - format to stdout +---------------------------------- + +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 + + +File: autogen.info, Node: SCM raw-shell-str, Next: SCM shell, Prev: SCM printf, Up: Common Functions + +3.5.28 `raw-shell-str' - single quote shell string +-------------------------------------------------- + +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. + + *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 + + +File: autogen.info, Node: SCM shell, Next: SCM shell-str, Prev: SCM raw-shell-str, Up: Common Functions + +3.5.29 `shell' - invoke a shell script +-------------------------------------- + +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 ``' definitions. There may be +left over state from previous shell expressions and the ``' processing +in the declarations. However, a `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. + + +File: autogen.info, Node: SCM shell-str, Next: SCM shellf, Prev: SCM shell, Up: Common Functions + +3.5.30 `shell-str' - double quote shell string +---------------------------------------------- + +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 `\\' before two special characters to accomplish this: +the backslash `\\' and double quote `"'. + + *Notice*: some shells will not correctly handle unusual non-printing +characters. This routine works for most reasonably conventional ASCII +strings. + + *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 `sub-shell-str' variation of this routine behaves identically, +except that the extra backslash is omitted in front of `"' instead of +``'. 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 `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 +`raw-shell-str', `shell-str' and `sub-shell-str' functions. + + 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` + + 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 + + +File: autogen.info, Node: SCM shellf, Next: SCM sprintf, Prev: SCM shell-str, Up: Common Functions + +3.5.31 `shellf' - format a string, run shell +-------------------------------------------- + +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 + + +File: autogen.info, Node: SCM sprintf, Next: SCM string-capitalize, Prev: SCM shellf, Up: Common Functions + +3.5.32 `sprintf' - format a string +---------------------------------- + +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 + + +File: autogen.info, Node: SCM string-capitalize, Next: SCM string-capitalize!, Prev: SCM sprintf, Up: Common Functions + +3.5.33 `string-capitalize' - capitalize a new string +---------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string-capitalize!, Next: SCM *=*, Prev: SCM string-capitalize, Up: Common Functions + +3.5.34 `string-capitalize!' - capitalize a string +------------------------------------------------- + +Usage: (string-capitalize! str) +capitalize all the words in an SCM string. + + Arguments: +str - input/output string + + +File: autogen.info, Node: SCM *=*, Next: SCM *==*, Prev: SCM string-capitalize!, Up: Common Functions + +3.5.35 `string-contains-eqv?' - caseless substring +-------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM *==*, Next: SCM string-downcase, Prev: SCM *=*, Up: Common Functions + +3.5.36 `string-contains?' - substring match +------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string-downcase, Next: SCM string-downcase!, Prev: SCM *==*, Up: Common Functions + +3.5.37 `string-downcase' - lower case a new string +-------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string-downcase!, Next: SCM *~, Prev: SCM string-downcase, Up: Common Functions + +3.5.38 `string-downcase!' - make a string be lower case +------------------------------------------------------- + +Usage: (string-downcase! str) +Change to lower case all the characters in an SCM string. + + Arguments: +str - input/output string + + +File: autogen.info, Node: SCM *~, Next: SCM *~~, Prev: SCM string-downcase!, Up: Common Functions + +3.5.39 `string-end-eqv-match?' - caseless regex ending +------------------------------------------------------ + +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 + + +File: autogen.info, Node: SCM *~~, Next: SCM *=, Prev: SCM *~, Up: Common Functions + +3.5.40 `string-end-match?' - regex match end +-------------------------------------------- + +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 + + +File: autogen.info, Node: SCM *=, Next: SCM *==, Prev: SCM *~~, Up: Common Functions + +3.5.41 `string-ends-eqv?' - caseless string ending +-------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM *==, Next: SCM ==, Prev: SCM *=, Up: Common Functions + +3.5.42 `string-ends-with?' - string ending +------------------------------------------ + +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 + + +File: autogen.info, Node: SCM ==, Next: SCM ~, Prev: SCM *==, Up: Common Functions + +3.5.43 `string-equals?' - string matching +----------------------------------------- + +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 + + +File: autogen.info, Node: SCM ~, Next: SCM =, Prev: SCM ==, Up: Common Functions + +3.5.44 `string-eqv-match?' - caseless regex match +------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM =, Next: SCM *~*, Prev: SCM ~, Up: Common Functions + +3.5.45 `string-eqv?' - caseless match +------------------------------------- + +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 `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 + + +File: autogen.info, Node: SCM *~*, Next: SCM *~~*, Prev: SCM =, Up: Common Functions + +3.5.46 `string-has-eqv-match?' - caseless regex contains +-------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM *~~*, Next: SCM ~~, Prev: SCM *~*, Up: Common Functions + +3.5.47 `string-has-match?' - contained regex match +-------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM ~~, Next: SCM ~*, Prev: SCM *~~*, Up: Common Functions + +3.5.48 `string-match?' - regex match +------------------------------------ + +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 + + +File: autogen.info, Node: SCM ~*, Next: SCM ~~*, Prev: SCM ~~, Up: Common Functions + +3.5.49 `string-start-eqv-match?' - caseless regex start +------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM ~~*, Next: SCM =*, Prev: SCM ~*, Up: Common Functions + +3.5.50 `string-start-match?' - regex match start +------------------------------------------------ + +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 + + +File: autogen.info, Node: SCM =*, Next: SCM ==*, Prev: SCM ~~*, Up: Common Functions + +3.5.51 `string-starts-eqv?' - caseless string start +--------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM ==*, Next: SCM string-substitute, Prev: SCM =*, Up: Common Functions + +3.5.52 `string-starts-with?' - string starting +---------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string-substitute, Next: SCM string-table-add, Prev: SCM ==*, Up: Common Functions + +3.5.53 `string-substitute' - multiple global replacements +--------------------------------------------------------- + +Usage: (string-substitute source match repl) +`match' and `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: + + (string-substitute source + (list "&" "<" ">") + (list "&" "<" ">")) + + Arguments: +source - string to transform +match - substring or substring list to be replaced +repl - replacement strings or substrings + + +File: autogen.info, Node: SCM string-table-add, Next: SCM string-table-add-ref, Prev: SCM string-substitute, Up: Common Functions + +3.5.54 `string-table-add' - Add an entry to a string table +---------------------------------------------------------- + +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: + string_array + <returned-value> + that will yield the address of the first byte of the inserted +string. See the `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 + + +File: autogen.info, Node: SCM string-table-add-ref, Next: SCM string-table-new, Prev: SCM string-table-add, Up: Common Functions + +3.5.55 `string-table-add-ref' - Add an entry to a string table, get reference +----------------------------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string-table-new, Next: SCM string-table-size, Prev: SCM string-table-add-ref, Up: Common Functions + +3.5.56 `string-table-new' - create a string table +------------------------------------------------- + +Usage: (string-table-new st-name) +This function will create an array of characters. The companion +functions, (*Note SCM string-table-add::, *Note SCM +string-table-add-ref::, and *note 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. + +Here is a brief example copied from the strtable.test test: + + [+ (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 }; + +Some explanation: + +I added the `(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 `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. +(`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 `ag-fprintf' the array-of-pointer declaration +directly into the current output. Finally I restore the "main" output +stream and `(out-pop #t)'-it into the main output stream. + + Here is the result. Note that duplicate strings are not repeated in +the string table: + + 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 }; + + These functions use the global name space `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 +`-Wno-format-contains-nul' + + Arguments: +st-name - the name of the array of characters + + +File: autogen.info, Node: SCM string-table-size, Next: SCM string->c-name!, Prev: SCM string-table-new, Up: Common Functions + +3.5.57 `string-table-size' - print the current size of a string table +--------------------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string->c-name!, Next: SCM string->camelcase, Prev: SCM string-table-size, Up: Common Functions + +3.5.58 `string->c-name!' - map non-name chars to underscore +----------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string->camelcase, Next: SCM string-tr, Prev: SCM string->c-name!, Up: Common Functions + +3.5.59 `string->camelcase' - make a string be CamelCase +------------------------------------------------------- + +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 + + +File: autogen.info, Node: SCM string-tr, Next: SCM string-tr!, Prev: SCM string->camelcase, Up: Common Functions + +3.5.60 `string-tr' - convert characters with new result +------------------------------------------------------- + +Usage: (string-tr source match translation) +This is identical to `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 + + +File: autogen.info, Node: SCM string-tr!, Next: SCM string-upcase, Prev: SCM string-tr, Up: Common Functions + +3.5.61 `string-tr!' - convert characters +---------------------------------------- + +Usage: (string-tr! source match translation) +This is the same as the `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 + + +File: autogen.info, Node: SCM string-upcase, Next: SCM string-upcase!, Prev: SCM string-tr!, Up: Common Functions + +3.5.62 `string-upcase' - upper case a new string +------------------------------------------------ + +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 + + +File: autogen.info, Node: SCM string-upcase!, Next: SCM sub-shell-str, Prev: SCM string-upcase, Up: Common Functions + +3.5.63 `string-upcase!' - make a string be upper case +----------------------------------------------------- + +Usage: (string-upcase! str) +Change to upper case all the characters in an SCM string. + + Arguments: +str - input/output string + + +File: autogen.info, Node: SCM sub-shell-str, Next: SCM sum, Prev: SCM string-upcase!, Up: Common Functions + +3.5.64 `sub-shell-str' - back quoted (sub-)shell string +------------------------------------------------------- + +Usage: (sub-shell-str string) +This function is substantially identical to `shell-str', except that +the quoting character is ``' and the "leave the escape alone" character +is `"'. + + Arguments: +string - string to transform + + +File: autogen.info, Node: SCM sum, Next: SCM time-string->number, Prev: SCM sub-shell-str, Up: Common Functions + +3.5.65 `sum' - sum of values in list +------------------------------------ + +Usage: (sum list ...) +Compute the sum of the list of expressions. + + Arguments: +list - list of values. Strings are converted to numbers + + +File: autogen.info, Node: SCM time-string->number, Next: SCM version-compare, Prev: SCM sum, Up: Common Functions + +3.5.66 `time-string->number' - duration string to seconds +--------------------------------------------------------- + +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 `d', `h', `m' and `s' respectively. +Hours, minutes and seconds may also be represented with `HH:MM:SS' or, +without hours, as `MM:SS'. + + Arguments: +time_spec - string to parse + + +File: autogen.info, Node: SCM version-compare, Prev: SCM time-string->number, Up: Common Functions + +3.5.67 `version-compare' - compare two version numbers +------------------------------------------------------ + +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: + (version-compare > "5.8.5" "5.8.5-pre4") + (version-compare > "5.8.5-pre10" "5.8.5-pre4") + + Arguments: +op - comparison operator +v1 - first version +v2 - compared-to version + + +File: autogen.info, Node: native macros, Next: output controls, Prev: Common Functions, Up: Template File + +3.6 AutoGen 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: + +`CASE' + This macro has scope through the `ESAC' macro. The scope is + subdivided by `SELECT' macros. You must have at least one + `SELECT' macro. + +`DEFINE' + This macro has scope through the `ENDDEF' macro. The defined user + macro can never be a block macro. This macro is extracted from + the template 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. + +`FOR' + This macro has scope through the `ENDFOR' macro. + +`IF' + This macro has scope through the `ENDIF' macro. The scope may be + subdivided by `ELIF' and `ELSE' macros. Obviously, there may be + only one `ELSE' macro and it must be the last of these + subdivisions. + +`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. + +`WHILE' + This macro has scope through the `ENDWHILE' macro. + +* 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 `FOR' function template block +* ENDIF:: ENDIF - Terminate the `IF' Template Block +* ENDWHILE:: ENDWHILE - Terminate the `WHILE' Template Block +* ESAC:: ESAC - Terminate the `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 + + +File: autogen.info, Node: AGMacro syntax, Next: BREAK, Up: native macros + +3.6.1 AutoGen Macro Syntax +-------------------------- + +The general syntax is: + + [ { <native-macro-name> | <user-defined-name> } ] [ <arg> ... ] + +The syntax for `<arg>' depends on the particular macro, but is +generally a full expression (*note expression syntax::). Here are the +exceptions to that general rule: + + 1. `INVOKE' macros, implicit or explicit, must be followed by a list + of name/string value pairs. The string values are simple + expressions, as described above. + + That is, the `INVOKE' syntax is one of these two: + <user-macro-name> [ <name> [ = <expression> ] ... ] + + INVOKE <name-expression> [ <name> [ = <expression> ] ... ] + + 2. AutoGen FOR macros must be in one of three forms: + + FOR <name> [ <separator-string> ] + + FOR <name> (...Scheme expression list) + + FOR <name> IN <string-entry> [ ... ] + where: + `<name>' + must be a simple name. + + `<separator-string>' + is inserted between copies of the enclosed block. Do not try + to use "IN" as your separator string. It won't work. + + `<string-entry>' + is an entry in a list of strings. "`<name>'" is assigned + each value from the "`IN'" list before expanding the `FOR' + block. + + `(...Scheme expression list)' + is expected to contain one or more of the `for-from', + `for-to', `for-by', and `for-sep' functions. (*Note FOR::, + and *note AutoGen Functions::) + + The first two forms iterate over the `FOR' block if `<name>' is + found in the AutoGen values. The last form will create the AutoGen + value named `<name>'. + + 3. AutoGen `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. *Note DEFINE::. + + 4. The AutoGen `COMMENT', `ELSE', `ESAC' and the `END*' macros take + no arguments and ignore everything after the macro name (e.g. see + *note COMMENT::) + + +File: autogen.info, Node: BREAK, Next: CASE, Prev: AGMacro syntax, Up: native macros + +3.6.2 BREAK - Leave a FOR or WHILE macro +---------------------------------------- + +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". + + +File: autogen.info, Node: CASE, Next: COMMENT, Prev: BREAK, Up: native macros + +3.6.3 CASE - Select one of several template blocks +-------------------------------------------------- + +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 `SELECT' macros (see the example below and the +expression evaluation function, *note EXPR::). The scope of the macro +is up to the matching `ESAC' macro. Within the scope of a `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: + + 1. Must the match start matching from the beginning of the string? + If not, then the match macro code starts with an asterisk (`*'). + + 2. Must the match finish matching at the end of the string? If not, + then the match macro code ends with an asterisk (`*'). + + 3. Is the match a pattern match or a string comparison? If a + comparison, use an equal sign (`='). If a pattern match, use a + tilde (`~'). + + 4. Is the match case sensitive? If alphabetic case is important, + double the tilde or equal sign. + + 5. Do you need a default match when none of the others match? Use a + single asterisk (`*'). + + 6. Do you need to distinguish between an empty string value and a + value that was not found? Use the non-existence test (`!E') before + testing a full match against an empty string (`== '''). There is + also an existence test (`+E'), more for symmetry than for + practical use. + +For example: + + [+ CASE <full-expression> +] + [+ ~~* "[Tt]est" +]reg exp must match at start, not at end + [+ == "TeSt" +]a full-string, case sensitive compare + [+ = "TEST" +]a full-string, case insensitive compare + [+ !E +]not exists - matches if no AutoGen value found + [+ == "" +]expression yielded a zero-length string + [+ +E +]exists - matches if there is any value result + [+ * +]always match - no testing + [+ ESAC +] + + `<full-expression>' (*note 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 (*note Common Functions::). + + +File: autogen.info, Node: COMMENT, Next: CONTINUE, Prev: CASE, Up: native macros + +3.6.4 COMMENT - A block of comment to be ignored +------------------------------------------------ + +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 `#', then the entire macro function +is treated as a comment and ignored. + + [+ # say what you want, but no '+' before any ']' chars +] + + +File: autogen.info, Node: CONTINUE, Next: DEBUG, Prev: COMMENT, Up: native macros + +3.6.5 CONTINUE - Skip to end of a FOR or WHILE macro. +----------------------------------------------------- + +This will skip the remainder of the loop and start the next. + + +File: autogen.info, Node: DEBUG, Next: DEFINE, Prev: CONTINUE, Up: native macros + +3.6.6 DEBUG - Print debug message to trace output +------------------------------------------------- + +If the tracing level is at "debug-message" or above (*note 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. + + +File: autogen.info, Node: DEFINE, Next: ELIF, Prev: DEBUG, Up: native macros + +3.6.7 DEFINE - Define a user AutoGen 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. + + [+ define foo +] + ... macro body with macro functions ... + [+ enddef +] + ... [+ foo bar='raw text' baz=<<text expression>> +] + + 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 `INVOKE' (*note 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. *Note expression syntax::. + + The resulting definitions are handled much like regular definitions, +except: + + 1. The values may not be compound. That is, they may not contain + nested name/value pairs. + + 2. The bindings go away when the macro is complete. + + 3. The name/value pairs are separated by whitespace instead of + semi-colons. + + 4. Sequences of strings are not concatenated. + + *NB:* The macro is extracted from the template as the template is + scanned. You cannot conditionally define a macro by enclosing it + in an `IF'/`ENDIF' (*note IF::) macro pair. If you need to + dynamically select the format of a `DEFINE'd macro, then put the + flavors into separate template files that simply define macros. + `INCLUDE' (*note INCLUDE::) the appropriate template when you have + computed which you need. + + Due to this, it is acceptable and even a good idea to place all the +`DEFINE' macros at the end of the template. That puts the main body of +the template at the beginning of the file. + + +File: autogen.info, Node: ELIF, Next: ELSE, Prev: DEFINE, Up: native macros + +3.6.8 ELIF - Alternate Conditional Template Block +------------------------------------------------- + +This macro must only appear after an `IF' function, and before any +associated `ELSE' or `ENDIF' functions. It denotes the start of an +alternate template block for the `IF' function. Its expression +argument is evaluated as are the arguments to `IF'. For a complete +description *Note IF::. + + +File: autogen.info, Node: ELSE, Next: ENDDEF, Prev: ELIF, Up: native macros + +3.6.9 ELSE - Alternate Template Block +------------------------------------- + +This macro must only appear after an `IF' function, and before the +associated `ENDIF' function. It denotes the start of an alternate +template block for the `IF' function. For a complete description *Note +IF::. + + +File: autogen.info, Node: ENDDEF, Next: ENDFOR, Prev: ELSE, Up: native macros + +3.6.10 ENDDEF - Ends a macro definition. +---------------------------------------- + +This macro ends the `DEFINE' function template block. For a complete +description *Note DEFINE::. + + +File: autogen.info, Node: ENDFOR, Next: ENDIF, Prev: ENDDEF, Up: native macros + +3.6.11 ENDFOR - Terminates the `FOR' function template block +------------------------------------------------------------ + +This macro ends the `FOR' function template block. For a complete +description *Note FOR::. + + +File: autogen.info, Node: ENDIF, Next: ENDWHILE, Prev: ENDFOR, Up: native macros + +3.6.12 ENDIF - Terminate the `IF' Template Block +------------------------------------------------ + +This macro ends the `IF' function template block. For a complete +description *Note IF::. + + +File: autogen.info, Node: ENDWHILE, Next: ESAC, Prev: ENDIF, Up: native macros + +3.6.13 ENDWHILE - Terminate the `WHILE' Template Block +------------------------------------------------------ + +This macro ends the `WHILE' function template block. For a complete +description *Note WHILE::. + + +File: autogen.info, Node: ESAC, Next: EXPR, Prev: ENDWHILE, Up: native macros + +3.6.14 ESAC - Terminate the `CASE' Template Block +------------------------------------------------- + +This macro ends the `CASE' function template block. For a complete +description, *Note CASE::. + + +File: autogen.info, Node: EXPR, Next: FOR, Prev: ESAC, Up: native macros + +3.6.15 EXPR - Evaluate and emit an Expression +--------------------------------------------- + +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 (*note expression syntax::) is +written to the current output. + + +File: autogen.info, Node: FOR, Next: IF, Prev: EXPR, Up: native macros + +3.6.16 FOR - Emit a template block multiple times +------------------------------------------------- + +This macro has a slight variation on the standard syntax: + FOR <value-name> [ <separator-string> ] + + FOR <value-name> (...Scheme expression list) + + FOR <value-name> IN "string" [ ... ] + + 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 `FOR' template block is skipped entirely. The scope of the +`FOR' macro extends to the corresponding `ENDFOR' macro. The last form +will create an array of string values named `<value-name>' that only +exists within the context of this `FOR' loop. With this form, in order +to use a `separator-string', you must code it into the end of the +template block using the `(last-for?)' predicate function (*note SCM +last-for?::). + + If there are any arguments after the `value-name', the initial +characters are used to determine the form. If the first character is +either a semi-colon (`;') or an opening parenthesis (`('), then it is +presumed to be a Scheme expression containing the FOR macro specific +functions `for-from', `for-by', `for-to', and/or `for-sep'. *Note +AutoGen Functions::. If it consists of an '`i'' an '`n'' and separated +by white space from more text, then the `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 `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. + + *NB:* the `for-from', `for-to', `for-by' and `for-sep' functions are +disabled outside of the context of the `FOR' macro. Likewise, the +`first-for', `last-for' and `for-index' functions are disabled outside +of the range of a `FOR' block. + + *Also:* the `<value-name>' must be a single level name, not a +compound name (*note naming values::). + + [+FOR var (for-from 0) (for-to <number>) (for-sep ",") +] + ... text with `var'ious substitutions ...[+ + ENDFOR var+] + +this will repeat the `... text with `var'ious substitutions ...' +<number>+1 times. Each repetition, except for the last, will have a +comma `,' after it. + + [+FOR var ",\n" +] + ... text with `var'ious substitutions ...[+ + ENDFOR var +] + +This will do the same thing, but only for the index values of `var' +that have actually been defined. + + +File: autogen.info, Node: IF, Next: INCLUDE, Prev: FOR, Up: native macros + +3.6.17 IF - Conditionally Emit a Template Block +----------------------------------------------- + +Conditional block. Its arguments are evaluated (*note 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 `ELIF', +`ELSE' or `ENDIF' is emitted. `ELIF' introduces a conditional +alternative if the `IF' clause evaluated FALSE and `ELSE' introduces an +unconditional alternative. + + [+IF <full-expression> +] + emit things that are for the true condition[+ + + ELIF <full-expression-2> +] + emit things that are true maybe[+ + + ELSE "This may be a comment" +] + emit this if all but else fails[+ + + ENDIF "This may *also* be a comment" +] + +`<full-expression>' may be any expression described in the `EXPR' +expression function, including the use of apply-codes and value-names. +If the expression yields an empty string, it is interpreted as false. + + +File: autogen.info, Node: INCLUDE, Next: INVOKE, Prev: IF, Up: native macros + +3.6.18 INCLUDE - Read in and emit a template block +-------------------------------------------------- + +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 `CASE', `DEFINE', `FOR', `IF' and `WHILE'; extending through +their respective terminating macro functions. + + +File: autogen.info, Node: INVOKE, Next: RETURN, Prev: INCLUDE, Up: native macros + +3.6.19 INVOKE - Invoke a User Defined Macro +------------------------------------------- + +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 *not* be a computed value. If +you explicitly invoke a user defined macro, the macro begins with the +macro name `INVOKE' followed by a 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 (`=') and a 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. + + +File: autogen.info, Node: RETURN, Next: SELECT, Prev: INVOKE, Up: native macros + +3.6.20 RETURN - Leave an INVOKE-d (DEFINE) macro +------------------------------------------------ + +This will unwind looping constructs inside of a DEFINE-d macro and +return to the invocation point. The output files and diversions 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. + + +File: autogen.info, Node: SELECT, Next: UNKNOWN, Prev: RETURN, Up: native macros + +3.6.21 SELECT - Selection block for CASE function +------------------------------------------------- + +This macro selects a block of text by matching an expression against +the sample text expression evaluated in the `CASE' macro. *Note CASE::. + + You do not specify a `SELECT' macro with the word "select". +Instead, you must use one of the 19 match operators described in the +`CASE' macro description. + + +File: autogen.info, Node: UNKNOWN, Next: WHILE, Prev: SELECT, Up: native macros + +3.6.22 UNKNOWN - Either a user macro or a value name. +----------------------------------------------------- + +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 `UNKNOWN' explicitly. + + +File: autogen.info, Node: WHILE, Prev: UNKNOWN, Up: native macros + +3.6.23 WHILE - Conditionally loop over a Template Block +------------------------------------------------------- + +Conditionally repeated block. Its arguments are evaluated (*note +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 `ENDWHILE' is emitted. + + [+WHILE <full-expression> +] + emit things that are for the true condition[+ + + ENDWHILE +] + +`<full-expression>' may be any expression described in the `EXPR' +expression function, including the use of apply-codes and value-names. +If the expression yields an empty string, it is interpreted as false. + + +File: autogen.info, Node: output controls, Prev: native macros, Up: Template File + +3.7 Redirecting Output +====================== + +AutoGen provides a means for redirecting the template output to +different files or, in `M4' parlance, to various diversions. It is +accomplished by providing a set of Scheme functions named `out-*' +(*note AutoGen Functions::). + +`out-push-new (*note 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 "`#t'" argument + to the `out-pop' (*note SCM out-pop::) function. + +`out-pop (*note 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 `out-push-new' (*note SCM + out-push-new::) function. If "`#t'" is passed in as an argument, + then the entire contents of the diversion (or file) is returned. + +`out-suspend (*note SCM out-suspend::)' + This function does not close the current output, but instead sets + it aside for resumption by the given name with `out-resume'. The + current output must have been pushed on the output queue with + `out-push-new' (*note SCM out-push-new::). + +`out-resume (*note SCM out-resume::)' + This will put a named file descriptor back onto the top of stack + so that it becomes the current output again. + +`out-switch (*note 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. + +`out-move (*note SCM out-move::)' + Renames the current output file without closing it. + + There are also several functions for determining the output status. +*Note AutoGen Functions::. + + +File: autogen.info, Node: Augmenting AutoGen, Next: autogen Invocation, Prev: Template File, Up: Top + +4 Augmenting AutoGen Features +***************************** + +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 + + +File: autogen.info, Node: shell commands, Next: guile macros, Up: Augmenting AutoGen + +4.1 Shell Output Commands +========================= + +Shell commands are run inside of a server process. This means that, +unlike `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: + die "some error text" + +That is a shell function added by AutoGen. It will send a SIGTERM to +autogen and exit from the "persistent" shell. + + +File: autogen.info, Node: guile macros, Next: guile callouts, Prev: shell commands, Up: Augmenting AutoGen + +4.2 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 `--load-scheme' command line option (*note 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: + (error "some error text") + + +File: autogen.info, Node: guile callouts, Next: AutoGen macros, Prev: guile macros, Up: Augmenting AutoGen + +4.3 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 `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 `exp*.c'. You also must have a +stylized comment that `getdefs' can find that conforms to the following: + + /*=gfunc <function-name> + * + * what: <short one-liner> + * general_use: + * string: <invocation-name-string> + * exparg: <name>, <description> [, ['optional'] [, 'list']] + * doc: A long description telling people how to use + * this function. + =*/ + SCM + ag_scm_<function-name>( SCM arg_name[, ...] ) + { <code> } + +`gfunc' + You must have this exactly thus. + +`<function-name>' + This must follow C syntax for variable names + +`<short one-liner>' + This should be about a half a line long. It is used as a + subsection title in this document. + +`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. + +`<invocation-name-string>' + Normally, the `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. + +`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. + +`doc:' + Please say something meaningful. + +`[, ...]' + Do not actually specify an ANSI ellipsis here. You must provide + for all the arguments you specified with `exparg'. + + See the Guile documentation for more details. More information is +also available in a large comment at the beginning of the +`agen5/snarf.tpl' template file. + + +File: autogen.info, Node: AutoGen macros, Prev: guile callouts, Up: Augmenting AutoGen + +4.4 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 +`--lib-template' option (See *note DEFINE:: and *note 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. + + +File: autogen.info, Node: autogen Invocation, Next: Installation, Prev: Augmenting AutoGen, Up: Top + +5 Invoking autogen +****************** + +AutoGen creates text files from templates using external definitions. + + `AutoGen' is designed for generating program files that contain +repetitive text with varied substitutions. The 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. + + One common example is the problem of maintaining the code required +for processing program options. Processing options requires a minimum +of four different constructs be kept in proper order in different places +in your program. You need at least: The flag character in the flag +string, code to process the flag when it is encountered, a global state +variable or two, and a line in the usage text. You will need more +things besides this if you choose to implement long option names, +configuration file processing, environment variables and so on. + + All of this can be done mechanically; with the proper templates and +this program. + + This chapter was generated by *AutoGen*, using the `agtexi-cmd' +template and the option descriptions for the `autogen' program. This +software is released under the GNU General Public License, version 3 or +later. + +* Menu: + +* autogen usage:: autogen help/usage (`--help') +* autogen input-select:: input-select options +* autogen out-handling:: out-handling options +* autogen debug-tpl:: debug-tpl options +* autogen processing:: processing options +* autogen dep-track:: dep-track options +* autogen config:: presetting/configuring autogen +* autogen exit status:: exit status +* autogen Examples:: Examples + + +File: autogen.info, Node: autogen usage, Next: autogen input-select, Up: autogen Invocation + +5.1 autogen help/usage (`--help') +================================= + +This is the automatically generated usage text for autogen. + + The text printed is the same whether selected with the `help' option +(`--help') or the `more-help' option (`--more-help'). `more-help' will +print the usage text by passing it through a pager program. +`more-help' is disabled on platforms without a working `fork(2)' +function. The `PAGER' environment variable is used to select the +program, defaulting to `more'. Both will exit with a status code of 0. + +autogen (GNU AutoGen) - The Automated Program Generator - Ver. 5.16.2pre7 +USAGE: autogen [ -<flag> [<val>] | --<name>[{=| }<val>] ]... [ <def-file> ] + +The following options select definitions, templates and scheme functions +to use: + + Flg Arg Option-Name Description + -L Str templ-dirs Template search directory list + - may appear multiple times + -T Str override-tpl Override template file + - may not be preset + -l Str lib-template Library template file + - may appear multiple times + Str definitions Definitions input file + - disabled as --no-definitions + - enabled by default + - may not be preset + -S Str load-scheme Scheme code file to load + -F Str load-functions Load scheme function library + Str shell name or path name of shell to use + -m no no-fmemopen Do not use in-mem streams + Str equate characters considered equivalent + +The following options modify how output is handled: + + Flg Arg Option-Name Description + -b Str base-name Base name for output file(s) + - may not be preset + no source-time set mod times to latest source + - disabled as --no-source-time + no writable Allow output files to be writable + - disabled as --not-writable + +The following options are often useful while debugging new templates: + + Flg Arg Option-Name Description + Num loop-limit Limit on increment loops + - is scalable with a suffix: k/K/m/M/g/G/t/T + - It must lie in one of the ranges: + -1 exactly, or + 1 to 16777216 + -t Num timeout Time limit for server shell + - It must be in the range: + 0 to 3600 + KWd trace tracing level of detail + Str trace-out tracing output file or filter + --- show-defs This option has been disabled + no used-defines Show the definitions used + - may not be preset + -C no core Leave a core dump on a failure exit + +These options can be used to control what gets processed in the +definitions files and template files: + + Flg Arg Option-Name Description + -s Str skip-suffix Omit the file with this suffix + - prohibits these options: + select-suffix + - may not be preset + - may appear multiple times + -o Str select-suffix specify this output suffix + - may not be preset + - may appear multiple times + -D Str define name to add to definition list + - may appear multiple times + -U Str undefine definition list removal pattern + - an alternate for define + +This option is used to automate dependency tracking: + + Flg Arg Option-Name Description + -M opt make-dep emit make dependency file + - may not be preset + - may appear multiple times + +version, usage and configuration options: + + Flg Arg Option-Name Description + -R Str reset-option Reset an option's state + -v opt version Output version information and exit + -? no help Display extended usage information and exit + -! no more-help Extended usage information passed thru pager + -u no usage Abbreviated usage to stdout + -> opt save-opts Save the option state to a config file + -< Str load-opts Load options from a config file + - disabled as --no-load-opts + - may appear multiple times + +Options are specified by doubled hyphens and their name or by a single +hyphen and the flag character. + +AutoGen creates text files from templates using external definitions. + +The following option preset mechanisms are supported: + - reading file $HOME + - reading file ./.autogenrc + - examining environment variables named AUTOGEN_* + +The valid "trace" option keywords are: + nothing debug-message server-shell templates block-macros + expressions everything + or an integer from 0 through 6 + +AutoGen is a tool designed for generating program files that contain +repetitive text with varied substitutions. +Packaged by Bruce (2012-08-10) +Report autogen bugs to bkorb@gnu.org + + +File: autogen.info, Node: autogen input-select, Next: autogen out-handling, Prev: autogen usage, Up: autogen Invocation + +5.2 input-select options +======================== + +The following options select definitions, templates and scheme +functions to use. + +templ-dirs option (-L). +----------------------- + +This is the "template search directory list" option. This option takes +an argument string `dir'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + Add a directory to the list of directories to search when opening a +template, either as the primary template or an included one. The last +entry has the highest priority in the search list. That is to say, +they are searched in reverse order. + +override-tpl option (-T). +------------------------- + +This is the "override template file" option. This option takes an +argument string `tpl-file'. + +This option has some usage constraints. It: + * may not be preset with environment variables or configuration + (rc/ini) files. + + Definition files specify the standard template that is to be +expanded. This option will override that name and expand a different +template. + +lib-template option (-l). +------------------------- + +This is the "library template file" option. This option takes an +argument string `tpl-file'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + DEFINE macros are saved from this template file for use in processing +the main macro file. Template text aside from the DEFINE macros is is +ignored. + +definitions option. +------------------- + +This is the "definitions input file" option. This option takes an +argument string `file'. + +This option has some usage constraints. It: + * is enabled by default. + + * may not be preset with environment variables or configuration + (rc/ini) files. + + Use this argument to specify the input definitions file with a +command line option. If you do not specify this option, then there +must be a command line argument that specifies the file, even if only +to specify stdin with a hyphen (`-'). Specify, `--no-definitions' when +you wish to process a template without any active AutoGen definitions. + +load-scheme option (-S). +------------------------ + +This is the "scheme code file to load" option. This option takes an +argument string `file'. Use this option to pre-load Scheme scripts +into the Guile interpreter before template processing begins. Please +note that the AutoGen specific functions are not loaded until after +argument processing. So, though they may be specified in lambda +functions you define, they may not be invoked until after option +processing is complete. + +load-functions option (-F). +--------------------------- + +This is the "load scheme function library" option. This option takes +an argument string `file'. + +This option has some usage constraints. It: + * must be compiled in by defining `HAVE_DLOPEN' during the + compilation. + + This option is used to load Guile-scheme functions. The +automatically called initialization routine `scm_init' must be used to +register these routines or data. + +shell option. +------------- + +This is the "name or path name of shell to use" option. This option +takes an argument string `shell'. + +This option has some usage constraints. It: + * must be compiled in by defining `SHELL_ENABLED' during the + compilation. + + By default, when AutoGen is built, the configuration is probed for a +reasonable Bourne-like shell to use for shell script processing. If a +particular template needs an alternate shell, it must be specified with +this option on the command line, with an environment variable (`SHELL') +or in the configuration/initialization file. + +no-fmemopen option (-m). +------------------------ + +This is the "do not use in-mem streams" option. If the local C library +supports "`fopencookie(3GNU)'", or "`funopen(3BSD)'" then AutoGen +prefers to use in-memory stream buffer opens instead of anonymous +files. This may lead to problems if there is a shortage of virtual +memory. If, for a particular application, you run out of memory, then +specify this option. This is unlikely in a modern 64-bit virtual +memory environment. + + On platforms without these functions, the option is accepted but +ignored. `fmemopen(POSIX)' is not adequate because its string buffer +is not reallocatable. `open_memstream(POSIX)' is also not adequate +because the stream is only opened for output. AutoGen needs a +reallocatable buffer available for both reading and writing. + +equate option. +-------------- + +This is the "characters considered equivalent" option. This option +takes an argument string `char-list'. This option will alter the list +of characters considered equivalent. The default are the three +characters, "_-^". (The last is conventional on a Tandem/HP-NonStop, +and I used to do a lot of work on Tandems.) + + +File: autogen.info, Node: autogen out-handling, Next: autogen debug-tpl, Prev: autogen input-select, Up: autogen Invocation + +5.3 out-handling options +======================== + +The following options modify how output is handled. + +base-name option (-b). +---------------------- + +This is the "base name for output file(s)" option. This option takes +an argument string `name'. + +This option has some usage constraints. It: + * may not be preset with environment variables or configuration + (rc/ini) files. + + A template may specify the exact name of the output file. Normally, +it does not. Instead, the name is composed of the base name of the +definitions file with suffixes appended. This option will override the +base name derived from the definitions file name. This is required if +there is no definitions file and advisable if definitions are being +read from stdin. If the definitions are being read from standard in, +the base name defaults to `stdin'. Any leading directory components in +the name will be silently removed. If you wish the output file to +appear in a particular directory, it is recommended that you "cd" into +that directory first, or use directory names in the format specification +for the output suffix lists, *Note pseudo macro::. + +source-time option. +------------------- + +This is the "set mod times to latest source" option. If you stamp your +output files with the `DNE' macro output, then your output files will +always be different, even if the content has not really changed. If +you use this option, then the modification time of the output files +will change only if the input files change. This will help reduce +unneeded builds. + +writable option. +---------------- + +This is the "allow output files to be writable" option. This option +will leave output files writable. Normally, output files are read-only. + + +File: autogen.info, Node: autogen debug-tpl, Next: autogen processing, Prev: autogen out-handling, Up: autogen Invocation + +5.4 debug-tpl options +===================== + +The following options are often useful while debugging new templates. +They specify limits that prevent the template from taking overly long +or producing more output than expected. + +loop-limit option. +------------------ + +This is the "limit on increment loops" option. This option takes an +argument number `lim'. This option prevents runaway loops. For +example, if you accidentally specify, "FOR x (for-from 1) (for-to -1) +(for-by 1)", it will take a long time to finish. If you do have more +than 256 entries in tables, you will need to specify a new limit with +this option. + +timeout option (-t). +-------------------- + +This is the "time limit for server shell" option. This option takes an +argument number `time-lim'. + +This option has some usage constraints. It: + * must be compiled in by defining `SHELL_ENABLED' during the + compilation. + + AutoGen works with a shell server process. Most normal commands will +complete in less than 10 seconds. If, however, your commands need more +time than this, use this option. + + The valid range is 0 to 3600 seconds (1 hour). Zero will disable +the server time limit. + +trace option. +------------- + +This is the "tracing level of detail" option. This option takes an +argument keyword `level'. + +This option has some usage constraints. It: + * This option takes a keyword as its argument. The argument sets an + enumeration value that can be tested by comparing the option value + macro (OPT_VALUE_TRACE). The available keywords are: + nothing debug-message server-shell + templates block-macros expressions + everything + + or their numeric equivalent. + + This option will cause AutoGen to display a trace of its template +processing. There are six levels, each level including messages from +the previous levels: + +`nothing' + Does no tracing at all (default) + +`debug-message' + Print messages from the "DEBUG" AutoGen macro (*note DEBUG::). + +`server-shell' + Traces all input and output to the server shell. This includes a + shell "independent" initialization script about 30 lines long. + Its output is discarded and not inserted into any template. + +`templates' + Traces the invocation of `DEFINE'd macros and `INCLUDE's + +`block-macros' + Traces all block macros. The above, plus `IF', `FOR', `CASE' and + `WHILE'. + +`expressions' + Displays the results of expression evaluations. + +`everything' + Displays the invocation of every AutoGen macro, even `TEXT' macros + (i.e. the text outside of macro quotes). Additionally, if you + rebuild the "expr.ini" file with debugging enabled, then all calls + to AutoGen defined scheme functions will also get logged: + cd ${top_builddir}/agen5 + DEBUG_ENABLED=true bash bootstrap.dir expr.ini + make CFLAGS='-g -DDEBUG_ENABLED=1' + + Be aware that you cannot rebuild this source in this way without + first having installed the `autogen' executable in your search + path. Because of this, "expr.ini" is in the distributed source + list, and not in the dependencies. + +trace-out option. +----------------- + +This is the "tracing output file or filter" option. This option takes +an argument string `file'. The output specified may be a file name, a +file that is appended to, or, if the option argument begins with the +`pipe' operator (`|'), a command that will receive the tracing output +as standard in. For example, `--traceout='| less'' will run the trace +output through the `less' program. Appending to a file is specified by +preceeding the file name with two greater-than characters (`>>'). + +show-defs option. +----------------- + +This is the "show the definition tree" option. + +This option has some usage constraints. It: + * must be compiled in by defining `DEBUG_ENABLED' during the + compilation. + + * may not be preset with environment variables or configuration + (rc/ini) files. + + This will print out the complete definition tree before processing +the template. + +used-defines option. +-------------------- + +This is the "show the definitions used" option. + +This option has some usage constraints. It: + * may not be preset with environment variables or configuration + (rc/ini) files. + + This will print out the names of definition values searched for +during the processing of the template, whether actually found or not. +There may be other referenced definitions in a template in portions of +the template not evaluated. Some of the names listed may be computed +names and others AutoGen macro arguments. This is not a means for +producing a definitive, all-encompassing list of all and only the +values used from a definition file. This is intended as an aid to +template documentation only. + +core option (-C). +----------------- + +This is the "leave a core dump on a failure exit" option. + +This option has some usage constraints. It: + * must be compiled in by defining `HAVE_SYS_RESOURCE_H' during the + compilation. + + Many systems default to a zero sized core limit. If the system has +the sys/resource.h header and if this option is supplied, then in the +failure exit path, autogen will attempt to set the soft core limit to +whatever the hard core limit is. If that does not work, then an +administrator must raise the hard core size limit. + + +File: autogen.info, Node: autogen processing, Next: autogen dep-track, Prev: autogen debug-tpl, Up: autogen Invocation + +5.5 processing options +====================== + +These options can be used to control what gets processed in the +definitions files and template files. They specify which outputs and +parts of outputs to produce. + +skip-suffix option (-s). +------------------------ + +This is the "omit the file with this suffix" option. This option takes +an argument string `suffix'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + * may not be preset with environment variables or configuration + (rc/ini) files. + + * must not appear in combination with any of the following options: + select-suffix. + + Occasionally, it may not be desirable to produce all of the output +files specified in the template. (For example, only the `.h' header +file, but not the `.c' program text.) To do this specify +`--skip-suffix=c' on the command line. + +select-suffix option (-o). +-------------------------- + +This is the "specify this output suffix" option. This option takes an +argument string `suffix'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + * may not be preset with environment variables or configuration + (rc/ini) files. + + If you wish to override the suffix specifications in the template, +you can use one or more copies of this option. See the suffix +specification in the *note pseudo macro:: section of the info doc. + +define option (-D). +------------------- + +This is the "name to add to definition list" option. This option takes +an argument string `value'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + The AutoGen define names are used for the following purposes: + + 1. Sections of the AutoGen definitions may be enabled or disabled by + using C-style #ifdef and #ifndef directives. + + 2. When defining a value for a name, you may specify the index for a + particular value. That index may be a literal value, a define + option or a value #define-d in the definitions themselves. + + 3. The name of a file may be prefixed with `$NAME/'. The `$NAME' + part of the name string will be replaced with the define-d value + for `NAME'. + + 4. When AutoGen is finished loading the definitions, the defined + values are exported to the environment with, `putenv(3)'. These + values can then be used in shell scripts with `${NAME}' references + and in templates with `(getenv "NAME")'. + + 5. While processing a template, you may specify an index to retrieve + a specific value. That index may also be a define-d value. + + It is entirely equivalent to place this name in the exported +environment. Internally, that is what AutoGen actually does with this +option. + +undefine option (-U). +--------------------- + +This is the "definition list removal pattern" option. This option +takes an argument string `name-pat'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + * may not be preset with environment variables or configuration + (rc/ini) files. + + Similar to 'C', AutoGen uses `#ifdef/#ifndef' preprocessing +directives. This option will cause the matching names to be removed +from the list of defined values. + + +File: autogen.info, Node: autogen dep-track, Next: autogen config, Prev: autogen processing, Up: autogen Invocation + +5.6 dep-track options +===================== + +This option is used to automate dependency tracking. + +make-dep option (-M). +--------------------- + +This is the "emit make dependency file" option. This option takes an +optional argument string `type'. + +This option has some usage constraints. It: + * may appear an unlimited number of times. + + * may not be preset with environment variables or configuration + (rc/ini) files. + + This option behaves fairly closely to the way the `-M' series of +options work with the gcc compiler, except that instead of just +emitting the predecessor dependencies, this also emits the successor +dependencies (output target files). By default, the output dependency +information will be placed in `<base-name>.d', but may also be +specified with `-MF<file>'. The time stamp on this file will be +manipulated so that it will be one second older than the oldest primary +output file. + + The target in this dependency file will normally be the dependency +file name, but may also be overridden with `-MT<targ-name>'. AutoGen +will not alter the contents of that file, but it may create it and it +will adjust the modification time to match the start time. + + *NB:* these second letters are part of the option argument, so `-MF +<file>' must have the space character quoted or omitted, and `-M "F +<file>"' is acceptable because the `F' is part of the option argument. + + `-M' may be followed by any of the letters M, F, P, T, Q, D, or G. +However, only F, Q, T and P are meaningful. All but F have somewhat +different meanings. `-MT<name>' is interpreted as meaning `<name>' is +a sentinel file that will depend on all inputs (templates and +definition files) and all the output files will depend on this sentinel +file. It is suitable for use as a real make target. Q is treated +identically to T, except dollar characters ('$') are doubled. P causes +a special clean (clobber) phoney rule to be inserted into the make file +fragment. An empty rule is always created for building the list of +targets. + + This is the recommended usage: + -MFwhatever-you-like.dep -MTyour-sentinel-file -MP + and then in your `Makefile', make the `autogen' rule: + -include whatever-you-like.dep + clean_targets += clean-your-sentinel-file + + your-sentinel-file: + autogen -MT$@ -MF$*.d ..... + + local-clean : + rm -f $(clean_targets) + + The modification time on the dependency file is adjusted to be one +second before the earliest time stamp of any other output file. +Consequently, it is suitable for use as the sentinel file testifying to +the fact the program was successfully run. (`-include' is the GNU make +way of specifying "include it if it exists". Your make must support +that feature or your bootstrap process must create the file.) + + All of this may also be specified using the `DEPENDENCIES_OUTPUT' or +`AUTOGEN_MAKE_DEP' environment variables. If defined, dependency +information will be output. If defined with white space free text that +is something other than `true', `false', `yes', `no', `0' or `1', then +the string is taken to be an output file name. If it contains a string +of white space characters, the first token is as above and the second +token is taken to be the target (sentinel) file as `-MT' in the +paragraphs above. `DEPENDENCIES_OUTPUT' will be ignored if there are +multiple sequences of white space characters or if its contents are, +specifically, `false', `no' or `0'. + + +File: autogen.info, Node: autogen config, Next: autogen exit status, Prev: autogen dep-track, Up: autogen Invocation + +5.7 presetting/configuring autogen +================================== + +Any option that is not marked as not presettable may be preset by +loading values from configuration ("rc" or "ini") files, and values +from environment variables named `AUTOGEN' and `AUTOGEN_<OPTION_NAME>'. +`<OPTION_NAME>' must be one of the options listed above in upper case +and segmented with underscores. The `AUTOGEN' variable will be +tokenized and parsed like the command line. The remaining variables +are tested for existence and their values are treated like option +arguments. + +`libopts' will search in 2 places for configuration files: + * $HOME + + * $PWD + The environment variables `HOME', and `PWD' are expanded and +replaced when `autogen' runs. For any of these that are plain files, +they are simply processed. For any that are directories, then a file +named `.autogenrc' is searched for within that directory and processed. + + Configuration files may be in a wide variety of formats. The basic +format is an option name followed by a value (argument) on the same +line. Values may be separated from the option name with a colon, equal +sign or simply white space. Values may be continued across multiple +lines by escaping the newline with a backslash. + + Multiple programs may also share the same initialization file. +Common options are collected at the top, followed by program specific +segments. The segments are separated by lines like: + [AUTOGEN] + or by + <?program autogen> + Do not mix these styles within one configuration file. + + Compound values and carefully constructed string values may also be +specified using XML syntax: + <option-name> + <sub-opt>...<...>...</sub-opt> + </option-name> + yielding an `option-name.sub-opt' string value of + "...<...>..." + `AutoOpts' does not track suboptions. You simply note that it is a +hierarchicly valued option. `AutoOpts' does provide a means for +searching the associated name/value pair list (see: optionFindValue). + + The command line options relating to configuration and/or usage help +are: + +version (-v) +------------ + +Print the program version to standard out, optionally with licensing +information, then exit 0. The optional argument specifies how much +licensing detail to provide. The default is to print just the version. +The licensing infomation may be selected with an option argument. Only +the first letter of the argument is examined: + +`version' + Only print the version. This is the default. + +`copyright' + Name the copyright usage licensing terms. + +`verbose' + Print the full copyright usage licensing terms. + +usage (-u) +---------- + +Print abbreviated usage to standard out, then exit 0. + +reset-option (-R) +----------------- + +Resets the specified option to the compiled-in initial state. This +will undo anything that may have been set by configuration files. The +option argument may be either the option flag character or its long +name. + + +File: autogen.info, Node: autogen exit status, Next: autogen Examples, Prev: autogen config, Up: autogen Invocation + +5.8 autogen exit status +======================= + +One of the following exit values will be returned: +`0 (EXIT_SUCCESS)' + Successful program execution. + +`1 (EXIT_OPTION_ERROR)' + The command options were misconfigured. + +`2 (EXIT_BAD_TEMPLATE)' + An error was encountered processing the template. + +`3 (EXIT_BAD_DEFINITIONS)' + The definitions could not be deciphered. + +`4 (EXIT_LOAD_ERROR)' + An error was encountered during the load phase. + +`5 (EXIT_SIGNAL)' + Program exited due to catching a signal. If your template includes + string formatting, a number argument to a "%s" formatting element + will trigger a segmentation fault. Autogen will catch the seg + fault signal and exit with `AUTOGEN_EXIT_SIGNAL(5)'. + Alternatively, AutoGen may have been interrupted with a `kill(2)' + signal. + +`66 (EX_NOINPUT)' + A specified configuration file could not be loaded. + +`70 (EX_SOFTWARE)' + libopts had an internal operational error. Please report it to + autogen-users@lists.sourceforge.net. Thank you. + + +File: autogen.info, Node: autogen Examples, Prev: autogen exit status, Up: autogen Invocation + +5.9 autogen Examples +==================== + +Here is how the man page is produced: + autogen -Tagman-cmd.tpl -MFman-dep -MTstamp-man opts.def + + This command produced this man page from the AutoGen option +definition file. It overrides the template specified in `opts.def' +(normally `options.tpl') and uses `agman-cmd.tpl'. It also sets the +make file dependency output to `man-dep' and the sentinel file (time +stamp file) to `man-stamp'. The base of the file name is derived from +the defined `prog-name'. + + The texi invocation document is produced via: + autogen -Tagtexi-cmd.tpl -MFtexi-dep -MTtexi-stamp opts.def + + +File: autogen.info, Node: Installation, Next: AutoOpts, Prev: autogen Invocation, Up: Top + +6 Configuring and Installing +**************************** + +* Menu: + +* configuring:: Configuring AutoGen +* AutoGen CGI:: AutoGen as a CGI server +* signal names:: Signal Names +* installing:: Installing AutoGen + + +File: autogen.info, Node: configuring, Next: AutoGen CGI, Up: Installation + +6.1 Configuring AutoGen +======================= + +AutoGen is configured and built using Libtool, Automake and Autoconf. +Consequently, you can install it wherever you wish using the various +`--prefix' options. To the various configuration options supplied by +these tools, AutoGen adds a few of its own: + +`--disable-shell' + AutoGen is now capable of acting as a CGI forms server, *Note + AutoGen CGI::. As such, it will gather its definitions using + either `GET' or `POST' methods. All you need to do is have a + template named `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 "``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. + + * Many of the make check tests will fail, since they assume a + working server shell. + + * 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. + + * Similarly, the documentation cannot be regenerated because + the documentation templates depend on subshell functionality. + +`--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. `cd' into the + `agen5' build directory, `make' the `autogen.texi' file and all + will be well thereafter. + +`--with-regex-header' +`--with-header-path' +`--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 + `--with-regex-header=value' must be the name of the relevant header + file. The AutoGen sources will attempt to include that source with + a `#include <value>' C preprocessing statement. The `path' from + the `--with-header-path=path' will be added to `CPPFLAGS' as + `-Ipath'. The `lib-specs' from `--with-regex-lib=lib-specs' will + be added to `LDFLAGS' without any adornment. + + +File: autogen.info, Node: AutoGen CGI, Next: signal names, Prev: configuring, Up: Installation + +6.2 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 `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 (*note Definitions File::) and the template named +"`cgi.tpl'" will be processed. + + This works by including the name of the real template to process in +the form data and having the "`cgi.tpl'" template include that template +for processing. I do this for processing the form +`http://autogen.sourceforge.net/conftest.html'. The "`cgi.tpl'" looks +approximately like this: + + <? AutoGen5 Template ?> + <? + IF (not (exist? "template")) ?><? + form-error ?><? + + ELIF (=* (get "template") "/") ?><? + form-error ?><? + + ELIF (define tpl-file (string-append "cgi-tpl/" + (get "template"))) + (access? tpl-file R_OK) ?><? + INCLUDE (. tpl-file) ?><? + + ELIF (set! tpl-file (string-append tpl-file ".tpl")) + (access? tpl-file R_OK) ?><? + INCLUDE (. tpl-file) ?><? + + ELSE ?><? + form-error ?><? + ENDIF ?> + +This forces the template to be found in the "`cgi-tpl/'" directory. +Note also that there is no suffix specified in the pseudo macro (*note +pseudo macro::). That tells AutoGen to emit the output to `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. + + *Please also note* that it is advisable, _especially_ for network +accessible machines, to configure AutoGen (*note configuring::) with +shell processing disabled (`--disable-shell'). That will make it +impossible for any referenced template to hand data to a subshell for +interpretation. + + +File: autogen.info, Node: signal names, Next: installing, Prev: AutoGen CGI, Up: Installation + +6.3 Signal Names +================ + +When AutoGen is first built, it tries to use `psignal(3)', +`sys_siglist', `strsigno(3)' and `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: + + 1. Build and install AutoGen in a place where it will be found in your + search path. + + 2. `cd ${top_srcdir}/compat' + + 3. `autogen strsignal.def' + + 4. Verify the results by examining the `strsignal.h' file produced. + + 5. Re-build and re-install AutoGen. + + 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 `strsignal.def' that tries to hunt down the information. + + +File: autogen.info, Node: installing, Prev: signal names, Up: Installation + +6.4 Installing AutoGen +====================== + +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 `$prefix'. +You can, of course, use `configure' to place these files where you wish. + + *NB* AutoGen does not contain any compiled-in path names. All +support directories are located via option processing, the environment +variable `HOME' or finding the directory where the executable came from. + + The installed files are: + + 1. The executables in `bin' (autogen, getdefs and columns). + + 2. The AutoOpts link libraries as `lib/libopts.*'. + + 3. An include file in `include/options.h', needed for Automated + Option Processing (see next chapter). + + 4. Several template files and a scheme script in `share/autogen', + needed for Automated Option Processing (*note AutoOpts::), parsing + definitions written with scheme syntax (*note Dynamic Text::), the + templates for producing documentation for your program (*note + documentation attributes::), autoconf test macros, and AutoFSM. + + 5. Info-style help files as `info/autogen.info*'. These files + document AutoGen, the option processing library AutoOpts, and + several add-on components. + + 6. The three man pages for the three executables are installed in + man/man1. + + This program, library and supporting files can be installed with +three commands: + + * <src-dir>/configure [ <configure-options> ] + + * make + + * make install + + However, you may wish to insert `make check' before the `make +install' command. + + If you do perform a `make check' and there are any failures, you +will find the results in `<module>/test/FAILURES'. Needless to say, I +would be interested in seeing the contents of those files and any +associated messages. If you choose to go on and analyze one of these +failures, you will need to invoke the test scripts individually. You +may do so by specifying the test (or list of test) in the TESTS make +variable, thus: + + gmake TESTS=test-name.test check + + I specify `gmake' because most makes will not let you override +internal definitions with command line arguments. `gmake' does. + + All of the AutoGen tests are written to honor the contents of the +VERBOSE environment variable. Normally, any commentary generated +during a test run is discarded unless the VERBOSE environment variable +is set. So, to see what is happening during the test, you might invoke +the following with bash or ksh: + + VERBOSE=1 gmake TESTS="for.test forcomma.test" check + +Or equivalently with csh: + + env VERBOSE=1 gmake TESTS="for.test forcomma.test" check + + +File: autogen.info, Node: AutoOpts, Next: Add-Ons, Prev: Installation, Up: Top + +7 Automated Option Processing +***************************** + +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. + + 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 + + +File: autogen.info, Node: Features, Next: Licensing, Up: AutoOpts + +7.1 AutoOpts 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 *note Option Definitions:: section. + + 1. POSIX-compliant short (flag) option processing. + + 2. GNU-style long options processing. Long options are recognized + without case sensitivity, and they may be abbreviated. + + 3. Environment variable initializations, *Note environrc::. + + 4. Initialization from configuration files (aka RC or INI files), and + saving the option state back into one, *Note loading rcfile::. + + 5. Config files may be partitioned. One config file may be used by + several programs by partitioning it with lines containing, + "`[PROGRAM_NAME]'" or "`<?program-name>'", *Note loading rcfile::. + + 6. Config files may contain AutoOpts directives. "`<?auto-options + [[option-text]]>'" may be used to set `AutoOpts' option processing + options. Viz., `GNU' usage layout versus `AutoOpts' conventional + layout, and `misuse-usage' versus `no-misuse-usage', *Note usage + attributes::. + + 7. Options may be marked as `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., + `--allow-mumble' and `--prevent-mumble' (*note Common + Attributes::). + + 8. 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 *Note Common Attributes::, and + *Note Option Conflict Attributes::. + + 9. There are several *note automatically supported options: automatic + 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 "`xxx-value;'" in the option definition file. + "`xxx'" is the name of the option below: + + `--help' + `--more-help' + These are always available. `--more-help' will pass the full + usage text through a pager. + + `--usage' + This is added to the option list if `usage-opt' is specified. + It yields the abbreviated usage to `stdout'. + + `--version' + This is added to the option list if `version = xxx;' is + specified. + + `--load-opts' + `--save-opts' + These are added to the option list if `homerc' is specified. + Mostly. If, `disable-save' is specified, then `--save-opts' + is disabled. + + 10. Various forms of main procedures can be added to the output, *Note + Generated main::. There are four basic forms: + + a. A program that processes the arguments and writes to standard + out portable shell commands containing the digested options. + + b. 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. + + c. 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. + + d. A main procedure of your own design. Its code can be + supplied in the option description template or by + incorporating another template. + + 11. There are several methods for handling option arguments. + * nothing (*note OPT_ARG::) option argument strings are + globally available. + + * user supplied (*note Option Argument Handling::) + + * stack option arguments (*note Option Argument Handling::) + + * integer numbers (*note arg-type number::) + + * true or false valued (*note arg-type boolean::) + + * enumerated list of names (*note arg-type keyword::) + + * an enumeration (membership) set (*note arg-type set + membership::) + + * a list of name/value pairs (option "subopts") (*note arg-type + hierarchy::) + + * a time duration or a specific time and date + + * validated file name (*note arg-type file name::) + + * optional option argument (*note arg-optional::) + + 12. 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 `gnu-usage' attribute (*note information + attributes::). This can be overridden by the user himself with the + `AUTOOPTS_USAGE' environment variable. If it exists and is set to + the string `gnu', it will force GNU-ish style format; if it is set + to the string `autoopts', it will force AutoOpts standard format; + otherwise, it will have no effect. + + 13. The usage text and many other strings are stored in a single + character array (*note string table functions: SCM + string-table-new.). 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, `embedded '\0' in format'. To eliminate the warning, you + must provide GCC with the `-Wno-format-contains-nul' option. + + 14. If you compile with `ENABLE_NLS' defined and `_()' defined to a + localization function (e.g. `gettext(3GNU)'), then the option + processing code will be localizable (*note i18n::). Provided also + that you do not define the `no-xlate' attribute to _anything_ + (*note presentation attributes::). + + 15. 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. + + 16. By adding a `doc' and `arg-name' attributes to each option, + AutoGen will also be able to produce a man page and the `invoking' + section of a texinfo document. + + 17. 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 + `allow-errors' (*note program attributes::) attribute. When + processing reaches a point where `optionProcess' (*note + libopts-optionProcess::) needs to be called again, the current + option can be set with `RESTART_OPT(n)' (*note RESTART_OPT::) + before calling `optionProcess'. + + See: *Note library attributes::. + + 18. Library suppliers can specify command line options that their + client programs will accept. They specify option definitions that + get `#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. + + 19. 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 `#include' into their own + option definitions. See "AutoOpt-ed Library for AutoOpt-ed + Program" (*note lib and program::) for more details. + + +File: autogen.info, Node: Licensing, Next: Caveats, Prev: Features, Up: AutoOpts + +7.2 AutoOpts 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 (`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 `libopts' source tarball. This source may be +incorporated into your package with the following simple commands: + + rm -rf libopts libopts-* + gunzip -c `autoopts-config libsrc` | \ + tar -xvf - + mv libopts-*.*.* libopts + + View the `libopts/README' file for further integration information. + + +File: autogen.info, Node: Caveats, Next: Quick Start, Prev: Licensing, Up: AutoOpts + +7.3 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: + + gnu-usage; + no-misuse-usage; + + Users may also override these settings with the `AUTOOPTS_USAGE' +environment variable. It may be set to a comma or white space separated +list of the following strings: + +`gnu' + The format of the extended usage text will be displayed in + GNU-normal form. The default display for `--version' will be to + include a note on licensing terms. + +`autoopts' + The format of the extended usage will be in AutoOpts' native + layout. + +`no-misuse-usage' + When an option error is made on the command line, the abbreviated + usage text will be suppressed. + +`misuse-usage' + When an option error is made on the command line, the abbreviated + usage text will be shown. + +The setting used is the last one seen. The `autoopts' and +`misuse-usage' serve no purpose, unless the definition file entries +were specified as above. + + 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 `#define' macros +such as this: + #define DESC(n) (autogenOptions.pOptDesc[INDEX_OPT_## n]) + and expect `DESC(DEBUG)' to expand correctly into +`(autogenOptions.pOptDesc[INDEX_OPT_DEBUG])'. If `DEBUG' is `#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 `guard-option-names' *Note program +attributes::. + + +File: autogen.info, Node: Quick Start, Next: Option Definitions, Prev: Caveats, Up: AutoOpts + +7.4 Quick Start +=============== + +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 `columns', `getdefs' and +`autogen' itself. + + For our simple example, assume you have a program named `check' that +takes two options: + + 1. A list of directories to check over for whatever it is `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. + + 2. An option to show or not show the definition tree being used. + Only one occurrence is to be allowed, specifying one or the other. + +First, specify your program attributes and its options to AutoOpts, as +with the following 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.'; + }; + +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: + + 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 + +Running those commands yields: + + check - Checkout Automated Options + USAGE: check [ -<flag> [<val>] | --<name>[{=| }<val>] ]... + + -L, --check-dirs=str Checkout directory list + - may appear multiple times + --show-defs Show the definition tree + - disabled as --dont-show-defs + -?, --help Display extended usage information and exit + -!, --more-help Extended usage information passed thru pager + + Options are specified by doubled hyphens and their name or by a single + hyphen and the flag character. + Packaged by Bruce (2012-08-11) + Report check bugs to bkorb@gnu.org + +Normally, however, you would not use the "main" clause. Instead, the +file would be named something like `checkopt.def', you would compile +`checkopt.c' the usual way, and link the object with the rest of your +program. + + The options are processed by calling `optionProcess' (*note +libopts-optionProcess::): + + main( int argc, char** argv ) + { + { + int optct = optionProcess( &checkOptions, argc, argv ); + argc -= optct; + argv += optct; + } + + The options are tested and used as in the following fragment. +"`ENABLED_OPT'" is used instead of "`HAVE_OPT'" for the `show-defs' +option because it is an enabled/disabled option type: + + 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++; + ... + + 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 +`check.1' and `invoke-check.texi'. The latter file will be generated +as a chapter, rather than a section or subsection. + + autogen -Tagman-cmd check.def + autogen -DLEVEL=chapter -Tagtexi-cmd -binvoke-check.texi check.def + +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. + + +File: autogen.info, Node: Option Definitions, Next: AutoOpts API, Prev: Quick Start, Up: AutoOpts + +7.5 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 (*note Quick Start::) and paying attention to the +following: + + 1. `prog-name', `prog-title', and `argument', program attributes, + *Note program attributes::. + + 2. `name' and `descrip' option attributes, *Note Required + Attributes::. + + 3. `value' (flag character) and `min' (occurrence counts) option + attributes, *Note Common Attributes::. + + 4. `arg-type' from the option argument specification section, *Note + Option Arguments::. + + 5. Read the overall how to, *Note Using AutoOpts::. + + 6. Highly recommended, but not required, are the several "man" and + "info" documentation attributes, *Note documentation attributes::. + + 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 + + +File: autogen.info, Node: program attributes, Next: library attributes, Up: Option Definitions + +7.5.1 Program Description 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: + +`prog-name' + This attribute is required. Variable names derived from this name + are derived using `string->c_name!' (*note SCM string->c-name!::). + +`prog-title' + This attribute is required and may be any descriptive text. + +`argument' + This attribute is required if your program uses operand arguments. + It specifies the syntax of the arguments that *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 (`['), 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 *not* consume all of the + command line arguments. + +`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. + +* Menu: + +* usage attributes:: Usage and Version Info Display +* config attributes:: Program Configuration +* programming attributes:: Programming Details +* presentation attributes:: User Presentation Attributes + + +File: autogen.info, Node: usage attributes, Next: config attributes, Up: program attributes + +7.5.1.1 Usage and Version Info Display +...................................... + +These will affect the way usage is seen and whether or not version +information gets displayed. + +`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. + * If not provided, the text will be computed as normal. + + * 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. + + * 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. + + * 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. + + This string should be readily translatable. Provision will be made + to translate it if this is provided, if the source code is + compiled with `ENABLE_NLS' defined, and `no-xlate' has not been + set to the value _anything_. + +`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. + +`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 `AUTOOPTS_USAGE' environment variable used to + request `autoopts' layout. See *Note Developer and User Notes: + Caveats. + +`usage-opt' + I apologize for too many confusing usages of usage. This + attribute specifies that `--usage' and/or `-u' be supported. The + help (usage) text displayed will be abbreviated when compared to + the default help text. + +`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 `AUTOOPTS_USAGE' + environment variable. See *Note Developer and User Notes: Caveats. + +`prog-group' + The version text in the `getopt.tpl' template will include this + text in parentheses after the program name, when this attribute is + specified. For example: + mumble (stumble) 1.0 + says that the "`mumble'" program is version 1.0 and is part of the + "`stumble'" group of programs. + +`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 `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 `endwin()' + before invoking the library function `optionUsage()'. This can be + handled by specifying your own usage function, thus: + void + my_usage(tOptions * opts, int ex) + { + if (curses_window_active) + endwin(); + optionUsage(opts, ex); + } + +`version' + Specifies the program version and activates the VERSION option, + *Note automatic options::. + + +File: autogen.info, Node: config attributes, Next: programming attributes, Prev: usage attributes, Up: program attributes + +7.5.1.2 Program Configuration +............................. + +Programs may be "pre-configured" before normal command line options are +processed (See *note Immediate Action Attributes: Immediate Action.). +How configuration files and environment variables are handled get +specified with these attributes. + +`disable-load' +`disable-save' + Indicates that the command line usage of `--load-opts' and/or + `--save-opts' are disallowed. + +`environrc' + Indicates looking in the environment for values of variables named, + `PROGRAM_OPTNAME' or `PROGRAM', where `PROGRAM' is the upper cased + `C-name' of the program and `OPTNAME' is the upper cased `C-name' + of a specific option. The contents of the `PROGRAM' variable, if + found, are tokenized and processed. The contents of + `PROGRAM_OPTNAME' environment variables are taken as the option + argument to the option nameed `optname'. + +`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 `homerc' value is not the dollar + character (`$'), then it is presumed to be a path name based on the + current directory. Otherwise, the method depends on the second + character: + + `$' + The path is relative to the directory where the executable + was found. + + `@' + The path is relative to the package data directory, e.g. + `/usr/local/share/autogen'. + + `[a-zA-Z]' + The path is derived from the named environment variable. + + Use as many as you like. The presence of this attribute activates + the `--save-opts' and `--load-opts' options. However, saving into + a file may be disabled with the `disable-save'. *Note loading + rcfile::. See the `optionMakePath(3AGEN)' man page for + excruciating details. + +`rcfile' + Specifies the configuration file name. This is only useful if you + have provided at least one `homerc' attribute. + default: .<prog-name>rc + +`vendor-opt' + This option implements the `-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 `-W' command line options, the short flag form. Long option + name processing must be disabled. In fact, the `long-opts' + attribute must not be provided, and some options must be specified + without flag values. + + The `-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 `--long-name' were found on the + command line. + + +File: autogen.info, Node: programming attributes, Next: presentation attributes, Prev: config attributes, Up: program attributes + +7.5.1.3 Programming Details +........................... + +These attributes affect some of the ways that the option data are used +and made available to the program. + +`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. + +`exit-name' +`exit-desc' + These values should be defined as indexed values, thus: + 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.'; + 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 + `getdefs': + typedef enum { + GETDEFS_EXIT_SUCCESS = 0, + GETDEFS_EXIT_FAILURE = 1 + } getdefs_exit_code_t; + which will be augmented by any `exit-name' definitions beyond "1". + +`usage-message' + This attribute will cause two procedures to be added to the code + file: `usage_message' and `vusage_message', with any applicable + prefix (see `prefix', below). They are declared in the generated + header, thus: + extern void vusage_message(char const * fmt, va_list ap); + extern void usage_message(char const * fmt, ...); + These functions print the message to `stderr' and invoke the usage + function with the exit code set to `1' (`EXIT_FAILURE'). + +`die-code' + This tells AutoOpts templates to emit code for `vdie', `die' and + `fserr' functions. If the `die-code' is assigned a text value, + then that code will be inserted in the `vdie' function immediately + before it prints the death rattle message. + + The profiles for these functions are: + 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); + +`export' + This string is inserted into the .h interface file. Generally + used for global variables or `#include' directives required by + `flag-code' text and shared with other program text. Do not + specify your configuration header (`config.h') in this attribute + or the `include' attribute, however. Instead, use + `config-header', above. + +`guard-option-names' + AutoOpts generates macros that presume that there are no `cpp' + macros with the same name as the option name. For example, if you + have an option named, `debug', then you must not use `#ifdef + DEBUG' in your code. If you specify this attribute, every option + name will be guarded. If the name is `#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: + + * Not defined. AutoOpts will behave as described above. + + * Defined, but set to the empty string. Text will be emitted + into the header to undefine (`#undef') any conflicting + preprocessor macros. The code will include compiler warnings + (via `#warning'). Some compilers are not ANSI-C-99 compliant + yet and will error out on those warnings. You may compile + with `-DNO_OPTION_NAME_WARNINGS' to silence or mostly silence + them. + + * Defined and set to the string, "`no-warning'". All of the + needed `#undef's will be emitted, without any conflict + checking `#warning' directives emitted. + + * Defined and set to the string, "`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 `HAVE_OPT(INDEX_OPT_DEBUG)' instead of + `HAVE_OPT(DEBUG)'. + +`include' + This string is inserted into the .c file. Generally used for + global variables required only by `flag-code' program text. + +`no-libopts' + If you are going to handle your option processing with the + `getopt.tpl' template instead of using libopts, then specify this + attribute. It will suppress mention of `--more-help' in the + generated documentation. (`getopt_long' does not support + `--more-help'.) + +`prefix' + This value is inserted into *all* global names. This will + disambiguate them if more than one set of options are to be + compiled into a single program. + + +File: autogen.info, Node: presentation attributes, Prev: programming attributes, Up: program attributes + +7.5.1.4 User Presentation Attributes +.................................... + +Attributes that affect the user's experience. + +`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 `ERRSKIP_OPTERR' and `ERRSTOP_OPTERR' from the generated + interface file. + +`long-opts' + 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 `long-opts'. If none of your options specify an option + value (flag character) and you do not specify `long-opts', then + command line arguments are processed in "named option mode". This + means that: + + * Every command line argument must be a long option. + + * The flag markers `-' and `--' are completely optional. + + * The `argument' program attribute is disallowed. + + * One of the options may be specified as the default (as long + as it has a required option argument). + +`no-xlate' + Modifies when or whether option names get translated. If provided, + it must be assigned one of these values: + `opt-cfg' + to suppress option name translation for configuration file + and and environment variable processing. + + `opt' + to suppress option name translation completely. The usage + text will always be translated if `ENABLE_NLS' is defined and + you have translations for that text. + + `anything' + Specifies disabling all internationalization support for + option code, completely. + See also the various `XLAT' interface entries in the AutoOpts + Programmatic Interface section (*note AutoOpts API::). + +`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: + * Allow `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 `RESTART_OPT' macro (see + *note RESTART_OPT::), and re-invoke `optionProcess'. This + will also allow you to process the operands in context. + + * 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. + +`resettable' + Specifies that the `--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. + + +File: autogen.info, Node: library attributes, Next: information attributes, Prev: program attributes, Up: Option Definitions + +7.5.2 Options for Library Code +------------------------------ + +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 + + +File: autogen.info, Node: lib and program, Next: lib called, Up: library attributes + +7.5.2.1 AutoOpt-ed Library for AutoOpt-ed Program +................................................. + +The library source code must provide an option definition file that +consists of only the attribute `library' and `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 `flag' entry must contain the following attributes: + +`name' + This name is used in the construction of a global pointer of type + `tOptDesc const*'. It is always required. + +`documentation' + It tells `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. + +`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. + +`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: + extern tOptDesc const* <<lib-name>>_<<name>>_optDesc_p; + and is used in the macros generated for the library's `.h' file. + + In order to compile this `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: + + 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 + +and nothing else. AutoGen will produce only the `.h' file. You may +now compile your library, referencing just this `.h' file. The macros +it creates will utilize a global variable that will be defined by the +`AutoOpts'-using client program. That program will need to have the +following `#include' in its option definition file: + + #include library-options-only.def + +All the right things will magically happen so that the global variables +named `<<lib-name>>_<<name>>_optDesc_p' are initialized correctly. For +an example, please see the `AutoOpts' test script: +`autoopts/test/library.test'. + + +File: autogen.info, Node: lib called, Next: prog calls lib, Prev: lib and program, Up: library attributes + +7.5.2.2 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 +`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: + + RESTART_OPT(next_arg_index); + +and then invoke `not_opt_index = optionProcess(...)'. The +`not_opt_index' value can be used to set `optind', if that is the +global being used to scan the program argument array. + + In this method, do *NOT* utilize the global `library' attribute. +Your library must specify its options as if it were a complete program. +You may choose to specify an alternate `usage()' function so that usage +for other parts of the option interface may be displayed as well. See +"Program Information Attributes" (*note information attributes::). + + At the moment, there is no method for calling `optionUsage()' telling +it to produce just the information about the options and not the program +as a whole. Some later revision after somebody asks. + + +File: autogen.info, Node: prog calls lib, Prev: lib called, Up: library attributes + +7.5.2.3 AutoOpt-ed Program Calls Regular Library +................................................ + +As with providing an `AutoOpt'-ed library to a non-`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 +`allow-errors' global option attribute and you will likely want an +alternate `usage()' function (see "Program Information Attributes" +*note information attributes::). In this case, though, when +`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 `RESTART_OPT()' macro, and recall +`optionProcess()'. Repeat until done. + + +File: autogen.info, Node: information attributes, Next: Generated main, Prev: library attributes, Up: Option Definitions + +7.5.3 Program Information Attributes +------------------------------------ + +These attributes are used to define how and what information is +displayed to the user of the program. + +`copyright' + The `copyright' is a structured value containing three to five + values. If `copyright' is used, then the first three are required. + + 1. `date' - the list of applicable dates for the copyright. + + 2. `owner' - the name of the copyright holder. + + 3. `type' - specifies the type of distribution license. + AutoOpts/AutoGen supports the text of the GNU Public License + (`gpl'), the GNU "Lesser" General Public License with Library + extensions (`lgpl'), the Modified Free BSD license (`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: + ls $(autoopts-config pkgdatadir)/*.lic + + 4. `text' - the text of the copyright notice. This must be + provided if `type' is set to `NOTE'. + + 5. `author' - in case the author name is to appear in the + documentation and is different from the copyright owner. + + 6. `eaddr' - email address for receiving praises and complaints. + Typically that of the author or copyright holder. + + An example of this might be: + copyright = { + date = "1992-2012"; + owner = "Bruce Korb"; + eaddr = 'bkorb@gnu.org'; + type = GPL; + }; + +`detail' + This string is added to the usage output when the HELP option is + selected. + +`explain' + Gives additional information whenever the usage routine is invoked. + +`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.: `autogen (GNU autogen) - The Automated Program + Generator'. + +`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. + +`prog-desc *and*' +`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 `settable'. + The library client program will invoke the `SET_OPTION' macro + which will invoke a handler function that will finally set these + global variables. + +`usage' + Optionally names the usage procedure, if the library routine + `optionUsage()' does not work for you. If you specify `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: + void my_usage( tOptions* pOptions, int exitCode ) + +`gnu-usage' + Normally, the default format produced by the `optionUsage' + procedure is AutoOpts Standard. By specifying this attribute, the + default format will be GNU-ish style. Either default may be + overridden by the user with the `AUTOOPTS_USAGE' environment + variable. If it is set to `gnu' or `autoopts', it will alter the + style appropriately. This attribute will conflict with the + `usage' attribute. + +`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 disabled if + `POSIXLY_CORRECT' is defined in the environment. + + +File: autogen.info, Node: Generated main, Next: option attributes, Prev: information attributes, Up: Option Definitions + +7.5.4 Generating main procedures +-------------------------------- + +When AutoOpts generates the code to parse the command line options, it +has the ability to produce any of several types of `main()' procedures. +This is done by specifying a global structured value for `main'. The +values that it contains are dependent on the value set for the one +value it must have: `main-type'. + + The recognized values for `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 + + Here is an example of an `include' variation: + + main = { + main-type = include; + tpl = "main-template.tpl"; + }; + + +File: autogen.info, Node: main guile, Next: main shell-process, Up: Generated main + +7.5.4.1 guile: main and inner_main procedures +............................................. + +When the `main-type' is specified to be `guile', a `main()' procedure +is generated that calls `gh_enter()', providing it with a generated +`inner_main()' to invoke. If you must perform certain tasks before +calling `gh_enter()', you may specify such code in the value for the `before-guile-boot' +attribute. + + The `inner_main()' procedure itself will process the command line +arguments (by calling `optionProcess()', *note +libopts-optionProcess::), and then either invoke the code specified +with the `guile-main' attribute, or else export the parsed options to +Guile symbols and invoke the `scm_shell()' function from the Guile +library. This latter will render the program nearly identical to the +stock `guile(1)' program. + + +File: autogen.info, Node: main shell-process, Next: main shell-parser, Prev: main guile, Up: Generated main + +7.5.4.2 shell-process: emit Bourne shell results +................................................ + +This will produce a `main()' procedure that parses the command line +options and emits to `stdout' Bourne shell commands that puts the +option state into environment variables. This can be used within a +shell script as follows: + + unset OPTION_CT + eval "`opt_parser \"$@\"`" + test -z "${OPTION_CT}" && exit 1 + test ${OPTION_CT} -gt 0 && shift ${OPTION_CT} + + 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 `stdout' and evaled: + + OPTION_CT=4 + export OPTION_CT + MYPROG_SECOND='first' + export MYPROG_SECOND + MYPROG_ANOTHER=1 # 0x1 + export MYPROG_ANOTHER + +If the arguments are to be reordered, however, then the resulting set +of operands will be emitted and `OPTION_CT' gets set to zero. For +example, the following would be appended to the above: + + set -- 'operand1' 'operand2' 'operand3' + OPTION_CT=0 + +`OPTION_CT' is set to zero since it is not necessary to shift off any +options. + + +File: autogen.info, Node: main shell-parser, Next: main main, Prev: main shell-process, Up: Generated main + +7.5.4.3 shell-parser: emit Bourne shell script +.............................................. + +This will produce a `main()' procedure that emits a shell script that +will parse the command line options. That script can be emitted to +`stdout' or inserted or substituted into a pre-existing shell script +file. Improbable markers are used to identify previously inserted +parsing text: + + # # # # # # # # # # -- do not modify this marker -- + +The program is also pretty insistent upon starting its parsing script +on the second line. + + +File: autogen.info, Node: main main, Next: main include, Prev: main shell-parser, Up: Generated main + +7.5.4.4 main: user supplied main procedure +.......................................... + +You must supply a value for the `main-text' attribute. You may also +supply a value for `option-code'. If you do, then the `optionProcess' +invocation will not be emitted into the code. AutoOpts will wrap the +`main-text' inside of: + + int + main( int argc, char** argv ) + { + { // replaced by option-code, if that exists + int ct = optionProcess( &<<prog-name>>Options, argc, argv ); + argc -= ct; + argv += ct; + } + <<your main-text goes here>> + } + +so you can most conveniently set the value with a "`here string'" +(*note here-string::): + + code = <<- _EndOfMainProc_ + <<your text goes here>> + _EndOfMainProc_; + + +File: autogen.info, Node: main include, Next: main invoke, Prev: main main, Up: Generated main + +7.5.4.5 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 `tpl' attribute and it will be +incorporated at the point where AutoOpts is ready to emit the `main()' +procedure. + + This can be very useful if, in your working environment, you have +many programs with highly similar `main()' procedures. All you need to +do is parameterize the variations and specify which variant is needed +within the `main' AutoOpts specification. Since you are coding the +template for this, the attributes needed for this variation would be +dictated by your template. + + +File: autogen.info, Node: main invoke, Next: main for-each, Prev: main include, Up: Generated main + +7.5.4.6 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 `func' +attribute to this `main()' procedure specification. Typically, this +template will be incorporated by using the `--lib-template' option +(*note autogen lib-template::) in the AutoGen invocation. Otherwise, +this variation operates in much the same way as "`include'" (*note main +include::) method. + + +File: autogen.info, Node: main for-each, Prev: main invoke, Up: Generated main + +7.5.4.7 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), *OR* once for each +non-blank, non-comment `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. + + *NB*: The `argument' program attribute (*note program attributes::) +must begin with the `[' character, to indicate that there are command +operands, but that they are optional. + + There are a number of attributes to `main' that may be used: + +`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 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 `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 *OR*-ed into a result integer for computing the + final exit code. E.g., here is part of the emitted code: + + int res = 0; + if (argc > 0) { + do { + res |= my_handler( *(argv++) ); + } while (--argc > 0); + } else { ... + +`handler-type' + If you do not supply this attribute, your handler procedure must be + the default type. The profile of the procedure must be: + + int my_handler( char const *pz_entry ); + + However, if you do supply this attribute, you may set the value to + any of four alternate flavors: + + `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. + + `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 + `fopen(3C)'. In this case, the profile for your procedure + must be: + + int my_handler( char const* pz_fname, FILE* entry_fp ); + + `text-of-file' + `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 `some-text-of-file' disallows empty + files. Both require regular files. In this case, the profile + for your procedure must be: + + program_exit_code_t + my_handler(char const* pz_fname, char* file_text, + size_t text_size); + + Note that though the `file_text' is not `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 `text_size + 1' bytes long and + the final byte is always `NUL'. The file contents need not + be text, as the data are read with the `read(2)' system call. + + If you select one of these file type handlers, then on access or + usage errors the `PROGRAM_EXIT_FAILURE' exit code will, by + default, be or-ed into the final exit code. This can be changed + by specifying the global `file-fail-code' attribute and naming a + different value. That is, something other than `failure'. You + may choose `success', in which case file access issues will not + affect the exit code and the error message will not be printed. + +`my_handler-code' + With this attribute, you provide the code for your handler + procedure in the option definition file. In this case, your + `main()' procedure specification might look something like this: + + main = { + main-type = for-each; + handler-proc = my_handler; + my_handler-code = <<- EndOfMyCode + /* whatever you want to do */ + EndOfMyCode; + }; + + and instead of an emitted external reference, a procedure will be + emitted that looks like this: + + static int + my_handler( char const* pz_entry ) + { + int res = 0; + <<my_handler-code goes here>> + return res; + } + +`main-init' + This is code that gets inserted after the options have been + processed, but before the handler procs get invoked. + +`main-fini' + This is code that gets inserted after all the entries have been + processed, just before returning from `main()'. + +`comment-char' + If you wish comment lines to start with a character other than a + hash (`#') character, then specify one character with this + attribute. If that character is the `NUL' byte, then only blank + lines will be considered comments. + + +File: autogen.info, Node: option attributes, Next: Option Arguments, Prev: Generated main, Up: Option Definitions + +7.5.5 Option Attributes +----------------------- + +For each option you wish to specify, you must have a block macro named +`flag' defined. There are two required attributes: `name' and +`descrip'. If any options do not have a `value' (traditional flag +character) attribute, then the `long-opts' program attribute must also +be defined. As a special exception, if no options have a `value' *and* +`long-opts' is not defined *and* `argument' is not defined, then all +arguments to the program are named options. In this case, the `-' and +`--' 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 + + +File: autogen.info, Node: Required Attributes, Next: Common Attributes, Up: option attributes + +7.5.5.1 Required Attributes +........................... + +Every option must have exactly one copy of both of these attributes. + +`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 `#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, `debug' or `munged-up', you + must not use the `#define' names `DEBUG' (or `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, `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: + + 1. Change the name of your option + + 2. add the program attribute (*note program attributes::): + + export = '#undef INTERFACE'; + + 3. add the program attribute: + + guard-option-names; + +`descrip' + Except for documentation options, a *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 `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. + + +File: autogen.info, Node: Common Attributes, Next: Immediate Action, Prev: Required Attributes, Up: option attributes + +7.5.5.2 Common Option Attributes +................................ + +These option attributes are optional. Any that do appear in the +definition of a flag, may appear only once. + +`value' + The flag character to specify for traditional option flags, e.g., + `-L'. + +`max' + Maximum occurrence count (invalid if DISABLE present). The + default maximum is 1. `NOLIMIT' can be used for the value, + otherwise it must be a number or a `#define' that evaluates to a + number. + +`min' + Minimum occurrence count. If present, then the option *must* + appear on the command line. Do not define it with the value zero + (0). + +`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. + +`deprecated' + There are two effects to this attribute: the usage text will not + show the option, and the generated documentation will mark it with: + "_NOTE: THIS OPTION IS DEPRECATED_". + +`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 `ENABLED_OPT(OPTNAME)' is false when either of + the following is true: + * The option has not been specified and the `enable' attribute + has not been specified. + + * The option has been specified with this disabling prefix. + To detect that the option has been specified with the disabling + prefix, you must use: + HAVE_OPT(OPTNAME) && ! ENABLED_OPT(OPTNAME) + +`enable' + Long-name prefix for enabling the option (invalid if DISABLE *not* + present). Only useful if long option names are being processed. + +`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. + +`ifdef' +`ifndef' +`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, `mumble' + that is indicated with the compile time define, `WITH_MUMBLING', + then add: + + ifdef = WITH_MUMBLING; + + Take care when using these. There are several caveats: + + * The case and spelling must match whatever is specified. + + * Do not confuse these attributes with the AutoGen directives + of the same names, *Note Directives::. These cause C + preprocessing directives to be inserted into the generated C + text. + + * Only one of `ifdef' and `ifndef' may apply to any one option. + + * The `VALUE_OPT_' values are `#define'-d. If `WITH_MUMBLING' + is not defined, then the associated `VALUE_OPT_' value will + not be `#define'-d either. So, if you have an option named, + `MUMBLING' that is active only if `WITH_MUMBLING' is + `#define'-d, then `VALUE_OPT_MUMBLING' will be `#define'-d + iff `WITH_MUMBLING' is `#define'-d. Watch those switch + statements. + + * If you specify `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 + `omitted-usage' a string value. e.g.: + omitted-usage = 'you cannot do this'; + +`no-command' + This option specifies that the option is not allowed on the + command line. Such an option may not take a `value' (flag + character) attribute. The program must have the `homerc' (*note + program attributes::) option set. + + +File: autogen.info, Node: Immediate Action, Next: Option Conflict Attributes, Prev: Common Attributes, Up: option attributes + +7.5.5.3 Immediate Action Attributes +................................... + +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 `--no-load-opts' *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 `homerc' file, followed by then next `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. + +`immediate' + Use this option attribute to specify that the enabled form of the + option is to be processed immediately. The `help' and `more-help' + options are so specified. They will also call `exit()' upon + completion, so they *do* have an effect on the processing of the + remaining options :-). + +`immed-disable' + Use this option attribute to specify that the disabled form of the + option is to be processed immediately. The `load-opts' option is + so specified. The `--no-load-opts' command line option will + suppress the processing of config files and environment variables. + Contrariwise, the `--load-opts' command line option is processed + normally. That means that the options specified in that file will + be processed after all the `homerc' files and, in fact, after + options that precede it on the command line. + +`also' + If either the `immediate' or the `immed-disable' attributes are + set to the string, "`also'", then the option will actually be + processed twice: first at the immediate processing phase and again + at the "normal" time. + + +File: autogen.info, Node: Option Conflict Attributes, Next: opt-attr settable, Prev: Immediate Action, Up: option attributes + +7.5.5.4 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. + +`flags-must' + one entry for every option that *must* be present when this option + is present + +`flags-cant' + one entry for every option that *cannot* be present when this + option is present + + +File: autogen.info, Node: opt-attr settable, Next: opt-attr no-preset, Prev: Option Conflict Attributes, Up: option attributes + +7.5.5.5 Program may set option +.............................. + +If the option can be set outside of option processing, specify +"`settable'". If this attribute is defined, special macros for setting +this particular option will be inserted into the interface file. For +example, `TEMPL_DIRS' is a settable option for AutoGen, so a macro named +`SET_OPT_TEMPL_DIRS(a)' appears in the interface file. This attribute +interacts with the DOCUMENTATION attribute. + + +File: autogen.info, Node: opt-attr no-preset, Next: opt-attr equivalence, Prev: opt-attr settable, Up: option attributes + +7.5.5.6 Option cannot be pre-configured +....................................... + +If presetting this option is not allowed, specify "`no-preset'". +(Thus, environment variables and values set in configuration files will +be ignored.) + + +File: autogen.info, Node: opt-attr equivalence, Next: opt-attr aliases, Prev: opt-attr no-preset, Up: option attributes + +7.5.5.7 Option Equivalence Class +................................ + +Generally, when several options are mutually exclusive and basically +serve the purpose of selecting one of several processing modes, specify +the "`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, +`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 (*note 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, +`cpio(1)' has three options `-o', `-i', and `-p' that define the +operational mode of the program (`create', `extract' and +`pass-through', respectively). They form an equivalence class from +which one and only one member must appear on the command line. If +`cpio' were an AutoOpt-ed program, then each of these option +definitions would contain: + + equivalence = create; + + and the program would be able to determine the operating mode with +code that worked something like this: + + switch (WHICH_IDX_CREATE) { + case INDEX_OPT_CREATE: ... + case INDEX_OPT_EXTRACT: ... + case INDEX_OPT_PASS_THROUGH: ... + default: /* cannot happen */ + } + + +File: autogen.info, Node: opt-attr aliases, Next: opt-attr default option, Prev: opt-attr equivalence, Up: option attributes + +7.5.5.8 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: + flag = { + name = aliasing-option-name; + value = aliasing-flag-char; // optional ! + aliases = aliased-to-option; + }; + Do not provide anything else. The usage text for such an option +will be: + This is an alias for aliased-to-option + |