11.3.38 clause/[2,3]   ISO

Synopsis

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.

Arguments

:Head

callable

A term whose functor names a dynamic procedure.

Body

callable

Ref

db_reference

Description

Initially, at least one of Head and Ref must be instantiated.

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, then (Head :- Body) is unified with the clause identified by Ref. (If this clause is a unit-clause, then 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, then 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.

Backtracking

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.

Exceptions

instantiation_error

Neither Head nor Ref is instantiated.

type_error

Head is not a callable, or Ref is not a well-formed db_reference

permission_error

Procedure is not dynamic.

existence_error

Ref is a well-formed db_reference but does not correspond to an existing clause or record.

Comments

If clause/[2,3] is called on an undefined procedure, then 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, then 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, then 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)).

no
| ?- 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 Indexing.

clause/2 is part of the ISO Prolog standard; clause/3 is not.

See Also

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