Table of Contents

1. Introduction

1.1 The Purpose of AutoGen
1.2 A Simple Example
1.3 csh/zsh caveat
1.4 A User's Perspective

2. AutoGen Definitions File

2.1 The Identification Definition
2.2 Named Definitions

2.2.1 Naming a Value
2.2.2 Definition List
2.2.3 Double Quote String
2.2.4 Single Quote String
2.2.5 Shell Output String
2.2.6 An Unquoted String
2.2.7 Scheme Result String
2.2.8 A Here String
2.2.9 Concatenated Strings

2.3 Dynamic Text
2.4 Controlling What Gets Processed
2.5 Pre-defined Names
2.6 Commenting Your Definitions
2.7 What it all looks like.
2.8 YACC Language Grammar
2.9 AutoGen without Definitions

3. AutoGen Template

3.1 Format of the Pseudo Macro
3.2 Naming a value
3.3 Macro Expression Syntax

3.3.1 Apply Code
3.3.2 Basic Expression

3.4 AutoGen Scheme Functions

3.4.1 `ag-function?' - test for function
3.4.2 `base-name' - base output name
3.4.3 `count' - definition count
3.4.4 `def-file' - definitions file name
3.4.5 `dne' - "Do Not Edit" warning
3.4.6 `error' - display message and exit
3.4.7 `error-source-line' - display of file & line
3.4.8 `exist?' - test for value name
3.4.9 `first-for?' - detect first iteration
3.4.10 `for-by' - set iteration step
3.4.11 `for-from' - set initial index
3.4.12 `for-index' - get current loop index
3.4.13 `for-sep' - set loop separation string
3.4.14 `for-to' - set ending index
3.4.15 `get' - get named value
3.4.16 `high-lim' - get highest value index
3.4.17 `last-for?' - detect last iteration
3.4.18 `len' - get count of values
3.4.19 `low-lim' - get lowest value index
3.4.20 `match-value?' - test for matching value
3.4.21 `out-delete' - delete current output file
3.4.22 `out-depth' - output file stack depth
3.4.23 `out-move' - change name of output file
3.4.24 `out-name' - current output file name
3.4.25 `out-pop' - close current output file
3.4.26 `out-push-add' - append output to file
3.4.27 `out-push-new' - purge and create output file
3.4.28 `out-resume' - resume current output file
3.4.29 `out-suspend' - suspend current output file
3.4.30 `out-switch' - close and create new output
3.4.31 `set-writable' - Make the output file be writable
3.4.32 `stack' - make list of AutoGen values
3.4.33 `suffix' - get the current suffix
3.4.34 `tpl-file' - get the template file name
3.4.35 `tpl-file-line' - get the template file and line number

3.5 Common Scheme Functions

3.5.1 `bsd' - Free BSD public license
3.5.2 `c-string' - emit string for ANSI C
3.5.3 `extract' - extract text from another file
3.5.4 `find-file' - locate a file in the search path
3.5.5 `fprintf' - format to a file
3.5.6 `gperf' - perform a perfect hash function
3.5.7 `gpl' - GNU public license
3.5.8 `in?' - test for string in list
3.5.9 `join' - join string list with separator
3.5.10 `kr-string' - emit string for K&R C
3.5.11 `lgpl' - GNU lib public license
3.5.12 `license' - an arbitrary license
3.5.13 `make-gperf' - build a perfect hash function program
3.5.14 `max' - maximum value in list
3.5.15 `min' - minimum value in list
3.5.16 `prefix' - prefix lines with a string
3.5.17 `printf' - format to stdout
3.5.18 `raw-shell-str' - single quote shell string
3.5.19 `shell' - invoke a shell script
3.5.20 `shell-str' - double quote shell string
3.5.21 `shellf' - format a string, run shell
3.5.22 `sprintf' - format a string
3.5.23 `string-capitalize' - make a new string be capitalized
3.5.24 `string-capitalize!' - capitalize a string
3.5.25 `string-contains-eqv?' - caseless substring
3.5.26 `string-contains?' - substring match
3.5.27 `string-downcase' - make a new string be lower case
3.5.28 `string-downcase!' - make a string be lower case
3.5.29 `string-end-eqv-match?' - caseless regex ending
3.5.30 `string-end-match?' - regex match end
3.5.31 `string-ends-eqv?' - caseless string ending
3.5.32 `string-ends-with?' - string ending
3.5.33 `string-equals?' - string matching
3.5.34 `string-eqv-match?' - caseless regex match
3.5.35 `string-eqv?' - caseless string match
3.5.36 `string-has-eqv-match?' - caseless regex contains
3.5.37 `string-has-match?' - contained regex match
3.5.38 `string-match?' - regex match
3.5.39 `string-start-eqv-match?' - caseless regex start
3.5.40 `string-start-match?' - regex match start
3.5.41 `string-starts-eqv?' - caseless string start
3.5.42 `string-starts-with?' - string starting
3.5.43 `string->c-name!' - map non-name chars to underscore
3.5.44 `string-tr!' - convert characters
3.5.45 `string-upcase' - make a new string be upper case
3.5.46 `string-upcase!' - make a string be upper case
3.5.47 `sub-shell-str' - back quoted (sub-)shell string
3.5.48 `sum' - sum of values in list

3.6 AutoGen Native Macros

3.6.1 AutoGen Macro Syntax
3.6.2 CASE - Select one of several template blocks
3.6.3 COMMENT - A block of comment to be ignored
3.6.4 DEFINE - Define a user AutoGen macro
3.6.5 ELIF - Alternate Conditional Template Block
3.6.6 ELSE - Alternate Template Block
3.6.7 ENDDEF - Ends a macro definition.
3.6.8 ENDFOR - Terminates the FOR function template block
3.6.9 ENDIF - Terminate the IF Template Block
3.6.10 ENDWHILE - Terminate the WHILE Template Block
3.6.11 ESAC - Terminate the CASE Template Block
3.6.12 EXPR - Evaluate and emit an Expression
3.6.13 FOR - Emit a template block multiple times
3.6.14 IF - Conditionally Emit a Template Block
3.6.15 INCLUDE - Read in and emit a template block
3.6.16 INVOKE - Invoke a User Defined Macro
3.6.17 SELECT - Selection block for CASE function
3.6.18 UNKNOWN - Either a user macro or a value name.
3.6.19 WHILE - Conditionally loop over a Template Block

3.7 Redirecting Output

4. Augmenting AutoGen

4.1 Shell Output Commands
4.2 Guile Macros
4.3 Guile Callout Functions
4.4 AutoGen Macros

5. Invoking autogen

5.1 autogen usage help (-?)
5.2 templ-dirs option (-L)
5.3 override-tpl option (-T)
5.4 lib-template option (-l)
5.5 base-name option (-b)
5.6 definitions option
5.7 load-scheme option (-S)
5.8 load-functions option (-F)
5.9 skip-suffix option (-s)
5.10 select-suffix option (-o)
5.11 source-time option
5.12 equate option
5.13 writable option
5.14 loop-limit option
5.15 timeout option (-t)
5.16 trace option
5.17 trace-out option
5.18 show-defs option
5.19 show-shell option
5.20 define option (-D)
5.21 undefine option (-U)

6. What Gets Installed Where
7. Automated Option Processing

7.1 AutoOpts Features

loading rc files
saving rc files
process a text string for options

7.2 Competitive Feature Analysis
7.3 Quick Start
7.4 Option Definitions

7.4.1 Program Description Attributes
7.4.2 Option Attributes

7.4.2.1 Required Attributes
7.4.2.2 Common Option Attributes
7.4.2.3 Special Option Handling
7.4.2.4 Immediate Action Attributes
7.4.2.5 Option Conflict Attributes
7.4.2.6 Option Argument Specification
7.4.2.7 Option Argument Handling

7.4.3 Man and Info doc Attributes
7.4.4 Automatically Supported Options
7.4.5 Library of Standard Options

7.5 Programmatic Interface

7.5.1 Data for Option Processing
7.5.2 CLEAR_OPT( <NAME> ) - Clear Option Markings
7.5.3 COUNT_OPT( <NAME> ) - Definition Count
7.5.4 DESC( <NAME> ) - Option Descriptor
7.5.5 DISABLE_OPT_name - Disable an option
7.5.6 ENABLED( <NAME> ) - Is Option Enabled?
7.5.7 ERRSKIP_OPTERR - Ignore Option Errors
7.5.8 ERRSTOP_OPTERR - Stop on Errors
7.5.9 HAVE_OPT( <NAME> ) - Have this option?
7.5.10 ISSEL_OPT( <NAME> ) - Is Option Selected?
7.5.11 ISUNUSED_OPT( <NAME> ) - Never Specified?
7.5.12 OPTION_CT - Full Count of Options
7.5.13 OPT_ARG( <NAME> ) - Option Argument String
7.5.14 OPT_VALUE_name - Option Argument Value
7.5.15 RESTART_OPT( n ) - Resume Option Processing
7.5.16 SET_OPT_name - Force an option to be set
7.5.17 STACKCT_OPT( <NAME> ) - Stacked Arg Count
7.5.18 STACKLST_OPT( <NAME> ) - Argument Stack
7.5.19 START_OPT - Restart Option Processing
7.5.20 STATE_OPT( <NAME> ) - Option State
7.5.21 USAGE( exit-code ) - Usage invocation macro
7.5.22 VALUE_OPT_name - Option Flag Value
7.5.23 VERSION - Version and Full Version
7.5.24 WHICH_IDX_name - Which Equivalenced Index
7.5.25 WHICH_OPT_name - Which Equivalenced Option
7.5.26 teOptIndex - Option Index and Enumeration
7.5.27 OPTIONS_STRUCT_VERSION - active version
7.5.28 libopts procedures

7.6 Option Descriptor File
7.7 Using AutoOpts
7.8 AutoOpts for Shell Scripts
7.9 Automated `Invoking Info' Doc
7.10 Automated Man Pages

