|
|
i |
|
NAME
autogen - The Automated Program Generator
SYNOPSIS
autogen [-flag [value]]... [--opt-name [[=| ]value]]...
[ <def-file> ]
AutoGen creates text files from templates using external
definitions.
DESCRIPTION
This manual page documents, briefly, the autogen command.
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 espe
cially 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 imple
ment long option names, rc/ini file processing, environ
ment variables and so on.
All of this can be done mechanically; with the proper tem
plates and this program.
OPTIONS
-L dir, --templ-dirs=dir
Template search directory list. This option may
appear an unlimited number of times.
Add a directory to the list of directories to
search when opening a template, either as the pri
mary 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.
-T tpl-file, --override-tpl=tpl-file
Override template file. This option may not be
preset with environment variables or in initializa
tion (rc) files.
Definition files specify the standard template that
is to be expanded. This option will override that
name and expand a different template.
-l tpl-file, --lib-template=tpl-file
Library template file. This option 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.
-b name, --base-name=name
Base name for output file(s). This option may not
be preset with environment variables or in initial
ization (rc) 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.
--definitions=file, --no-definitions
Definitions input file. The no-definitions form
will disable the option. This option is enabled by
default. This option may not be preset with envi
ronment variables or in initialization (rc) 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.
-S file, --load-scheme=file
Scheme code file to load.
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 pro
cessing. So, though they may be specified in
lambda functions you define, they may not be
invoked until after option processing is complete.
-F file, --load-functions=file
Load scheme callout library.
This option is used to load Guile-scheme callout
functions. The automatically called initialization
routine scm_init must be used to register these
routines or data. This routine can be generated by
using the following command and the `snarf.tpl'
template. Read the introductory comment in
`snarf.tpl' to see what the `getdefs(1AG)' comment
must contain.
GRP_NAME=whateveryoulike
eopt="subblock=exparg=arg_name,arg_desc,arg_optional,arg_list"
eopt="$eopt defs=gfunc templ=snarf srcfile"
eopt="assign=group=${GRP_NAME} assign=init=_init $eopt"
eopt="$eopt autogen=${AG} base-name=expr"
getdefs $eopt <<source-file-list>>
Note, however, that your functions must be named:
whateveryoulike_scm_<<function_name>>(...)
so you may wish to use a shorter group name.
-s suffix, --skip-suffix=suffix
Omit the file with this suffix. This option may
appear an unlimited number of times. This option
may not be preset with environment variables or in
initialization (rc) files.
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-suf
fix=c on the command line.
-o suffix, --select-suffix[=suffix]
specify this output suffix. This option may appear
an unlimited number of times. This option may not
be preset with environment variables or in initial
ization (rc) 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
@ref{pseudo macro} section of the info doc.
--source-time, --no-source-time
set mod times to latest source. The no-source-time
form will disable the option.
If you stamp your output files with the `DNE' macro
output, then your output files will always be dif
ferent, 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.
--equate=char-list
characters considered equivalent. The default
char-list for this opton is _-^.
This option will alter the list of characters con
sidered equivalent. The default are the three
characters, "_-^". (The latter is conventional on
a Tandem, and I do a lot of work on the Tandem.)
--writable, --not-writable
Allow output files to be writable. The not-
writable form will disable the option. This option
may not be preset with environment variables or in
initialization (rc) files.
This option will leave output files writable.Nor
mally, output files are read-only.
--loop-limit=lim
Limit on increment loops. The default lim for this
opton is 256.
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.
-t time-lim, --timeout=time-lim
Time limit for servers. The default time-lim for
this opton is 10.
AutoGen works with a shell server process. Most
normal commands will complete in less than 10 sec
onds. 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=level
tracing level of detail. The default level for
this opton is nothing.
This option will cause AutoGen to display a trace
of its template processing. There are five levels:
Does no tracing at all (default)
Traces the invocation of DEFINEd macros and
INCLUDEs
Traces all block macros. The above, plus IF, FOR,
CASE and WHILE.
Displays the results of expression evaluations
Displays the invocation of every AutoGen macro,
even TEXT macros.
--trace-out=file
tracing output file or filter.
The output specified may be either a file name, or,
if the option argument begins with the pipe opera
tor (|), a command that will receive the tracing
output as standard in. For example, --traceout='|
less' will run the trace output through the less
program.
--show-defs
Show the definition tree. This option may not be
preset with environment variables or in initializa
tion (rc) files.
This will print out the complete definition tree
before processing the template.
--show-shell
Show shell commands. This option may not be preset
with environment variables or in initialization
(rc) files.
This will cause set -x to be executed in the shell,
with the resultant output printed to /dev/tty.
This option will have no effect if --disable-shell
was specified at configure time.
-D value, --define=value
name to add to definition list. This option may
appear an unlimited number of times. This option
is a member of the define class of options.
The AutoGen define names are used for the following
purposes:
Sections of the AutoGen definitions may be enabled
or disabled by using C-style #ifdef and #ifndef
directives.
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.
The name of a file may be prefixed with $NAME.
That part of the name string will be replaced with
the define-d value for NAME.
While processing a template, you may specify an
index to retrieve a specific value. That index may
also be a define-d value.
-U name-pat, --undefine=name-pat
definition list removal pattern. This option may
appear an unlimited number of times. This option
may not be preset with environment variables or in
initialization (rc) files. This option is a member
of the define class of options.
Just like 'C', AutoGen uses #ifdef/#ifndef prepro
cessing directives. This option will cause the
matching names to be removed from the list of
defined values.
-?, --help
Display usage information and exit.
-!, --more-help
Extended usage information passed thru pager.
-> rcfile, --save-opts[=rcfile]
Save the option state to rcfile. The default is
the last rc file listed in the OPTION PRESETS sec
tion, below.
-< rcfile, --load-opts=rcfile, --no-load-opts
Load options from rcfile. The no-load-opts form
will disable the loading of earlier RC/INI files.
--no-load-opts is handled early, out of order.
-v [v|c|n], --version[=v|c|n]
Output version of program and exit. The default
mode is `v', a simple version. The `c' mode will
print copyright information and `n' will print the
full copyright notice.
OPTION PRESETS
Any option that is not marked as not presettable may be
preset by loading values from RC (.ini) file(s) and values
from environment variables named:
AUTOGEN_<option-name>
The environmental presets take precedence (are processed
later than) the RC files. The homerc files are "$HOME",
and ".". If any of these are directories, then the file
.autogenrc is searched for within those directories.
SEE ALSO
This program is documented more fully in the AutoGen Info
system documentation.
EXAMPLES
autogen -T man.tpl --base-name=autogen opts.def
This command produced this man page from the AutoGen
option definition file. It overrides the template speci
fied in opts.def (normally options.tpl) and uses man.tpl.
It also overrides the base-name of the output file, which
is normally derived from the input definition file name
(viz. opts).
AUTHOR
Bruce Korb
Please send bug reports to: autogen-bugs@sf.net
Released under the GNU General Public License.
This manual page was AutoGen-erated from the autogen
option definitions.
2002-09-21 AUTOGEN(1)
This man page was converted to HTML by man2html
|
