Remove a single clause from the active module, the next unifiable predicate that matches with the argument is retracted. This built-in predicate is re-executable, i.e. each time it is executed it attempts to remove the next clause that matches with its argument, if there is no (more) clause to remove then retract/1 fails.
The clauses may only be removed from the module if they were defined as dynamic. Another built-in predicate that removes clauses from a module is abolish/1.
see also: abolish/1 abolish/2 asserta/1assertz/1 asserta/2 assertz/2 dynamic/1 dynamic/2 retract/2 set_active_module/0 set_active_module/1
| Example | |
| retract( test(1) ). | removes the next predicate that matches with the argument 'test(1)' |
| retract( test(X) ). | removes the next 'test(_)' that it finds and unifies X with the value of the match |
| Exceptions | |
| The argument is a variable | the exception instantiation_error is thrown |
| There is no active module | the exception existence_error(active_module) is thrown |
| The head of the clause term is a variable, retract( A :- body ) | because the head is a variable an instantiation_error exception is thrown |
| The head of the clause term is not a correct term, retract( 4 :- body) | a type_error(callable, Var) exception is thrown because 4 is not a valid head of a clause, in this case Var is assigned 4 |
| The predicate to retract is a built-in predicate. | an exception permission_error(modify, static_procedure, Pred) is thrown, Pred is replaced by a predicate indicator |