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

1.3.2 List

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

• List Examples

1.3.3 Record

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.

• Record Examples