1.3 Option Specifications

There are several ways to specify the way the arguments are parsed; we present them in order of increasing processing power.

1.3.1 Plain

Syntax Specification

The plain way of command line processing actually involves no processing at all. In CGI parsing, not even escaped characters are translated.

<spec> ::= plain

Returned Result

For CGI scripts, the result consists of a list of pairs of strings (the name/value pairs), whereas for command lines, it consists of a list of strings.

1.3.2 List

Syntax Specification

The list way of processing command line arguments takes care of determining what is a command line option, whether it takes a value, how its value to be interpreted, etc.

<spec> += list([mode: <mode>] <option> ... <option>)

Using the mode specification, the command line parser can either be instructed to stop at the first non-option argument it encounters (start) or it can look for options on the whole command line (anywhere). The latter is the default if no mode is given.

<mode> ::= start | anywhere

The integer fields of the option specification describe the individual options. An option must as least have an <option name>. Furthermore, it may either be an alias for another option (if alias is given) or it may be a `real' option actually visible to the application. Aliases are never returned to the application; they are always replaced by the option they stand for.

<option> ::= <option name>([char: <char or chars>] [type: <type>])
 | <option name>([char: <char or chars>] alias: <alias>)

<option name> ::= <atom>

As mentioned in Section 1.2.2, options may be notated using single-character short forms. With the char specification one or several single-character short forms may be assigned to an option.

<char or chars> ::= <char> | [<char>]

If no type is given, then the option does not take an argument. (Note that true will be used as the associated value in this case.) Boolean options have a special status, as has already been described in Section 1.2. The remaining type specifications, however, require an additional argument. The list(<primary type>) annotation interprets its argument as a comma-separated list of elements of a specific type.

<type> ::= bool
 | <primary type>
 | list(<primary type>)

There are four supported basic types and a `generic' type. Integer and float arguments have to be given in Oz concrete syntax (with the exception that the unary minus sign may be notated as -); minimum and maximum values may also be specified. For arguments to be returned as atoms, a set of allowed values may be specified. Strings are returned as-is.

The generic type simply consists of a binary procedure with the signature {P +S X} which may arbitrarily transform the argument, given as a string.

<primary type> ::= int([min: <int>] [max: <int>])
 | float([min: <float>] [max: <float>])
 | atom([<atom> ... <atom>])
 | string
 | <procedure>

Two different forms of alias are supported. Option name aliases simply state that this option name is equivalent to some other option name; the other option's argument description will be used for parsing this option as well. The second kind of alias states that this option is equivalent to another option used with the supplied value (or a combination of several options). In the latter case, the value will be transferred to the output without any additional transformations.

<alias> ::= <option name>
 | <option name>#<value>
 | [<option name>#<value>]

Returned Result

The result of this processing step is a list of parsed options, interspersed with non-parsed arguments, a so-called <option list>. All option names in this list are the canonical (i. e., not aliased and unabbreviated) forms. The list respects the order in which the arguments were given.

<option list> ::= [<arg or option>]

<arg or option> ::= <option name>#<value>
 | <string>

1.3.3 Record

Syntax Specification

The additional processing step involved in record kind specifications is that additional contextual conditions may be checked, and the result is returned in a different form.

Basically, the record specification is a strict extension of the list specification.

<spec> += record([mode: <mode>] <option> ... <option>)

The specifications for `real' (i. e., non-alias) options take some more information into consideration, namely how often the option may appear and how several occurrences combine (<occ>), and whether it is a required option (optional; the default is true) or whether it takes a default value (default), which it does not by default. At most one of default and optional may be given.

<option> += <option name>(
   1: <occ>
   [char: <char or chars>]
   [type: <type>]
   [default: <value> | optional: <bool>])

An option may be allowed to occur at most once (single) or any number of times. In the latter case, the result may either respect all occurrences (multiple), or it may ignore all but the first (leftmost) or last (rightmost) occurrence. When all occurrences are respected, a list of them (preserving the order) is returned.

<occ> ::= single | multiple | leftmost | rightmost | accumulate(P)

When accumulate(P) is specified, procedure P is called for each occurrence of the option. It takes two arguments: the option (as an atom) and the parsed value. This can be used to accumulate multiple occurrences of related options into one list. See, for example, options --include and --exclude of the Oz linker ozl.

Returned Result

The result consists of an option record. All options which had an explicit <occ> given in their specification are moved from the option list into this record, the feature being the option name, the subtree the associated value. Defaulted options that have not been overridden by the argument list appear in this record with their default value. Only optional options may be missing from this record, namely when they have not been specified in the argument list. Those options which did not have an explicit <occ> given in their specification are found, interspersed with non-parsed arguments, in an option list under feature 1 of the option record.

<option record> ::= optRec(1: <option list>
       <option name><value> ...
       <option name><value>)

Denys Duchier, Leif Kornstaedt, Martin Homik, Tobias Müller, Christian Schulte and Peter Van Roy
Version 1.4.0 (20080702)