A.14 option.pl -- Option list processing

See also

library(record)

To be done

- We should consider putting many options in an assoc or record with appropriate preprocessing to achieve better performance.
- We should provide some standard to to automatic type-checking on option lists.

The library(option) provides some utilities for processing option lists. Option lists are commonly used as an alternative for many arguments. Examples built-in predicates are open/4 and write_term/3. Naming the arguments results in more readable code and the list nature makes it easy to extend the list of options accepted by a predicate. Option lists come in two styles, both of which are handled by this library.

Name(Value)

This is the preferred style.

Name = Value

This is often used, but deprecated.

Processing options inside time critical code (loops) can cause serious overhead. One possibility is to define a record using library(record) and initialise this using make_<record>/2. In addition to providing good performance, this also provides type-checking and central declaration of defaults.

:- record atts(width:integer=100, shape:oneof([box,circle])=box).

process(Data, Options) :-
        make_atts(Options, Attributes),
        action(Data, Attributes).

action(Data, Attributes) :-
        atts_shape(Attributes, Shape),
        ...

option(?Option, +OptionList, +Default)

Get an option from a OptionList. OptionList can use the Name=Value as well as the Name(Value) convention.

Option

Term of the form Name(?Value).

option(?Option, +OptionList)

Get an option from a OptionList. OptionList can use the Name=Value as well as the Name(Value) convention. Fails silently if the option does not appear in OptionList.

Option

Term of the form Name(?Value).

[semidet]select_option(?Option, +Options, -RestOptions)

Get and remove option from an option list. As option/2, removing the matching option from Options and unifying the remaining options with RestOptions.

[det]select_option(?Option, +Options, -RestOptions, +Default)

Get and remove option with default value. As select_option/3, but if Option is not in Options, its value is unified with Default and RestOptions with Options.

[det]merge_options(+New, +Old, -Merged)

Merge two option lists. Merged is a sorted list of options using the canonical format Name(Value) holding all options from New and Old, after removing conflicting options from Old.

[det]meta_options(+IsMeta, :Options0, -Options)

Perform meta-expansion on options that are module-sensitive. Whether an option name is module sensitive is determined by calling call(IsMeta, Name). Here is an example:

        meta_options(is_meta, OptionsIn, Options),
        ...

is_meta(callback).