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 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
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:
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' `;'
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 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.
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 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.
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";