8. Add-on packages for AutoGen

8.1 Automated Finite State Machine
8.2 Combined RPC Marshalling
8.3 Automated Event Management
8.4 Invoking columns

8.4.1 columns usage help (-?)
8.4.2 width option (-W)
8.4.3 columns option (-c)
8.4.4 col-width option (-w)
8.4.5 spread option
8.4.6 indent option (-I)
8.4.7 first-indent option
8.4.8 tab-width option
8.4.9 sort option (-s)
8.4.10 format option (-f)
8.4.11 separation option (-S)
8.4.12 line-separation option
8.4.13 by-columns option
8.4.14 input option (-i)

8.5 Invoking getdefs

8.5.1 getdefs usage help
8.5.2 defs-to-get option
8.5.3 ordering option
8.5.4 first-index option
8.5.5 input option
8.5.6 subblock option
8.5.7 listattr option
8.5.8 filelist option
8.5.9 assign option
8.5.10 common-assign option
8.5.11 copy option
8.5.12 srcfile option
8.5.13 linenum option
8.5.14 output option
8.5.15 autogen option
8.5.16 template option
8.5.17 agarg option
8.5.18 base-name option

8.6 Replacement for Stdio Formatting Library

9. Hints, helps and FAQs
10. Some ideas for the future.
Concept Index
Function Index