listing.pl -- List programs and pretty print clauses

This module implements listing code from the internal representation in a human readable format.

• listing/0 lists a module.
• listing/1 lists a predicate or matching clause
• listing/2 lists a predicate or matching clause with options
• portray_clause/2 pretty-prints a clause-term

Layout can be customized using library(settings). The effective settings can be listed using list_settings/1 as illustrated below. Settings can be changed using set_setting/2.

?- list_settings(listing).
========================================================================
Name                      Value (*=modified) Comment
========================================================================
listing:body_indentation  4              Indentation used goals in the body
listing:tab_distance      0              Distance between tab-stops.
...

To be done

- More settings, support Coding Guidelines for Prolog and make the suggestions there the default.

- Provide persistent user customization

 listing

Lists all predicates defined in the calling module. Imported predicates are not listed. To list the content of the module mymodule, use one of the calls below.

?- mymodule:listing.
?- listing(mymodule:_).

 listing(:What) is det

 listing(:What, +Options) is det

List matching clauses. What is either a plain specification or a list of specifications. Plain specifications are:

• Predicate indicator (Name/Arity or Name//Arity) Lists the indicated predicate. This also outputs relevant declarations, such as multifile/1 or dynamic/1.
• A Head term. In this case, only clauses whose head unify with Head are listed. This is illustrated in the query below that only lists the first clause of append/3.

  ?- listing(append([], _, _)).
  lists:append([], L, L).

The following options are defined:

variable_names(+How)

One of source (default) or generated. If source, for each clause that is associated to a source location the system tries to restore the original variable names. This may fail if macro expansion is not reversible or the term cannot be read due to different operator declarations. In that case variable names are generated.

source(+Bool)

If true (default false), extract the lines from the source files that produced the clauses, i.e., list the original source text rather than the decompiled clauses. Each set of contiguous clauses is preceded by a comment that indicates the file and line of origin. Clauses that cannot be related to source code are decompiled where the comment indicates the decompiled state. This is notably practical for collecting the state of multifile predicates. For example:

?- listing(file_search_path, [source(true)]).

 portray_clause(+Clause) is det

 portray_clause(+Out:stream, +Clause) is det

 portray_clause(+Out:stream, +Clause, +Options) is det

Portray `Clause' on the current output stream. Layout of the clause is to our best standards. As the actual variable names are not available we use A, B, ... Deals with ';', '|', '->' and calls via meta-call predicates as determined using the predicate property meta_predicate. If Clause contains attributed variables, these are treated as normal variables.

If Options is provided, the option-list is passed to write_term/3 that does the final writing of arguments.

 listing(:What) is det

 listing(:What, +Options) is det

List matching clauses. What is either a plain specification or a list of specifications. Plain specifications are:

• Predicate indicator (Name/Arity or Name//Arity) Lists the indicated predicate. This also outputs relevant declarations, such as multifile/1 or dynamic/1.
• A Head term. In this case, only clauses whose head unify with Head are listed. This is illustrated in the query below that only lists the first clause of append/3.

  ?- listing(append([], _, _)).
  lists:append([], L, L).

The following options are defined:

variable_names(+How)

One of source (default) or generated. If source, for each clause that is associated to a source location the system tries to restore the original variable names. This may fail if macro expansion is not reversible or the term cannot be read due to different operator declarations. In that case variable names are generated.

source(+Bool)

If true (default false), extract the lines from the source files that produced the clauses, i.e., list the original source text rather than the decompiled clauses. Each set of contiguous clauses is preceded by a comment that indicates the file and line of origin. Clauses that cannot be related to source code are decompiled where the comment indicates the decompiled state. This is notably practical for collecting the state of multifile predicates. For example:

?- listing(file_search_path, [source(true)]).

 portray_clause(+Clause) is det

 portray_clause(+Out:stream, +Clause) is det

 portray_clause(+Out:stream, +Clause, +Options) is det

Portray `Clause' on the current output stream. Layout of the clause is to our best standards. As the actual variable names are not available we use A, B, ... Deals with ';', '|', '->' and calls via meta-call predicates as determined using the predicate property meta_predicate. If Clause contains attributed variables, these are treated as normal variables.

If Options is provided, the option-list is passed to write_term/3 that does the final writing of arguments.

 portray_clause(+Clause) is det

 portray_clause(+Out:stream, +Clause) is det

 portray_clause(+Out:stream, +Clause, +Options) is det

Portray `Clause' on the current output stream. Layout of the clause is to our best standards. As the actual variable names are not available we use A, B, ... Deals with ';', '|', '->' and calls via meta-call predicates as determined using the predicate property meta_predicate. If Clause contains attributed variables, these are treated as normal variables.

If Options is provided, the option-list is passed to write_term/3 that does the final writing of arguments.