retractall/1

Synopsis

retractall(+Head)

Removes every clause in module M whose head matches Head.

Arguments

Head callable [MOD]

Head of a Prolog clause.

Description

Head must be instantiated to a term that looks like a call to a dynamic procedure. For example, to retract all the clauses of foo/3, you would write

     | ?- retractall(foo(_,_,_)).
     

Head may be preceded by a M: prefix, in which case the clauses are retracted from module M instead of the calling module.

retractall/1 could be defined (less efficiently) as

     retractall(Head) :-
             clause(Head, _, Ref),
             erase(Ref),
             fail ; true.
     

or

     retractall(Head) :-
             retract((Head :- _Body)),
             fail ; true.
     

retractall/1 is useful for erasing all the clauses of a dynamic procedure without forgetting that it is dynamic; abolish/1 will not only erase all the clauses, but will also forget absolutely everything about the procedure. retractall/1 only erases the clauses. This is important if the procedure is called later on.

Since retractall/1 erases all the dynamic clauses whose heads match Head, it has no choices to make, and is determinate. If there are no such clauses, it succeeds trivially. None of the variables in Head will be instantiated by this command. For example,

     | ?- listing(baz/2).
     
     baz(a,1).
     baz(b,2).
     baz(a,3).
     baz(b,4).
     
     yes
     | ?- retractall(baz(a, X)).
     
     X = _798
     
     | ?- listing(baz/2).
     
     baz(b,2).
     baz(b,4).
     
     yes
     

The space previously occupied by a retracted clause is reclaimed. This reclamation is not necessarily immediate, but it is not delayed until backtracking past the call of retractall/1, as in some implementations.

Exceptions

instantiation_error

if Head or Module is uninstantiated.

type_error

if Head is not of type callable.

permission_error

if the procedure corresponding to Head is built-in or has a static definition.

See Also

abolish/[1,2], assert/1, dynamic/1, erase/1, retract/1 ref-mdb-bas