[ previous ] [ contents ] [ next ]

Using arfg

• Options and arguments
• The files arfg makes use of
• The options arfg provides
• m4 variable definitions made available

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:

Usage: /usr/local/bin/arfg [option|infile[.arfg]]...
Valid options:
	--compile    	Command to be issued after successful code
	             	construction (default: `'; in --dir; may
	             	be given multiple times).
	--dir        	Directory for generated files (default: .).
	--ext        	Extension for generated file (default:
	             	`').
	--help       	Display this help and exit.
	--no-post    	Do not apply ./.arfg-post.
	--no-pre     	Do not apply ./.arfg-pre.
	--no-rewrite 	Do not apply ./.arfg-rewrite.
	--now        	Explicitly set m4-variable
	             	`m4_arfgBuildTime'.
	--polish     	Filter to be served as last stage of
	             	code construction (may be given multiple
	             	times).
	--quiet      	Do not print filenames.
	--show       	Show, don't execute commands.
	--version    	Display version information and exit.
Exit codes:
	0: for successful completion
	1: for failure of code construction
	2: for failure of code compilation (cf. --compile)
More information is available on the world wide web from
	http://purl.oclc.org/NET/arfg/current/ (most recent version) or from
	http://purl.oclc.org/NET/arfg/2.9b/ (this version).

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.

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 not to 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). 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.

.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. 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 criteria.

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.

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.

--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. 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 non-zero exit code (255 on Unix; cf. perldoc -f die for details).

--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.

--polish command:

Use command as a re-writing filter to apply 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.

--quiet:

In normal operation, arfg prints a short message on standard output indicating the files it processes. This can be disabled by specifying --quiet.

--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).

[ previous ] [ contents ] [ next ]