options.pl -- Options handling and processing.

This is an infrastructure SWI pack that deals with predicate options. The main concept is to treate options as naive Prolog lists which the programmer can manipulate and specialise if they need to, while providing a number of basic predicates that manage basic common operations on options. Options are particularly important in the context of SWI packs, as making code publicly available to others often involves allowing for variations in the behaviour of the code.

The library provides simple extensions to the basic list manipulation predicates. In many cases it is just the error handling that is the main difference to standard predicates.

Technically the library is designed on the semantics of memberchk/2. Looking for an Option in a list of options, memberchk/2 will return the leftmost match. Library(options) sees options as a concatenation (append/3) of the user provided options (arguments for hereon) and the defaults provided by the predicate.

The default option values for a predicate are given by a predicate of the same name but postfixed by '_defaults'. The library also allows for reading user specific default options by reading profiles from a file located at $HOME/.pl/<pred_name>.pl, if that file exists. Each options file should have a number of option terms given as facts.

Some distinctive features of pack(options)

• minimal "magic" behind the scenes
• allows sloppy (un-listed) single option argument
• defaults might depend on input
• can-do cascading (options of distinct predicates should be disjoint)
• processing debug(Dbg) terms which optionise calls to debug/1
• uniform access to user specific file-based default options

For an example see program options_example_sort_defaults.pl in examples directory.

?- edit( pack(options/examples/ex_sort) ).

?- [pack(options/examples/ex_sort)].

?- ex_sort( [a,b,e,c,b], Ord, true ).
Ord = [a, b, c, e].
?- ex_sort( [a,b,e,c,b], Ord, debug(true) ).
% Input list length: 5
% Output list length: 4
Ord = [a, b, c, e].
?- ex_sort( [a,b,e,c,b], Ord, order(>) ).
Ord = [e, c, b, a].
?- ex_sort( [a,b,e,c,b], Ord, duplicates(true) ).
Ord = [a, b, b, c, e].

Create file $HOME/.pl/ex_sort.pl with content order(>).

?- ex_sort( [a,b,e,c,b], Ord, true ).
Ord = [e, c, b, a].

Default for user is now order(>) which can still be over-ridden at invocation

?- ex_sort( [a,b,e,c,b], Ord, order(<) ).
Ord = [a, b, c, e].

Predicates

• en_list/2,
• options/2,3
• options_append/3,4
• options_propagate/4
• options_restore/2
• options_return/2

author

- nicos angelopoulos

version

- 0.2.0 2015/7/5

To be done

- type checking (see options_propagate for a first use)

Undocumented predicates

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

options_debug(Arg1, Arg2, Arg3)

options_append(Arg1, Arg2, Arg3)

options_append(Arg1, Arg2, Arg3, Arg4)

options_version(Arg1, Arg2)

options(Arg1, Arg2, Arg3)

options(Arg1, Arg2)

options_return(Arg1, Arg2)

options_propagate(Arg1, Arg2, Arg3, Arg4)

en_list(Arg1, Arg2)

options_restore(Arg1, Arg2)