assert/[1,2]

Synopsis

These predicates add a dynamic clause, Clause, to the Prolog database. They optionally return a database reference in Ref:

assert(+Clause)

assert(+Clause, -Ref)

Undefined whether Clause will precede or follow the clauses already in the database.

asserta(+Clause)

asserta(+Clause, -Ref)

Clause will precede all existing clauses in the database.

assertz(+Clause)

assertz(+Clause, -Ref)

Clause will follow all existing clauses in the database.

Arguments

Clause callable [MOD]

A valid dynamic Prolog clause.

Ref db_reference

a database reference, which uniquely identifies the newly asserted Clause.

Description

Clause must be of the form:

            Head
     or     Head :- Body
     or     M:Clause
     

where Head is of type callable and Body is a valid clause body. If specified, M must be an atom.

assert(Head) means assert the unit-clause Head. The exact same effect can be achieved by assert((Head :- true)).

If Body is uninstantiated it is taken to mean call(Body). For example, (A) is equivalent to (B):

     | ?- assert((p(X) :- X)).            (A)
     | ?- assert((p(X) :- call(X))).      (B)
     

Ref should be uninstantiated; a range exception is signalled if Ref does not unify with its return value. This exception is signalled after the assert has been completed.

The procedure for Clause must be dynamic or undefined. If it is undefined, it is set to be dynamic.

If you want to write a term of the form Head :- Body as the argument to assert/1, you must put it in parentheses, because the operator precedence of the :-/2 functor is greater than 1000 (see ref-syn-ops-res). For example, (C) will cause a syntax error; instead you should type (D):

     | ?- assert(foo:-bar).                 (C)
     
     | ?- assert((foo:-bar)).               (D)
     

When an assert takes place, the new clause is immediately seen by any subsequent call to the procedure. However, if there is a currently active call of the procedure at the time the clause is asserted, the new clause is not encountered on backtracking by that call. See ref-mdb-exa for further explanation of what happens when currently running code is modified.

Exceptions

instantiation_error

if Head (in Clause) or M is uninstantiated.

type_error

if Head is not of type callable, or if M is not an atom, or if Body is not a valid clause body.

permission_error

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

context_error

if a cut appears in the if-part of an if-then-else.

range_error

if Ref does not unify with the returned database reference.

See Also

abolish/[1,2], dynamic/1, erase/1, multifile_assertz/1 retract/1, retractall/1, clause/[2,3]. ref-mdb-dre