File: predicate_options.html

package info (click to toggle)
swi-prolog 7.2.3%2Bdfsg-6
links: PTS, VCS
area: main
in suites: stretch
size: 84,180 kB
ctags: 45,684
sloc: ansic: 330,358; perl: 268,104; sh: 6,795; java: 4,904; makefile: 4,561; cpp: 4,153; ruby: 1,594; yacc: 843; xml: 82; sed: 12; sql: 6
file content (567 lines) | stat: -rw-r--r-- 18,853 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<html>
<head>
<title>SWI-Prolog 7.3.6 Reference Manual: Section A.23</title><link rel="home" href="index.html">
<link rel="contents" href="Contents.html">
<link rel="index" href="DocIndex.html">
<link rel="summary" href="summary.html">
<link rel="previous" href="pio.html">
<link rel="next" href="prologpack.html">

<style type="text/css">

/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef, dt.multidef
{ color: #fff;
padding: 2px 10px 0px 10px;
margin-bottom: 5px;
font-size: 18px;
vertical-align: middle;
overflow: hidden;
}

dt.pubdef { background-color: #0c3d6e; }
dt.multidef { background-color: #ef9439; }

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{
}

span.sec-title
{
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
padding-top: 0.2em;
font-size: 80%;
font-style: italic;
color: #fff;
}

div.caption
{ width: 80%;
margin: auto;
text-align:center;
}

/* Footnotes */
.fn {
color: red;
font-size: 70%;
}

.fn-text, .fnp {
position: absolute;
top: auto;
left: 10%;
border: 1px solid #000;
box-shadow: 5px 5px 5px #888;
display: none;
background: #fff;
color: #000;
margin-top: 25px;
padding: 8px 12px;
font-size: larger;
}

sup:hover span.fn-text
{ display: block;
}

/* Lists */

dl.latex
{ margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.latex dl.latex dd.defbody
{ margin-bottom: 0.5ex;
}

/* PlDoc Tags */

dl.tags
{ font-size: 90%;
margin-left: 5ex;
margin-top: 1ex;
margin-bottom: 0.5ex;
}

dl.tags dt
{ margin-left: 0pt;
font-weight: bold;
}

dl.tags dd
{ margin-left: 3ex;
}

td.param
{ font-style: italic;
font-weight: bold;
}

/* Index */

dt.index-sep
{ font-weight: bold;
font-size: +1;
margin-top: 1ex;
}

/* Tables */

table.center
{ margin: auto;
}

table.latex
{ border-collapse:collapse;
}

table.latex tr
{ vertical-align: text-top;
}

table.latex td,th
{ padding: 2px 1em;
}

table.latex tr.hline td,th
{ border-top: 1px solid black;
}

table.frame-box
{ border: 2px solid black;
}

</style>
</head>
<body style="background:white">
<div class="navigate"><a class="nav" href="index.html"><img src="home.gif" alt="Home"></a>
<a class="nav" href="Contents.html"><img src="index.gif" alt="Contents"></a>
<a class="nav" href="DocIndex.html"><img src="yellow_pages.gif" alt="Index"></a>
<a class="nav" href="summary.html"><img src="info.gif" alt="Summary"></a>
<a class="nav" href="pio.html"><img src="prev.gif" alt="Previous"></a>
<a class="nav" href="prologpack.html"><img src="next.gif" alt="Next"></a>
</div>
<h2 id="sec:predicate_options"><a id="sec:A.23"><span class="sec-nr">A.23</span> <span class="sec-title">library(predicate_options): 
Declare option-processing of predicates</span></a></h2>

<a id="sec:predicate_options"></a>

<p><i>Discussions with Jeff Schultz helped shaping this library</i>

<p><h3 id="sec:predopts-pro-cons"><a id="sec:A.23.1"><span class="sec-nr">A.23.1</span> <span class="sec-title">The 
strength and weakness of predicate options</span></a></h3>

<p><a id="sec:predopts-pro-cons"></a>

<p>Many ISO predicates accept options, e.g., <a class="pred" href="IO.html#open/4">open/4</a>, <a class="pred" href="termrw.html#write_term/3">write_term/3</a>. 
Options offer an attractive alternative to proliferation into many 
predicates and using high-arity predicates. Properly defined and used, 
they also form a mechanism for extending the API of both system and 
application predicates without breaking portability. I.e., previously 
fixed behaviour can be replaced by dynamic behaviour controlled by an 
option where the default is the previously defined fixed behaviour. The 
alternative to using options is to add an additional argument and 
maintain the previous definition. While a series of predicates with 
increasing arity is adequate for a small number of additional 
parameters, the untyped positional argument handling of Prolog quickly 
makes this unmanageable.

<p>The ISO standard uses the extensibility offered by options by 
allowing implementations to extend the set of accepted options. While 
options form a perfect solution to maintain backward portability in a 
linear development model, it is not well equipped to deal with 
concurrent branches because

<p>
<ol class="latex">
<li>There is no API to find which options are supported in a particular 
implementation.
<li>While the portability problem caused by a missing predicate in 
Prolog <i>A</i> can easily be solved by implementing this predicate, it 
is much harder to add processing of an additional option to an already 
existing predicate.
</ol>

<p>Different Prolog implementations can be seen as concurrent 
development branches of the Prolog language. Different sets of supported 
options pose a serious portability issue. Using an option <i>O</i> that 
establishes the desired behaviour on system <i>A</i> leads (on most 
systems) to an error or system <i>B</i>. Porting may require several 
actions:

<p>
<ul class="latex">
<li>Drop <i>O</i> (if the option is not vital, such as the layout 
options to <a class="pred" href="termrw.html#write_term/3">write_term/3</a>)
<li>Replace <i>O</i> by <i>O2</i> (i.e., a differently named option 
doing the same)
<li>Something else (cannot be ported; requires a totally different 
approach, etc.)
</ul>

<p>Predicates that process options are particularly a problem when 
writing a compatibility layer to run programs developed for System <i>A</i> 
on System
<i>B</i> because complete emulation is often hard, may cause a serious 
slowdown and is often not needed because the application-to-be-ported 
only uses options that are shared by all target Prolog implementations. 
Unfortunately, the consequences of a partial emulation cannot be 
assessed by tools.

<p><h3 id="sec:predopts-environment"><a id="sec:A.23.2"><span class="sec-nr">A.23.2</span> <span class="sec-title">Options 
as arguments or environment?</span></a></h3>

<p><a id="sec:predopts-environment"></a>

<p>We distinguish two views on options. One is to see them as additional 
parameters that require strict existence, type and domain-checking and 
the other is to consider them `locally scoped environment variables'. 
Most systems adopt the first option. SWI-Prolog adopts the second: it 
silently ignores options that are not supported but does type and domain 
checking of option-values. The `environment' view is commonly used in 
applications to create predicates supporting more options using the 
skeleton below. This way of programming requires that <i>pred1</i> and
<i>pred2</i> do not interpret the same option differently. In cases 
where this is not true, the options must be distributed by <i>some_pred</i>. 
We have been using this programming style for many years and in practice 
it turns out that the need for active distribution of options is rare. 
I.e., options either have distinct names or multiple predicates 
implement the same option but this has the desired effect. An example of 
the latter is the <code>encoding</code> option, which typically needs to 
be applied consistently.

<pre class="code">
some_pred(..., Options) :-
      pred1(..., Options),
      pred2(..., Options).
</pre>

<p>As stated before, options provide a readable alternative to 
high-arity predicates and offer a robust mechanism to evolve the API, 
but at the cost of some runtime overhead and weaker consistency 
checking, both at compiletime and runtime. From our experience, the 
`environment' approach is productive, but the consequence is that 
mistyped options are silently ignored. The option infrastructure 
described in this section tries to remedy these problems.

<p><h3 id="sec:predopts-improving"><a id="sec:A.23.3"><span class="sec-nr">A.23.3</span> <span class="sec-title">Improving 
on the current situation</span></a></h3>

<p><a id="sec:predopts-improving"></a>

<p>Whether we see options as arguments or locally scoped environment 
variables, the most obvious way to improve on the current situation is 
to provide reflective support for options: discover that an argument is 
an option-list and find what options are supported. Reflective access to 
options can be used by the compiler and development environment as well 
as by the runtime system to warn or throw errors.

<p><h4 id="sec:predopts-as-types"><a id="sec:A.23.3.1"><span class="sec-nr">A.23.3.1</span> <span class="sec-title">Options 
as types</span></a></h4>

<p><a id="sec:predopts-as-types"></a>

<p>An obvious approach to deal with options is to define the different 
possible option values as a type and type the argument that processes 
the option as list(<var>&lt;</var>option_type<var>&gt;</var>), as 
illustrated below. Considering options as types fully covers the case 
where we consider options as additional parameters.

<pre class="code">
:- type open_option ---&gt; type(stream_type) |
                         alias(atom) | ... .
:- pred open(source_sink, open_mode, stream, list(open_option)).
</pre>

<p>There are three reasons for considering a different approach:

<p>
<ul class="latex">
<li>There is no consensus about types in the Prolog world, neither about 
what types should look like, nor whether or not they are desirable. It 
is not likely that this debate will be resolved shortly.
<li>Considering options as types does not support the `environment' 
view, which we consider the most productive.
<li>Even when using types, we need reflective access to what options are 
provided in order to be able to write compile or runtime conditional 
code.
</ul>

<p><h4 id="sec:predopts-reflextion"><a id="sec:A.23.3.2"><span class="sec-nr">A.23.3.2</span> <span class="sec-title">Reflective 
access to options</span></a></h4>

<p><a id="sec:predopts-reflextion"></a>

<p>From the above, we conclude that we require reflective access to find 
out whether an option is supported and valid for a particular predicate. 
Possible option values must be described by types. Due to lack of a type 
system, we use <code>library(error)</code> to describe allowed option 
values. Predicate options are declared using <a class="pred" href="predicate_options.html#predicate_options/3">predicate_options/3</a>:

<dl class="latex">
<dt class="pubdef"><span class="pred-tag">[det]</span><a id="predicate_options/3"><strong>predicate_options</strong>(<var>:PI, 
+Arg, +Options</var>)</a></dt>
<dd class="defbody">
Declare that the predicate <var>PI</var> processes options on <var>Arg</var>. <var>Options</var> 
is a list of options processed. Each element is one of:

<p>
<ul class="latex">
<li>Option(ModeAndType)
<var>PI</var> processes Option. The option-value must comply to 
ModeAndType. Mode is one of + or - and Type is a type as accepted by <span class="pred-ext">must_be/2</span>.
<li>pass_to(:<var>PI</var>,<var>Arg</var>) The option-list is passed to 
the indicated predicate.
</ul>

<p>Below is an example that processes the option <code>header(boolean)</code> 
and passes all options to <a class="pred" href="IO.html#open/4">open/4</a>:

<pre class="code">
:- predicate_options(write_xml_file/3, 3,
                     [ header(boolean),
                       pass_to(open/4, 4)
                     ]).

write_xml_file(File, XMLTerm, Options) :-
    open(File, write, Out, Options),
    (   option(header(true), Option, true)
    -&gt;  write_xml_header(Out)
    ;   true
    ),
    ...
</pre>

<p>This predicate may only be used as a <i>directive</i> and is 
processed by <a class="pred" href="consulting.html#expand_term/2">expand_term/2</a>. 
Option processing can be specified at runtime using <span class="pred-ext">assert_predicate_options/3</span>, 
which is intended to support program analysis.</dd>
<dt class="pubdef"><span class="pred-tag">[semidet]</span><a id="assert_predicate_options/4"><strong>assert_predicate_options</strong>(<var>:PI, 
+Arg, +Options, ?New</var>)</a></dt>
<dd class="defbody">
As predicate_options(:<var>PI</var>, +<var>Arg</var>, +<var>Options</var>). <var>New</var> 
is a boolean indicating whether the declarations have changed. If <var>New</var> 
is provided and <code>false</code>, the predicate becomes semidet and 
fails without modifications if modifications are required.
</dd>
</dl>

<p>The predicates below realise the support for compile and runtime 
checking for supported options.

<dl class="latex">
<dt class="pubdef"><span class="pred-tag">[nondet]</span><a id="current_predicate_option/3"><strong>current_predicate_option</strong>(<var>:PI, 
?Arg, ?Option</var>)</a></dt>
<dd class="defbody">
True when <var>Arg</var> of <var>PI</var> processes <var>Option</var>. 
For example, the following is true:

<pre class="code">
?- current_predicate_option(open/4, 4, type(text)).
true.
</pre>

<p>This predicate is intended to support conditional compilation using <a class="pred" href="consulting.html#if/1">if/1</a> 
... <a class="pred" href="consulting.html#endif/0">endif/0</a>. The 
predicate
<a class="pred" href="predicate_options.html#current_predicate_options/3">current_predicate_options/3</a> 
can be used to access the full capabilities of a predicate.</dd>
<dt class="pubdef"><span class="pred-tag">[det]</span><a id="check_predicate_option/3"><strong>check_predicate_option</strong>(<var>:PI, 
+Arg, +Option</var>)</a></dt>
<dd class="defbody">
Verify predicate options at runtime. Similar to
<a class="pred" href="predicate_options.html#current_predicate_option/3">current_predicate_option/3</a>, 
but intended to support runtime checking.

<dl class="tags">
<dt class="mtag">Errors</dt>
<dd>
- <code>existence_error(option, OptionName)</code> if the option is not 
supported by <var>PI</var>. <br>
- <code>type_error(Type, Value)</code> if the option is supported but 
the value does not match the option type. See <span class="pred-ext">must_be/2</span>.
</dd>
</dl>

</dd>
</dl>

<p>The predicates below can be used in a development environment to 
inform the user about supported options. PceEmacs uses this for 
colouring option names and values.

<dl class="latex">
<dt class="pubdef"><span class="pred-tag">[nondet]</span><a id="current_option_arg/2"><strong>current_option_arg</strong>(<var>:PI, 
?Arg</var>)</a></dt>
<dd class="defbody">
True when <var>Arg</var> of <var>PI</var> processes predicate options. 
Which options are processed can be accessed using <a class="pred" href="predicate_options.html#current_predicate_option/3">current_predicate_option/3</a>.</dd>
<dt class="pubdef"><span class="pred-tag">[nondet]</span><a id="current_predicate_options/3"><strong>current_predicate_options</strong>(<var>:PI, 
?Arg, ?Options</var>)</a></dt>
<dd class="defbody">
True when <var>Options</var> is the current active option declaration 
for
<var>PI</var> on <var>Arg</var>. See <a class="pred" href="predicate_options.html#predicate_options/3">predicate_options/3</a> 
for the argument descriptions. If <var>PI</var> is ground and refers to 
an undefined predicate, the autoloader is used to obtain a definition of 
the predicate.
</dd>
</dl>

<p>The library can execute a complete check of your program using
<a class="pred" href="predicate_options.html#check_predicate_options/0">check_predicate_options/0</a>:

<dl class="latex">
<dt class="pubdef"><span class="pred-tag">[det]</span><a id="check_predicate_options/0"><strong>check_predicate_options</strong></a></dt>
<dd class="defbody">
Analyse loaded program for erroneous options. This predicate decompiles 
the current program and searches for calls to predicates that process 
options. For each option list, it validates whether the provided options 
are supported and validates the argument type. This predicate performs 
partial dataflow analysis to track option-lists inside a clause.

<dl class="tags">
<dt class="tag">See also</dt>
<dd>
<a class="pred" href="predicate_options.html#derive_predicate_options/0">derive_predicate_options/0</a> 
can be used to derive declarations for predicates that pass options. 
This predicate should normally be called before
<a class="pred" href="predicate_options.html#check_predicate_options/0">check_predicate_options/0</a>.
</dd>
</dl>

</dd>
</dl>

<p>The library offers predicates that may be used to create declarations 
for your application. These predicates are designed to cooperate with 
the module system.

<dl class="latex">
<dt class="pubdef"><span class="pred-tag">[det]</span><a id="derive_predicate_options/0"><strong>derive_predicate_options</strong></a></dt>
<dd class="defbody">
Derive new predicate option declarations. This predicate analyses the 
loaded program to find clauses that process options using one of the 
predicates from <code>library(option)</code> or passes options to other 
predicates that are known to process options. The process is repeated 
until no new declarations are retrieved.

<dl class="tags">
<dt class="tag">See also</dt>
<dd>
<a class="pred" href="runtime.html#autoload/0">autoload/0</a> may be 
used to complete the loaded program.
</dd>
</dl>

</dd>
<dt class="pubdef"><span class="pred-tag">[det]</span><a id="retractall_predicate_options/0"><strong>retractall_predicate_options</strong></a></dt>
<dd class="defbody">
Remove all dynamically (derived) predicate options.</dd>
<dt class="pubdef"><span class="pred-tag">[nondet]</span><a id="derived_predicate_options/3"><strong>derived_predicate_options</strong>(<var>:PI, 
?Arg, ?Options</var>)</a></dt>
<dd class="defbody">
Derive option arguments using static analysis. True when <var>Options</var> 
is the current <i>derived</i> active option declaration for <var>PI</var> 
on
<var>Arg</var>.</dd>
<dt class="pubdef"><span class="pred-tag">[det]</span><a id="derived_predicate_options/1"><strong>derived_predicate_options</strong>(<var>+Module</var>)</a></dt>
<dd class="defbody">
Derive predicate option declarations for a module. The derived options 
are printed to the <code>current_output</code> stream.
</dd>
</dl>

<p></body></html>