[ previous ] [ contents ] [ next ]
Using arfg
arfg accepts any number of options and filename arguments on the
command line. All options are processed from left to right, and all
files named are processed in the order in which they are given; note,
however, that the combined set of all options specified is applied to
every file, even if its name appears before some option. (This used to
be different before version 2.9a, but the current solution is
probably less confusing.)
For a first impression of the facilities arfg provides, have a look
at its help message:
Apart from the commands arfg calls,
the script uses a number of files in the current directory (though it
can be told, by employing suitable options, to
ignore them).
In the following list of files, anything written in italics (or
surrounded by <i> and </i> in the
source, if your browser does not show italics) is generic and must be
substituted by whatever is appropriate; anything written in fixed
width font (or surrounded by <tt> and
</tt> in the source, if your browser does not
distinguish fixed width font) should be taken literally. - All files
refer to the current working directory.
- .arfg-pre:
- This is prepended to any filename.wml unless
option --no-pre is specified. Usually its contents, which
will be processed by .arfg-rewrite, provide common
definitions, define macros, or output common header information. -
Also see option --pre.
- filename.arfg:
- The contents of this file, henceforth referred to as the input
file, are sandwiched between .arfg-pre and .arfg-post to jointly be
processed. If named on the command line, it is an error for the file
to not exist or to not be readable. It is the contents of this file
that are processed within the context set up by .arfg-pre and
.arfg-post to produce the output file filename, or
filenameExt if an option of the form
--ext Ext has been given, in the current
directory (or in any directory named via the --dir option;
but note the rules for the output file's
location below). File permissions of the output file will be
set to match those of the input file.
- filename without trailing .arfg:
- This is equivalent to filename.arfg, see
above.
- .arfg-post:
- If this file exists and can be read, its contents are appended
to any filename.arfg unless option --no-post
is specified. Usually its contents, which will also be processed by
.arfg-rewrite, provide a way for clean-up operations or to
output common footer information. -
Also see option --post
- .arfg-rewrite:
- If this file exists and can be executed, it acts as an initial
re-write filter for the input files unless option
--no-rewrite is specified; if it exists but is not
executable, a warning is issued. This program, usually written in
Perl, sed, awk or a similar language, is used to add syntactic
sugar to the meta-language or to implement advanced features based upon
automatically recognizable patterns. -
Also see option --rewrite
In addition to these, options --compile and
--polish, expecting arguments to be interpreted as commands,
may refer to the names of executable files.
Note that arfg always works in a directory-oriented way, which is
why all the above files are searched for only in the current
directory. As a consequence, different applications using the same
resources sometimes cannot easily be made to coexist in one directory
- symbolic links provide a simple solution.
An (almost) complete listing of all options with a short description
is part of arfg's help message. In the
following more detailed description of the options the fonts have the
same meaning as above.
- --compile command:
- After code construction has successfully been completed, i. e.
after all input files have been processed without non-zero exit code,
command is executed after changing to the
workingDirectory specified by option --dir. If given
multiple times, all commands are executed in turn; note, however, that
the change of directories is performed only before the first
command. Care has to be taken to properly quote any commands
comprising more than one word and to escape characters that might be
evaluated by the shell. - Default is empty. - q. v. option
--dir.
- --define m4Variable or --define
m4Variable=m4Value:
- Prepend calls to m4_define() to make
sure that m4Variable is defined
(m4_ifdef() returns $1) and, if
m4Value is provided, that the expansion of m4Variable
(accessible only via m4_indir() if it does
not conform to m4's notion of a word) is set to m4Value; if
there are multiple = signs in the option's argument, the
first one is used to distinguish the two parts. Note that the
implementation relies on m4_changequote() for
proper quoting of, among others, shell metacharacters; however, even
though this means that the pipeline assembled by arfg cannot be
broken by specifying inappropriate arguments to --define,
calling arfg on, say, an English text with an option like
--define "the=m4_esyscmd(echo -e -n
\"\\a\">&2)" will most likely produce a lot of
noise during the m4 step of arfg. Once
again, there is no attempt to disable potentially harmful
--defines - arfg is certainly not for the faint of
heart.
- --dir workingDirectory:
- Output file filename (with optional extension,
cf. option --ext) corresponding to input file
filename.arfg mentioned above
will be created in directory workingDirectory (but note the
rules for the output file's location
below). Note that the current working directory during program
execution is not affected by this, only the location of the file
produced; if the m4 or Perl steps of arfg perform any I/O, the
corresponding files will be located relative to the directory where
arfg was called, not in workingDirectory. - When specified
multiple times, the last value takes precedence. - Default is the
current working directory. - q. v. option --compile.
- --ext Extension:
- Filename extension to be appended to the output file name. -
When specified multiple times, the last value takes precedence. -
Default is void.
- --help:
- Output the help message and terminate
with zero exit code.
- --list:
- List all the output files produced on standard
output. Together with --quiet (which is not honored in this
case), this sometimes comes in handy when operating with, e. g.,
xargs on the output files.
- --no-post:
- Do not use file .arfg-post even
if it exists and can be read.
- --no-pre:
- Do not use file .arfg-pre even
if it exists and can be read.
- --no-rewrite:
- Do not use file .arfg-rewrite
as an initial re-writing filter even if it exists and can be
executed.
- --now currentTime:
- For arfg to be fully effective, it is often called repeatedly until the output files no
longer change. However, if any of the output files is to contain the
time of code construction, this procedure is likely to not terminate
(depending on the granularity of the output's time dependence and the
speed of code construction). To avoid this kind of problem, you can
specify a string currentTime to be used for initializing m4 variable m4_arfgBuildTime. - When
specified multiple times, the last value takes precedence. - Default
is the current time as provided by the system clock.
- --pre file:
- Use file instead of .arfg-pre,
q. v..
- --post file:
- Use file instead of .arfg-post,
q. v..
- --polish command:
- Use command as a re-writing filter to be applied after
the eperl step. This option may be specified multiple times, in
which case the filters are applied in the order of their occurrence on
the command line. Care has to be taken to properly quote any commands
comprising more than one word and to escape characters that might be
evaluated by the shell. - Default is void.
- --re file:
- Use file instead of .arfg-rewrite,
q. v..
- --quiet:
- In normal operation, arfg prints a short message on standard
output indicating the files it processes. This can be disabled by
specifying --quiet. Note however that the list of output
files requested by --list will still be printed.
- --show:
- After assembling the command line in the usual way, print,
rather than execute, it. The output is in a form usually suitable for
selection with a mouse pointing device under gpm or the likes
of it. Useful especially for debugging.
- --version:
- Display version and date. Version labels comprise two numbers
separated by a dot and a sequence of one or more lower-case
letters. Increasing the first number indicates changes breaking
compatibility with earlier versions; increasing the second number
indicates minor changes (incompatibilities possible only through name
clashes); an increase in the letters when viewed as a base-26 integer
indicates non-trivial change (improvement, hopefully) of the
software's documentation.
Some rudimentary meta-data regarding the current application of arfg
to an input file is made available to the m4 stage of arfg, which
can, of course, also be accessed by eperl by referencing the result
of an m4 evaluation:
- m4_sourcefile:
- The name of the current input file being processed (including
the trailing .arfg).
- m4_arfgBuildTime:
- The current time at the moment of calling arfg, or the
argument of option --now.
- m4_lastEditTime:
- The time the current input file was last edited, as found from
the stat() system call (cf. perldoc -f stat).
In addition to these, option --define
allows to set any number of m4 variables.
arfg makes a distinction between absolute paths (starting with
/; tilde-expansion is currently not considered) and relative
paths for the input files: when given an absolute path, the output
file will actually be placed in the directory indicated by
--dir (or the current working directory if not given); when a
relative path is specified for the input file, the corresponding
output file will be located relative to the directory
indicated by --dir (or the current working directory if not
given). The latter allows to translate hierarchical directory
structures, while the former allows one to process files located in
non-writable directories.
[ previous ] [ contents ] [ next ]