|Did you know ...||Search Documentation:|
|Notation of Predicate Descriptions|
We have tried to keep the predicate descriptions clear and concise.
First, the predicate name is printed in bold face, followed by the
arguments in italics. Arguments are preceded by a mode indicator. There
is no complete agreement on mode indicators in the Prolog community. We
use the following definitions:44These
definitions are taken from PlDoc. The current manual has only one mode
declaration per predicate and therefore predicates with mode (+,-) and
(-,+) are described as (?,?). The
@-mode is often replaced
|++||Argument must be ground, i.e., the argument may not contain a variable anywhere.|
|+||Argument must be fully instantiated to a term that
satisfies the type. This is not necessarily ground, e.g., the
|-||Argument is an output argument. Unless
specified otherwise, output arguments need not to be unbound. For
example, the goal |
|--||Argument must be unbound. Typically used by predicates that create `something' and return a handle to the created object, such as open/3 which creates a stream.|
|?||Argument must be bound to a partial term of
the indicated type. Note that a variable is a partial term for any type.
Think of the argument as either input or output or
both input and output. For example, in
|:||Argument is a meta-argument. Implies |
|@||Argument is not further instantiated. Typically used for type tests.|
|!||Argument contains a mutable structure that may be modified using setarg/3 or nb_setarg/3.|
Referring to a predicate in running text is done using a predicate indicator. The canonical and most generic form of a predicate indicator is a term <module>:<name>/<arity>. If the module is irrelevant (built-in predicate) or can be inferred from the context it is often omitted. Compliant to the ISO standard draft on DCG (see section 4.13), SWI-Prolog also allows for [<module>]:<name>//<arity> to refer to a grammar rule. For all non-negative arity, <name>//<arity> is the same as <name>/<arity>+2, regardless of whether or not the referenced predicate is defined or can be used as a grammar rule. The //-notation can be used in all places that traditionally allow for a predicate indicator, e.g., the module declaration, spy/1, and dynamic/1.
See also the description in the package of the Prolog documentation generator:
where additional information regarding determinism (determinacy?) annotation is given.
A note from that page:
_Developers should ensure that predicates are steadfast with respect to output arguments (marked - in the template). This means that instantiation of output arguments at call-time does not change the semantics of the goal (it may be used for optimization, though). If this steadfast behavior cannot be guaranteed, -- should be used instead._