Did you know ... | Search Documentation: |
The argument mode indicator |
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:51These
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 (
,+
)
and (-
,-
) are
described as (+
,?
).
The ?
@
-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] 52The 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.