[ previous ] [ contents ] [ next ]

Using arfg

Options and arguments

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:



The files arfg makes use of

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.

The options arfg provides

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.

m4 variable definitions made available

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.

Location of the output files

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 ]


Copyright © 2001-2005 by Albert REINER. All rights reserved.

URL: http://purl.oclc.org/NET/arfg/current/usage.html

URL: http://purl.oclc.org/NET/arfg/2.13c/usage.html

2005-08-06 23:02:01