Command Line Processing
If the default behaviour is not sufficient you can alter the command
line interface using a file whose extension is
A boolean option is something like the
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.
WideListing "-w" booleans;says that the user can give as many
Some options need values. CLP supports two types of values: strings
Typical options of these types would be the
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
OutputFile "-o" string; NumCopies "-#" int;describes the options mentioned above and
Command "-e" strings;describes a repeatable option (see the Unix command
Value options as described in the previous section are separated from
their values by white space. If this is not desired, joined value
can be used and no white space will be expected. Examples of joined
value options are
For example, the following specification lines describe the options mentioned above:
TmpFile "-temp=" joinedto string; NumLines "-" joinedto int;
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
For example, the following specification line describes an option
-x42 -x 42
Exit "-x" with int;
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:
Print "-p" "+pr" "--print" boolean "Print the output";
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
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 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.
When a positional parameter denotes an input file an error message will be generated in the case that this file cannot be opened. The default message is of the form:
PROG ` : cannot open' FILE ` for reading'where PROG is the name of the executable, and FILE is the name of the file that could not be opened.
This error message can be customised using a specification of the form:
`open' `error' `format' string `;'String will then be used as the error message if a file cannot be opened. String can contain escape sequences of the form `%C' which are replaced before the message is output. The following table gives the valid escape sequences:
For example, the default error message is specified using:
open error format "%p: cannot open %f for reading";
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' `;'
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
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 -- -rto interactively (
`terminator' string `;'declares string to be such a string. Multiple terminator specifications are allowed.
To get the behaviour described above for
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.
name `positional' `;'describes a situation where a positional parameter is to be recognized and called name.
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.
An input parameter is a special kind of positional parameter for use when the file named by the parameter value should be initialised for input by the rest of the program. For example, Eli-generated processors usually take a single input file name as a positional parameter.
name `input' `;'describes a situation where a positional parameter is to be recognized, called name and used as an input file by the program.
Currently, only one input parameter may be specified. Also, if an input parameter is specified but the user does not specify a value for it, standard input is used. Future versions will probably allow this behaviour to be customized. For the time-being positional parameters can be used with custom opening of input files.
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). Its main input stream will come from standard input.
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";