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

### Modes and Determinism

- retract(+) is nondet

### Modules

This predicate is sensitive to its module context (tool predicate, see @/2).

### Fail Conditions

Fails if no dynamic clause unifies with Clause

### 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