mpg-ref-clause - SICStus Prolog

11.3.37 `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, (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.

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 of type callable. Ref is not a syntactically valid database reference.
permission_error: Procedure is not dynamic.
existence_error: Ref is a well-formed database reference but does not correspond to an existing clause or record.

Comments

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)).
     
     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.

11.3.37 clause/[2,3] [ISO]