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
• 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  8              Indentation used goals in the body
listing:tab_distance      8              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:

?- mymodule:listing.

 listing(:What)

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([], A, A).

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

 meta_implies_transparent(+Head) is semidet[private]

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

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

 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.