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).

For these predicates, 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. If reactivated by backtracking, invocations of the predicate whose clauses are being retracted will proceed unaffected by the retracts. This is also true for invocations of clause/[2,3] for the same predicate. The space occupied by a retracted clause will be recovered when instances of the clause are no longer in use.

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 procedures 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.