Remove a single clause from a module, the next unifiable predicate that matches with the second argument is retracted. The first argument must be the name of a module currently loaded, not the filename of a file in the module. 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 are 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/1 set_active_module/0 set_active_module/1
| Example | |
| retract( data, test(1) ). | removes the next predicate that matches with 'test(1)' from the module 'data' |
| retract( data, test(X) ). | removes the next 'test(_)' from the module 'data' that matches |
| Exceptions | |
| The first argument is a variable | an instantiation_error exception is thrown |
| The first argument Arg is not an atom | a type_error(atom, Arg) exception is thrown |
| No module with the specified Name exists | an existence_error(module, Name) exception is thrown. |
| The second argument is a variable | the exception instantiation_error 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 |