Mode Declarations

The XSB compiler accepts mode declarations of the form:

:- mode $ModeAnnot_1, \ldots, ModeAnnot_n$.

where each $ModeAnnot$ is a mode annotation (a term indicator whose arguments are elements of the set $\{$+,-,#,?$\}$). From Version 1.4.1 on, mode directives are used by the compiler for tabling directives, a use which differs from the standard use of modes in Prolog systems^3.3. See Section 3.8.4 for detailed examples.

Mode annotations have the following meaning:

+

This argument is an input to the predicate. In every invocation of the predicate, the argument position must contain a non-variable term. This term may not necessisarily be ground, but the predicate is guaranteed not to alter this argument).

:- mode see(+), assert(+).

-

This argument is an output of the predicate. In every invocation of the predicate the argument position will always be a variable (as opposed to the # annotation below). This variable is unified with the value returned by the predicate. We note that Prolog does not enforce the requirement that output arguments should be variables; however, output unification is not very common in practice.

:- mode cputime(-).

#

This argument is either:

• An output argument of the predicate for which a non-variable value may be supplied for this argument position. If such a value is supplied, the result in this position is unified with the supplied supplied value. The predicate fails if this unification fails. If a variable term is supplied, the predicate succeeds, and the output variable is unified with the return value.

  :- mode '='(#,#).

• An input/output argument position of a predicate that has only side-effects (usually by further instantiating that argument). The # symbol is used to denote the $\pm$ symbol that cannot be entered from the keyboard.

?

This argument does not fall into any of the above categories. Typical cases would be the following:

• An argument that can be used both as input and as output (but usually not with both uses at the same time).

  :- mode functor(?,?,?).

• An input argument where the term supplied can be a variable (so that the argument cannot be annotated as +), or is instantiated to a term which itself contains uninstantiated variables, but the predicate is guaranteed not to bind any of these variables.

  :- mode var(?), write(?).

We try to follow these mode annotation conventions throughout this manual.

Finally, we warn the user that mode declarations can be error-prone, and since errors in mode declarations do not show up while running the predicates interactively, unexpected behaviour may be witnessed in compiled code, optimised to take modes into account (currently not performed by XSB). However, despite this danger, mode annotations can be a good source of documentation, since they express the programmer's intention of data flow in the program.