
predicate_options.pl -- Access and analyse predicate options
This module provides the developers interface for the directive
predicate_options/3. This directive allows us to specify that, e.g.,
open/4 processes options using the 4th argument and supports the option
type
using the values text
and binary
. Declaring options that are
processed allows for more reliable handling of predicate options and
simplifies porting applications. This library provides the following
functionality:
- Query supported options through current_predicate_option/3 or current_predicate_options/3. This is intended to support conditional compilation and an IDE.
- Derive additional declarations through dataflow analysis using derive_predicate_options/0.
- Perform a compile-time analysis of the entire loaded program using check_predicate_options/0.
Below, we describe some use-cases.
- Quick check of a program
-
This scenario is useful as an occasional check or to assess problems
with option-handling for porting an application to SWI-Prolog. It
consists of three steps: loading the program (1 and 2), deriving
option handling for application predicates (3) and running the
checker (4).
1 ?- [load]. 2 ?- autoload. 3 ?- derive_predicate_options. 4 ?- check_predicate_options.
- Add declarations to your program
-
Adding declarations about option processes improves the quality of
the checking. The analysis of derive_predicate_options/0 may miss
options and does not derive the types for options that are processed
in Prolog code. The process is similar to the above. In steps 4 and
further, the inferred declarations are listed, inspected and added to
the source code of the module.
1 ?- [load]. 2 ?- autoload. 3 ?- derive_predicate_options. 4 ?- derived_predicate_options(module_1). 5 ?- derived_predicate_options(module_2). 6 ?- ...
- Declare option processing requirements
-
If an application requires that open/4 needs to support
lock(write)
, it may do so using the directive below. This directive raises an exception when loaded on a Prolog implementation that does not support this option.:- current_predicate_option(open/4, 4, lock(write)).
predicate_options(:PI, +Arg, +Options) is det
- Declare that the predicate PI processes options on Arg. Options
is a list of options processed. Each element is one of:
- Option(ModeAndType) PI processes Option. The option-value must comply to ModeAndType. Mode is one of + or - and Type is a type as accepted by must_be/2.
- pass_to(:PI,Arg) The option-list is passed to the indicated predicate.
Below is an example that processes the option
header(boolean)
and passes all options to open/4::- 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), Options, true) -> write_xml_header(Out) ; true ), ...
This predicate may only be used as a directive and is processed by expand_term/2. Option processing can be specified at runtime using assert_predicate_options/3, which is intended to support program analysis.
Undocumented predicates
The following predicates are exported, but not or incorrectly documented.
check_predicate_options(Arg1)
derived_predicate_options(Arg1, Arg2, Arg3)
check_predicate_option(Arg1, Arg2, Arg3)
current_predicate_options(Arg1, Arg2, Arg3)
derived_predicate_options(Arg1)
current_option_arg(Arg1, Arg2)
current_predicate_option(Arg1, Arg2, Arg3)
assert_predicate_options(Arg1, Arg2, Arg3, Arg4)
retractall_predicate_options
check_predicate_options
derive_predicate_options