General Information

	Eli: Translator Construction Made Easy
	Global Index
	Frequently Asked Questions
	Typical Eli Usage Errors

Tutorials

	Quick Reference Card
	Guide For new Eli Users
	Release Notes of Eli
	Tutorial on Name Analysis
	Tutorial on Scope Graphs
	Tutorial on Type Analysis
	Typical Eli Usage Errors

Reference Manuals

	User Interface
	Eli products and parameters
	LIDO Reference Manual
	Typical Eli Usage Errors

Libraries

	Eli library routines
	Specification Module Library

Translation Tasks

	Lexical analysis specification
	Syntactic Analysis Manual
	Computation in Trees

Tools

	LIGA Control Language
	Debugging Information for LIDO
	Graphical ORder TOol

FunnelWeb User's Manual

	Pattern-based Text Generator
	Property Definition Language
	Operator Identification Language
	Tree Grammar Specification Language
	Command Line Processing
	COLA Options Reference Manual

Generating Unparsing Code

Monitoring a Processor's Execution

Administration

System Administration Guide

Command Line Processing

Specifying the command line interface

If the default behaviour is not sufficient you can alter the command line interface using a file whose extension is .clp. The following sections show how to specify the varieties of options that the interface may need to handle.

The general format of the command line

The general format of a command line that can be recognised using a .clp specification is:

The program name, followed by
An arbitrary number of options, followed by
An arbitrary number of positional parameters.

A .clp specification describes the legal options and positional parameters.

If the .clp specification is empty the effect is to prohibit all options and positional parameters. A processor generated in this manner must get its input from standard input.

Options that are either there or not

