### List Examples

The following will give some examples taken from the `ozc` program, which is the Oz command-line compiler.

Basics

The `ozc` program has a command line option to tell it to output usage information. The easiest way to specify such an option is:

> `help`

Furthermore, we want to support a popular single-character abbreviation for it:

> `help(char: &h)`

We might even support several single-character abbreviations for convenience.

> `help(char: [&h &?])`

We can now write any of `--help`, `-h`, or `-?` for this option. (We might also abbreviate the long form to one of `--h`, `--he`, or `--hel`, provided that this would still be unambiguous.) The returned option list would be `[help#true]`.

Boolean Options

There is another option to tell `ozc` to be verbose about what it is doing. Say we specified it as follows:

> `verbose(char: &v)`

This means that we can write `--verbose` or `-v`. In contrast, the following specification additionally allows for `--noverbose`:

> `verbose(char: &v type: bool)`

Aliases

Some people prefer to write `--noverbose` as `--quiet`, so we introduce an alias for it:

> `quiet(char: &q alias: verbose#false)`

This is an alias with associated value. In contrast, the following option (not supported by `ozc`, by the way) would be an alias without value:

> `gossipy(alias: verbose)`

This would allow us to write `--gossipy` for `--verbose` and `--nogossipy` for `--noverbose`.

String Arguments

The following example illustrates another type of argument than boolean:

> `include(type: string)`

Saying `--include=x.oz` for instance would tell `ozc` to load and compile this file before tackling its `real' job. Together with the following option, we get an example for when the order beween different arguments may matter:

> `'define'(char: &D type: atom)`

Saying

> `--define=MYMACRO1 --include=x.oz --include=y.oz`

for instance would mean that `MYMACRO1` would be defined for both `x.oz` and `y.oz`, whereas in

> `--include=x.oz --define=MYMACRO1 --include=y.oz`

it is only defined for `y.oz`.

By the way, this option has a single-character abbreviation and an explicit argument (in contrast to the implicit boolean arguments above): We can thus write either `-D MYMACRO1` or `-DMYMACRO1` instead of `--define=MYMACRO1`.

List Arguments

In `ozc`, actually, a list of macro names is allowed for this option:

> `'define'(char: &D type: list(atom))`

This also supports, e. g., `-DMYMACRO1,YOURMACRO17 x.oz`. This would return the option list `['define'#['MYMACRO1' 'YOURMACRO17'] "x.oz"]`.

Range Limitations

Sometimes one wants to limit the range of allowed values:

> `compress(char: &z type: int(min: 0 max: 9))`

This would allow us to write `-z9`, but not `-z17`. For atom arguments, sometimes only a limited set of values is sensible:

> `mode(type: atom(help core outputcode
> feedtoemulator dump executable)`

For these, `ozc` also provides the better known aliases such as:

> `dump(char: &c alias: mode#dump)`