11.3.12 assertz/[1,2]   ISO

Synopsis

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

assertz(+Clause)

assertz(+Clause, -Ref)

Clause will follow all existing clauses in the database.

Arguments

:Clause

callable, must be nonvar

A valid dynamic Prolog clause.

Ref

db_reference, must be var

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, then M must be an atom.

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

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

| ?- assertz((p(X) :- X)).             (A)
| ?- assertz((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, then it is set to be dynamic.

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, then the new clause is not encountered on backtracking by that call. See ref-mdb-bas for further explanation of what happens when currently running code is modified.

Any uninstantiated variables in the Term will be replaced by brand new, unattributed variables (see ref-sem-sec).

Exceptions

instantiation_error

Head (in Clause) or M is uninstantiated.

type_error

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

permission_error

the procedure corresponding to Head is not dynamic

uninstantiation_error

Ref is not a variable

Examples

| ?- assertz(mammal(kangaroo)).
yes
| ?- assertz(mammal(whale), Ref).
Ref = '$ref'(1258504,210) ? RET
yes
| ?- listing(mammal).
mammal(kangaroo).
mammal(whale).
yes

See Also

ref-mdb-acd.