A boolean option is something like the -S (produce assembly code) or -c (compile only, don't link) options for the standard Unix compilers. That is, the option string is all that is needed.

A specification line of the form:

name string `boolean' `;'

describes a boolean option called name which is indicated by the command line string string. For example:

GenAssembly "-S" boolean;
CompileOnly "-c" boolean;

describe the compiler options mentioned above.

If a boolean option can appear more than once on the command line you should use the keyword booleans instead of boolean. Thus, the specification line:

WideListing "-w" booleans;

says that the user can give as many -w options as they like. For example, the processor can check the number provided and produce a listing of the appropriate width. (See the Berkeley Unix ps command.)

Options that have a value given with them

Some options need values. CLP supports two types of values: strings and integers. Typical options of these types would be the -o (generate output in the specified file) option of a Unix compiler, or the -# (print this many copies) option of a line printing program.

A specification line of the form:

name string type `;'

describes a value option called name which is indicated by the command line string string and accepts values of the specified type separated from the indication by whitespace. The valid types are int, ints, string and strings. The plural versions denote value options that may appear more than once on the command line.

For example:

OutputFile "-o" string;
NumCopies "-#" int;

describes the options mentioned above and

Command "-e" strings;

describes a repeatable option (see the Unix command sed, for example).

Options that are joined to their values

Value options as described in the previous section are separated from their values by white space. If this is not desired, joined value options can be used and no white space will be expected. Examples of joined value options are - which is used by the Unix head program to designate how many lines to print (eg. head -42 file), and -temp= which is used by some compilers to describe where to put temporary files (eg. pc -temp=/usr/tmp file.p).

To describe a joined value option, use the specification line as described in the previous section with the keyword joinedto before the type specifier.

For example, the following specification lines describe the options mentioned above:

TmpFile "-temp=" joinedto string;
NumLines "-" joinedto int;

Joined value options can be repeated in the same way as normal value options. For example,

MacroPackage "-m" joinedto strings;

In some cases it is desirable to allow the option to be joined to its value or to be separated from its value by whitespace. To specify this behaviour the keyword with can be used before the type specifier. with can also be used with repeated options of both integer and string type.

For example, the following specification line describes an option -x for which both of the following uses would be legal:

-x42 -x 42

Exit "-x" with int;

Multiple option strings for the same option

The previous three sections have described options with associated values. In some cases it is useful to be able to invoke these options with more than one string on the command line. To specify this kind of behaviour just list all of the option strings instead of just one.

For example, the following specification line says that the printing option can be invoked with any of the following: -p, +pr, or --print.

Print "-p" "+pr" "--print" boolean "Print the output";

The order of option specification lines

Care must be taken when writing a CLP specification to ensure that the specification lines are ordered correctly. When processing the command line, CLP looks for options in the order that you specify them. A problem can occur if some option indication is a prefix of another option indication specified later.

For example, the code generated from the specification:

ModuleOption "-m" joinedto string;
ManOption "-man" string;

will never recognize the -man option because ModuleOption will be tested for first. Putting the specification of ManOption first will fix the problem.

Options that affect usage messages

CLP will automatically arrange for the usage message to be displayed when an erroneous condition is discovered. Sometimes it is nice to be able to implement an option that the user can use on purpose to get the usage message.

A specification line of the form:

`usage' string `;'

declares string to be such an option. Multiple usage options are allowed.

If a usage option is specified on the command line by the user when running the generated processor, the usage message is displayed and execution is terminated. All other options and/or parameters are ignored.

A report can be sent to the standard error stream if the program detects some error in opening a file specified on the command line. To send the report, the program calls ClpOpenError with two arguments (see Reporting open errors).

The text of the report is defined by writing a description of the form:

`open' `error' `format' string `;'

String defines the text, and may contain escape sequences of the form `%C' that are replaced before the report is output:

%f: Replaced by the first argument of the ClpFileError call (usually the name of the file that could not be opened).
%t: Replaced by the second argument of the ClpFileError call (usually a string describing the system error).
%p: Replaced by the name of the program being executed.
%%: Replaced by a single %.
%C: Where `C' is not f, p, t, or %, replaced by nothing.

A CLP specification may contain an arbitrary number of report definitions, but only the last one encountered will be used. CLP assumes that every specification begins with the following report definition:

open error format "%p cannot open %f: %t";

Sometimes it is useful to print the usage message when a file cannot be opened. For example, cases like this occur when the user mistypes an option which is then interpreted as a filename. By default, the usage message is not printed when a file cannot be opened. To cause it to be printed, use a specification line of the form:

`open' `error' `usage' `;'

Terminating the option list

For many processors it is useful to allow the user some way of saying that a command line string that looks like an option isn't really one. For example, this situation may arise when using the Unix rm command. If a user wants to remove a file called -r they would rather not have the filename interpreted as an option to recursively delete subdirectories.

One way of coping with this is to allow the user to type a special command line string that causes option recognition to terminate. For example, a user could type:

rm -i -- -r

to interactively (-i) delete a file called -r.

The termination facility of CLP lets you specify which string (or strings) should cause this behaviour. A specification line of the form:

`terminator' string `;'

declares string to be such a string. Multiple terminator specifications are allowed.

To get the behaviour described above for rm the following would be used:

terminator "--";

Parameters given by their command line position

Parameters that are interpreted according to their position on the command line are called positional parameters. For example, when invoking a remote login program the remote machine name may be given as a positional parameter.

A specification line of the form:

name `positional' `;'

describes a situation where a positional parameter is to be recognized and called name.

The plural form:

name `positionals' `;'

can be used if a group of positional parameters is to be handled and grouped together.

Multiple positional parameters can be recognized by giving multiple specification lines of these kinds. Parameters will be recognized in the order that they are specified. If a plural form is present, it should be the last positional parameter specification line because it will represent all of the positional parameters from that point on. In that case, the processor generated will accept varying numbers of parameters. If no plural form is given, the processor will accept a fixed number of parameters equal to the number of singular positional parameter specification lines.

Input parameters

An input parameter is a special case of a positional parameter. Its value must be a file name, and that file will replace standard input as the primary source of data for the program. An error will be reported if the named file cannot be opened for input. Only one input parameter may be specified.

A specification line of the form:

name `input' `;'

describes a situation where a positional parameter is to be recognized, called name, and used as the primary source of data for the program.

If an input parameter is specified, but the user does not provide a value for it on the command line, then standard input is used as the primary source of data for the program.

If no input parameter is specified then the processor will not be able to get input from a file (unless otherwise programmed using positional parameters). Standard input will be used as the primary source of data for the program.

Documentation options and parameters

If the user specifies things incorrectly on the command line the usual practice is to produce a usage message and terminate execution of the processor. CLP will automatically produce a usage message in this fashion. It is possible to attach descriptions to the option and parameter specification lines to make this usage message more helpful to the user.

Each of the types of specification lines described above (except those for termination of option processing) can have a documentation string. Typical examples are:

CompileOnly "-c" boolean "Just compile, don't link";
MacroPackage "-m" joinedto strings "Load this macro package";
FileName input "File to be processed";
Others positionals "Other positional parameters";