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).

• 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)]).

 list_predicates(:Preds:list(pi), :Spec, +Options) is det[private]

 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)

 meta_implies_transparent(+Head) is semidet[private]

True if the meta-declaration Head implies that the predicate is transparent.

 list_clause(+Term, +ClauseRef, +ContextModule, +Options)[private]

 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.

 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_clause_string(+File, +Line, -String, -Repositioned)[private]

True when String is the source text for a clause starting at Line in File.

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

 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.

 portray_or(+Term, +Indent, +Priority, +Out) is det[private]

 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.

 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.

 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
]                       ]

 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.

 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.

 inc_indent(+Indent0, +Inc, -Indent)[private]

Increment the indent with logical steps.

 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.

 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).

• 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)]).

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

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