Clauses in the database

The predicates described in this section allow you to manipulate Prolog predicate clauses in the database, typically associated with interpreted code. They will not work on predicates that have been compiled. These predicates allow you to add, review and remove clauses from the database.

Note: When a predicate is stored in the database, it is stored under a key specified by the principal functor of the predicate. For instance, the predicate append/3 would be stored under the key append(,,_). You should be sure not to use this functor for the name of a database key, B-tree or hash table unless you have designated separate code and data worlds.

Adding clauses to the database

Clauses can either be added to the database by using one of the variants of the assert predicate or an entire file of clauses may be added by using one of the variants of the consult predicate. Any clauses that are added without a body (facts) are assumed to have a body consisting of the goal true. The predicates for adding clauses to the database follow:

assert(+Clause)

assertz(+Clause)

The assertz/1 and assert/1 predicates add clauses to the end of a chain of clauses for the same predicate. If the clause that you specify has no body, assertz/1 defines the body to be true.

asserta(+Clause)

The asserta/1 predicate adds a clause to the beginning of a chain of clauses for the same predicate. If the clause that you specify has no body, asserta/1 defines the body to be true.

assert(+Clause, +N))

The assert/2 predicate adds a clause before the Nth clause in a chain of clauses. If N is -1 or greater than the number of clauses in a chain, then the asserted clause is placed at the end of the chain.

consult(+Filename)

The consult predicate reads clauses from a file and places the clauses in the database. The clauses read from Filename are appended to the end of any clauses already in the database. If no extension is given for Filename, then an extension of .ari is assumed. For example, the following loads the file named newfile.ari:

?- consult(newfile).
yes

If you want to consult a file that has no extension, you include a period at the end of the file name and enclose the file name in quotes or dollar signs ($).

If you provide the atom user as the Filename, then consult/1 will use keyboard input for clauses until you type <ctrl-z>. There must be a period followed by white space (such as a <cr> entered to terminate each clause prior to the <ctrl-z>. Input may be aborted with <ctrl-c>.

reconsult(+Filename)

When you do not want duplicate predicate definitions in the database, you should use reconsult/1. As it reads a source file, reconsult/1 searches the database for duplicate predicate definitions. When it encounters a duplicate, reconsult/1 replaces the old definition with the new definition.

[+FilenameList]

You may find it more convenient to use the list syntax to load one or more files into the database. Each member of FileNameList is either a FileName or a FileName preceded by a minus sign (-). If you precede the Filename argument with a minus sign (-), then the file will be loaded into the database with the reconsult/1 predicate. Otherwise, the file is loaded into the database with the consult/1 predicate. Again, If no filename extension is given, an extension of ari is assumed.

Reviewing clauses in the database

clause(+Head,-Body)

The clause predicate unifies Head with the head of a clause, and unifies Body with the body of the clause. The Head argument must be instantiated. Unit clauses return the atom true as their body.

Note: The clause predicate can backtrack, returning all clauses of a predicate that unify with Head and Body.

current_predicate(-Predicate)

This predicate returns through backtracking the name and arity of the predicates in the database in the form Name / Arity.

listing

listing(+Name/Arity)

listing(+[Name/Arity, Name/Arity, ...])

The listing/0 and listing/1 predicates list the clauses that are defined in the current code world for one or more predicates. If you supply no argument to the predicate, listing displays all the clauses in the database. If you supply the name and arity of a predicate, listing displays the clauses for that predicate that have the specified arity. If you supply a list of arguments, listing displays the clauses for the predicates in the list. If you only specify the name of a predicate, then listing will display clauses for all predicates with the name, regardless of arity.

Because listing uses writeq to list the clauses, the names of atoms and functors are quoted where necessary. (Quotes are not necessary when the atom name begins with a lower-case letter and consists entirely of alphanumeric characters or when it consists entirely of symbolic characters. Quotes are necessary when the atom name begins with an uppercase character letter or when it contains spaces.)

The variable names shown by listing are the names assigned by Arity/Prolog32 using the varnames predicate, rather than the names you may have given to the variables.

file_list(+Filename)

file_list(+Filename,+Name/Arity)

file_list(+Filename,+[Name/Arity,Name/Arity...])

With the file_list/0 and file_list/1 predicates, you can save the contents of a database, or specific clauses in the database, to a file. The Filename is the name of the file to which you want to save the clauses. If you do not supply a file name extension with Filename, then an extension of .ari is assumed.

Removing clauses from the database

You can remove clauses from the database one at a time or you can remove all clauses associated with a predicate. The predicates for removing clauses from the database follow:

retract(+Clause)

The retract/1 predicate nondeterministically removes clauses from the database. The first clause in the database that unifies with Clause is removed and retract/1 succeeds. Upon backtracking, the search for a unifying clause continues and if found, it is returned as unified Clause and removed. If no clauses unify, retract/1 fails.

The retract/1 predicate uses a form of soft erasure which is described in the Sequential storage of terms section. The expunge/1 predicate may be used for complete recovery of database space used by retracted clauses.

abolish(+Name/Arity)

The abolish/1 predicate removes all the clauses from the database with the specified Name and Arity. The abolish/1 predicate always succeeds.