# `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 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.