An argument mode
indicator gives information about the intended direction in which
information carried by a predicate argument is supposed to flow. Mode
indicators (and types) are not a formal part of the Prolog language but
help in explaining intended semantics to the programmer. There is no
complete agreement on argument mode indicators in the Prolog community.
We use the following definitions:49These
definitions are taken from the PlDoc markup language
description. PldDoc markup is used for source code markup (as
well as for the commenting tool). The current manual has only one mode
declaration per predicate and therefore predicates with mode (+--+??@-mode is often replaced by
chr+.
| ++ | At call time, the argument must be ground, i.e., the argument may not contain any variables that are still unbound. |
| + | At call time, the argument must be instantiated to a
term satisfying some (informal) type specification. The argument need
not necessarily be ground. For example, the term [_] is a
list, although its only member is the anonymous variable, which is
always unbound (and thus nonground). |
| - | Argument is an output argument. It may or may
not be bound at call-time. If the argument is bound at call time, the
goal behaves as if the argument were unbound, and then unified with that
term after the goal succeeds. This is what is called being steadfast:
instantiation of output arguments at call-time does not change the
semantics of the predicate, although optimizations may be performed. For
example, the goal findall(X, Goal, [T]) is good style and
equivalent to findall(X, Goal, Xs), Xs = [T]50The
ISO standard dictates that findall(X, Goal, 1) raise a type_error
exception, breaking steadfastness. SWI-Prolog does not follow the
standard here. Note that any determinism
specification, e.g., det, only applies if the argument is
unbound. For the case where the argument is bound or involved in
constraints, det effectively becomes
semidet, and multi effectively becomes
nondet. |
| -- | At call time, the argument must be unbound. This is typically used by predicates that create‘something' and return a handle to the created object, such as open/3, which creates a stream. |
| ? | At call time, the argument must be bound to a partial
term (a term which may or may not be ground) satisfying some
(informal) type specification. Note that an unbound variable is
a partial term. Think of the argument as either providing input or
accepting output or being used for both input and output. For example,
in stream_property(S, reposition(Bool)), the
reposition part of the term provides input and the
unbound-at-call-time Bool variable accepts output. |
| : | Argument is a meta-argument, for example a
term that can be called as goal. The predicate is thus a meta-predicate.
This flag implies |
| @ | Argument will not be further instantiated than it is at call-time. Typically used for type tests. |
| ! | Argument contains a mutable structure that may be modified using setarg/3 or nb_setarg/3. |
See also section 4.8 for examples of meta-predicates, and section 6.5 for mode flags to label meta-predicate arguments in module export declarations.