clause(+*Head, *Body)

clause(-Head, -Body, +Ref)

clause(+*Head, *Body, *Ref)

Searches the database for a clause whose head matches Head and whose body matches Body.


Head callable [MOD]
a term whose functor names a dynamic procedure.
Body callable
compound term or true
Ref db_reference
a database reference


In the case of unit-clauses, Body is unified with true.

If a procedure consists entirely of unit-clauses then there is no point in calling clause/2 on it. It is simpler and faster to call the procedure.

In clause/3, either Head or Ref must be instantiated. If Ref is instantiated, (Head :- Body) is unified with the clause identified by Ref. (If this clause is a unit-clause, Body is unified with true.)

If the predicate did not previously exist, then it is created as a dynamic predicate and clause/2 fails. If Ref is not instantiated, clause/3 behaves exactly like clause/2 except that the database reference is returned.

By default, clauses are accessed with respect to the source module.


Can be used to backtrack through all the clauses matching a given Head and Body. It fails when there are no (or no further) matching clauses in the database.


Neither Head nor Ref is instantiated.
Head is not of type callable

Ref is not a syntactically valid database reference.

Procedure is static (not dynamic).
Ref is a well-formed database reference but does not correspond to an existing clause or record.


If clause/[2,3] is called on an undefined procedure it fails, but before failing it makes the procedure dynamic. This can be useful if you wish to prevent unknown procedure catching from happening on a call to that procedure.

It is not a limitation that Head is required to be instantiated in clause(Head, Body), because if you want to backtrack through all clauses for all dynamic procedures this can be achieved by:

     | ?- predicate_property(P,(dynamic)), clause(P,B).

If there are clauses with a given name and arity in several different modules, or if the module for some clauses is not known, the clauses can be accessed by first finding the module(s) by means of current_predicate/2. For example, if the procedure is f/1:

     | ?- current_predicate(_,M:f(_)), clause(M:f(X),B).

clause/3 will only access clauses that are defined in, or imported into, the source module, except that the source module can be overridden by explicitly naming the appropriate module. For example:

     | ?- assert(foo:bar,R).
     R = '$ref'(771292,1)
     | ?- clause(H,B,'$ref'(771292,1)).
     | ?- clause(foo:H,B,'$ref'(771292,1)).
     H = bar,
     B = true
     | ?-

Accessing a clause using clause/2 uses first argument indexing when possible, in just the same way that calling a procedure uses first argument indexing. See bas-eff-ind.

See Also

instance/2, assert/[1,2], dynamic/1, retract/1 ref-mdb-dre