.. _library_listing:

listing

This library provides support for listing object dynamic predicate clauses. The predicates must (also) be declared using a scope directive to make them visible to the listing predicates.

API documentation

Open the `../../apis/library_index.html#listing <../../apis/library_index.html#listing>`__ link in a web browser.

Loading

To load all entities in this library, load the loader.lgt utility file:

::

| ?- logtalk_load(listing(loader)).

Testing

To test this library predicates, load the tester.lgt file:

::

| ?- logtalk_load(listing(tester)).

Usage

This library provides a listing category that can be imported by any number of objects. The main predicates are declared public. If you want to restrict their scope, use protected or private import. For example:

::

:- object(data_store, imports(private::listing)).

debug :- ^^listing(data/4). ...

:- end_object.

The listing category provides a bare-bones portray_clause/1 predicate implementation. As this predicate is called (by the listing/0-1 predicates) using the (::)/1 control construct, the object importing the category can easily override the inherited definition with its own or with a call to the backend system native implementation of the predicate. For example, assuming a backend that provides portray_clause/1 as a built-in predicate, we can write:

::

:- object(thing, imports(listing)).

:- uses(user, [portray_clause/1]). ...

:- end_object.

The main predicate, listing/1, accepts as argument a predicate indicator, a non-terminal indicator, or a clause head template (to list only clauses with a matching head).

This library is often useful as a debugging helper. For example, assuming that we want to list dynamic predicate clauses for an object data compiled (or created) with the complements flag set to allow, we can hot patch it to add the listing category:

::

| ?- create_category(patch, [extends(listing),complements(data)], [], []). yes

| ?- data::listing. ...

Another example:

::

| ?- create_category( patch, [extends(listing),complements(data)], [public(debug/1)], [(debug(Key) :- ::listing(p(Key,Datum)))] ). yes

| ?- data::debug(k42). ...

Note that the semantics of complementing categories require that we use the (::)/2 control construct instead of the (^^)/2 control construct as a super call would be interpreted as made from the complemented object.