Did you know ... Search Documentation:
listing.pl -- List programs and pretty print clauses
PublicShow source

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

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
Source 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:_).
Source listing(:What) is det
Source 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).
  • A clause reference as obtained for example from nth_clause/3.

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)]).
Source list_predicates(:Preds:list(pi), :Spec, +Options) is det[private]
Source declaration(:Head, +Module, -Decl) is nondet[private]
True when the directive Decl (without :-/1) needs to be used to restore the state of the predicate Head.
To be done
- Answer subsumption, dynamic/2 to deal with incremental and abstract(Depth)
Source meta_implies_transparent(+Head) is semidet[private]
True if the meta-declaration Head implies that the predicate is transparent.
Source list_clause(+Term, +ClauseRef, +ContextModule, +Options)[private]
Source restore_variable_names(+Module, +Head, +Body, +Ref, +Options) is det[private]
Try to restore the variable names from the source if the option variable_names(source) is true.
Source name_other_vars(+Term, +Bindings) is det[private]
Give a '$VAR'(N) name to all remaining variables in Term, avoiding clashes with the given variable names.
Source source_clause_string(+File, +Line, -String, -Repositioned)[private]
True when String is the source text for a clause starting at Line in File.
Source portray_clause(+Clause) is det
Source portray_clause(+Out:stream, +Clause) is det
Source portray_clause(+Out:stream, +Clause, +Options) is det
Portray `Clause' on the current output stream. Layout of the clause is to our best standards. Deals with control structures 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.

Variable names are by default generated using numbervars/4 using the option singletons(true). This names the variables A, B, ... and the singletons _. Variables can be named explicitly by binding them to a term '$VAR'(Name), where Name is an atom denoting a valid variable name (see the option numbervars(true) from write_term/2) as well as by using the variable_names(Bindings) option from write_term/2.

Options processed in addition to write_term/2 options:

variable_names(+Bindings)
See above and write_term/2.
indent(+Columns)
Left margin used for the clause. Default 0.
module(+Module)
Module used to determine whether a goal resolves to a meta predicate. Default user.
Source portray_body(+Term, +Indent, +DoIndent, +Priority, +Out, +Options)[private]
Write Term at current indentation. If DoIndent is 'indent' we must first call nlindent/2 before emitting anything.
Source portray_or(+Term, +Indent, +Priority, +Out) is det[private]
Source infix_op(+Op, -Left, -Right) is semidet[private]
True if Op is an infix operator and Left is the max priority of its left hand and Right is the max priority of its right hand.
Source or_layout(@Term) is semidet[private]
True if Term is a control structure for which we want to use clean layout.
To be done
- Change name.
Source portray_meta(+Out, +Call, +MetaDecl, +Options)[private]
Portray a meta-call. If Call contains non-primitive meta-calls we put each argument on a line and layout the body. Otherwise we simply print the goal.
 portray_list(+List, +Indent, +Out)[private]
Portray a list like this. Right side for improper lists
[ element1,             [ element1
  element2,     OR      | tail
]                       ]
Source pprint(+Out, +Term, +Priority, +Options)[private]
Print Term at Priority. This also takes care of several formatting options, in particular:
  • {}(Arg) terms are printed with aligned arguments, assuming that the term is a body-term.
  • Terms that do not fit on the line are wrapped using pprint_wrapped/3.
To be done
- Decide when and how to wrap long terms.
 listing_write_options(+Priority, -WriteOptions) is det[private]
WriteOptions are write_term/3 options for writing a term at priority Priority.
Source nlindent(+Out, +Indent)[private]
Write newline and indent to column Indent. Uses the setting listing:tab_distance to determine the mapping between tabs and spaces.
Source inc_indent(+Indent0, +Inc, -Indent)[private]
Increment the indent with logical steps.
Source comment(+Format, +Args)[private]
Emit a comment.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.

Source listing(:What) is det
Source 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).
  • A clause reference as obtained for example from nth_clause/3.

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)]).
Source portray_clause(+Clause) is det
Source portray_clause(+Out:stream, +Clause) is det
Source portray_clause(+Out:stream, +Clause, +Options) is det
Portray `Clause' on the current output stream. Layout of the clause is to our best standards. Deals with control structures 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.

Variable names are by default generated using numbervars/4 using the option singletons(true). This names the variables A, B, ... and the singletons _. Variables can be named explicitly by binding them to a term '$VAR'(Name), where Name is an atom denoting a valid variable name (see the option numbervars(true) from write_term/2) as well as by using the variable_names(Bindings) option from write_term/2.

Options processed in addition to write_term/2 options:

variable_names(+Bindings)
See above and write_term/2.
indent(+Columns)
Left margin used for the clause. Default 0.
module(+Module)
Module used to determine whether a goal resolves to a meta predicate. Default user.
Source portray_clause(+Clause) is det
Source portray_clause(+Out:stream, +Clause) is det
Source portray_clause(+Out:stream, +Clause, +Options) is det
Portray `Clause' on the current output stream. Layout of the clause is to our best standards. Deals with control structures 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.

Variable names are by default generated using numbervars/4 using the option singletons(true). This names the variables A, B, ... and the singletons _. Variables can be named explicitly by binding them to a term '$VAR'(Name), where Name is an atom denoting a valid variable name (see the option numbervars(true) from write_term/2) as well as by using the variable_names(Bindings) option from write_term/2.

Options processed in addition to write_term/2 options:

variable_names(+Bindings)
See above and write_term/2.
indent(+Columns)
Left margin used for the clause. Default 0.
module(+Module)
Module used to determine whether a goal resolves to a meta predicate. Default user.