mpg-ref-retract - SICStus Prolog

11.3.192 `retract/1` [ISO]

Synopsis

retract(+Clause)

Removes the first occurrence of dynamic clause Clause from module M.

Arguments

:Clause: callable, must be nonvar
A valid Prolog clause.

Description

retract/1 erases the first clause in the database that matches Clause. Clause is retracted in module M if specified. Otherwise, Clause is retracted in the source module.

retract/1 is nondeterminate. If control backtracks into the call to retract/1, successive clauses matching Clause are erased. If and when no clauses match, the call to retract/1 fails.

If the predicate did not previously exist, then it is created as a dynamic predicate and retract/1 fails.

Clause must be of one of the forms:

Head
Head :- Body
Module:Clause

where Head is of type callable and the principal functor of Head is the name of a dynamic procedure. If specified, Module must be an atom.

retract(Head) means retract the unit-clause Head. The exact same effect can be achieved by retract((Head :- true)).

Body may be uninstantiated, in which case it will match any body. In the case of a unit-clause it will be bound to true. Thus, for example,

     | ?- retract((foo(X) :- Body)), fail.

is guaranteed to retract all the clauses for foo/1, including any unit-clauses, providing of course that foo/1 is dynamic.

Backtracking

Can be used to retract all matching clauses through backtracking.

Exceptions

instantiation_error: if Head (in Clause) or M is uninstantiated.
type_error: if Head is not of type callable, or if M is not an atom, or if Body is not a valid clause body.
permission_error: if the procedure corresponding to Head is not dynamic.

11.3.192 retract/1 [ISO]