[ Dynamic Predicates | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

retract(+Clause)

Succeeds if a clause that unifies with Clause can be removed from the database.
+Clause
Atom or compound term

Description

Removes the first clause that matches the argument from the database. On backtracking, successive clauses that match are removed. The clauses are not reasserted when backtracking occurs through retract/1.

The functor of the head of Clause must be that of a predicate declared as dynamic, otherwise an error occurs. If no clause matches, it fails.

retract/1 satisfies the logical update semantics. When retract/1 is first called, it makes a virtual copy of the clauses that match and, on backtracking, unifies its argument with them and removes them from the database. Any modifications made to the procedure after retract/1 has started executing do not, in any way, affect its behaviour. A subsequent call, however, makes and uses a new, virtual, copy of the modified database.

Fail Conditions

Fails if no dynamic clause unifies with Clause

Resatisfiable

Yes

Exceptions

(4) instantiation fault
Clause is not instantiated
(4) instantiation fault
The head of Clause is a free variable.
(5) type error
Clause or the head of Clause is not a callable term.
(63) procedure not dynamic
Procedure is not dynamic
(70) accessing an undefined dynamic procedure
Procedure is undefined

Examples

Success:
    [eclipse]: assert(city(munich)), assert(city(london)),
    assert((p :- write(hi), write(there))).

    yes.
    [eclipse]: retract(city(X)).

    X = munich     More? (;)
    yes.
    [eclipse]: retract(city(X) :- Body).

    X = london
    Body = true
    yes.
    [eclipse]: retract(p :- Body).

    Body = write(hi) , write(there)
    yes.
Fail:
    assert(fact),retract(fact),retract(fact).

Error:
    retract(X).                            (Error 4).
    retract("x").                          (Error 5).
    retract(listing).                      (Error 63).
    retract(undef).                        (Error 70).

See Also

asserta / 1, dynamic / 1, listing / 1