option.pl -- Option list processing

The library(option) provides some utilities for processing option lists. Option lists are commonly used as an alternative for many arguments. Examples of 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),
        ...

Options typically have exactly one argument. The library does support options with 0 or more than one argument with the following restrictions:

• The predicate option/3 and select_option/4, involving default are meaningless. They perform an arg(1, Option, Default), causing failure without arguments and filling only the first option-argument otherwise.
• meta_options/3 can only qualify options with exactly one argument.

See also

- library(record)

- Option processing capabilities may be declared using the directive predicate_options/3.

To be done

- We should consider putting many options in an assoc or record with appropriate preprocessing to achieve better performance.

 option(?Option, +OptionList, +Default) is semidet

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

Arguments:

Option

- Term of the form Name(?Value).

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 select_option(Arg1, Arg2, Arg3)

 meta_options(Arg1, Arg2, Arg3)

 option(Arg1, Arg2)

 dict_options(Arg1, Arg2)

 select_option(Arg1, Arg2, Arg3, Arg4)

 merge_options(Arg1, Arg2, Arg3)