8.9 Modification of the Program

The predicates defined in this section allow modification of dynamic predicates. Dynamic clauses can be added (asserted) or removed from the program (retracted).

SICStus Prolog implements the “logical” view in updating dynamic predicates. This means that the definition of a dynamic predicate that is visible to a call is effectively frozen when the call is made. A predicate always contains, as far as a call to it is concerned, exactly the clauses it contained when the call was made.

A useful way to think of this is to consider that a call to a dynamic predicate makes a virtual copy of its clauses and then runs the copy rather than the original clauses. Any changes to the predicate made by the call are immediately reflected in the Prolog database, but not in the copy of the predicate being run. Thus, changes to a running predicate will not be visible on backtracking. A subsequent call, however, makes and runs a copy of the modified Prolog database. Any changes to the predicate that were made by an earlier call will now be visible to the new call.

For the predicates of this section, the argument Head must be instantiated to an atom or a compound term, with an optional module prefix. The argument Clause must be instantiated either to a term Head :- Body or, if the body part is empty, to Head, with an optional module prefix. An empty body part is represented as true.

Note that a term Head :- Body must be enclosed in parentheses when it occurs as an argument of a compound term, as `:-' is a standard infix operator with precedence greater than 1000 (see Operators), e.g.:

     | ?- assert((Head :- Body)).

Like recorded terms (see Database), the clauses of dynamic predicates have a unique implementation-defined identifier. Some of the predicates below have an additional argument, which is this identifier. This identifier makes it possible to access clauses directly instead of requiring a normal database (hash-table) lookup.

assert(:Clause)

assert(:Clause,-Ref)

The current instance of Clause is interpreted as a clause and is added to the database. The predicate concerned must currently be dynamic or undefined and the position of the new clause within it is implementation-defined. Ref is a database reference to the asserted clause. Any uninstantiated variables in the Clause will be replaced by new private variables, along with copies of any subgoals blocked on these variables (see Procedural).

asserta(:Clause) ISO

asserta(:Clause,-Ref)

Like assert/2, except that the new clause becomes the first clause for the predicate concerned.

assertz(:Clause) ISO

assertz(:Clause,-Ref)

Like assert/2, except that the new clause becomes the last clause for the predicate concerned.

clause(:Head,?Body) ISO

clause(:Head,?Body,?Ref)

clause(?Head,?Body,+Ref)

The clause (Head :- Body) exists in the database, and its database reference is Ref. The predicate concerned must currently be dynamic. At the time of call, either Ref must be instantiated, or Head must be instantiated to an atom or a compound term. Thus clause/3 can have two different modes of use.

retract(:Clause) ISO

The first clause in the database that matches Clause is erased. The predicate concerned must currently be dynamic. retract/1 may be used in a nondeterminate fashion, i.e. it will successively retract clauses matching the argument through backtracking.

retractall(:Head)

Erases all clauses whose head matches Head, where Head must be instantiated to an atom or a compound term. The predicate concerned must currently be dynamic. The predicate definition is retained.

Please note: all predicates mentioned above first look for a predicate that is visible in the module in which the call textually appears. If no predicate is found, a new dynamic predicate (with no clauses) is created automatically. It is recommended to declare as dynamic predicates for which clauses will be asserted.

abolish(:Spec) ISO

abolish(:Name,+Arity)

Abolishes the predicates specified by the generalized predicate spec Spec or Name/Arity. Name may be prefixed by a module name (see Module Spec). In iso execution mode only dynamic predicates can be abolished. In sicstus execution mode only built-in predicates cannot be abolished, the user-defined ones always can be, even when static.

erase(+Ref)

The dynamic clause or recorded term (see Database) whose database reference is Ref is effectively erased from the database.

instance(+Ref,?Term)

A (most general) instance of the dynamic clause or recorded term whose database reference is Ref is unified with Term.