% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(listing): List programs and pretty print clauses}

\label{sec:listing}

\begin{tags}
\mtag{To be done}- More settings, support \textit{Coding Guidelines for Prolog} and make
the suggestions there the default. \\- Provide persistent user customization
\end{tags}

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

\begin{itemize}
    \item \predref{listing}{0} lists a module.
    \item \predref{listing}{1} lists a predicate or matching clause
    \item \predref{listing}{2} lists a predicate or matching clause with options
    \item \predref{portray_clause}{2} pretty-prints a clause-term
\end{itemize}

Layout can be customized using \file{library(settings)}. The effective settings
can be listed using \predref{list_settings}{1} as illustrated below. Settings can
be changed using \predref{set_setting}{2}.

\begin{code}
?- 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.
...
\end{code}

\vspace{0.7cm}

\begin{description}
    \predicate{listing}{0}{}
Lists all predicates defined in the calling module. Imported
predicates are not listed. To list the content of the module
\const{mymodule}, use one of the calls below.

\begin{code}
?- mymodule:listing.
?- listing(mymodule:_).
\end{code}

    \predicate[det]{listing}{1}{:What}
\nodescription
    \predicate[det]{listing}{2}{:What, +Options}
List matching clauses. \arg{What} is either a plain specification or a
list of specifications. Plain specifications are:

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

\begin{code}
?- listing(append([], _, _)).
lists:append([], L, L).
\end{code}

    \item A clause reference as obtained for example from \predref{nth_clause}{3}.
\end{itemize}

The following options are defined:

\begin{description}
    \termitem{variable_names}{+How}
One of \const{source} (default) or \const{generated}. If \const{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.
    \termitem{source}{+Bool}
If \const{true} (default \const{false}), extract the lines from the source
files that produced the clauses, i.e., list the original source
text rather than the \textit{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 \textit{multifile}
predicates. For example:

\begin{code}
?- listing(file_search_path, [source(true)]).
\end{code}

\end{description}

    \predicate[det]{portray_clause}{1}{+Clause}
\nodescription
    \predicate[det]{portray_clause}{2}{+Out:stream, +Clause}
\nodescription
    \predicate[det]{portray_clause}{3}{+Out:stream, +Clause, +Options}
Portray `\arg{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 \arg{Clause} contains attributed variables, these are
treated as normal variables.

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

\arg{Options} processed in addition to \predref{write_term}{2} options:

\begin{description}
    \termitem{variable_names}{+Bindings}
See above and \predref{write_term}{2}.
    \termitem{indent}{+Columns}
Left margin used for the clause. Default \verb$0$.
    \termitem{module}{+Module}
\arg{Module} used to determine whether a goal resolves to a meta
predicate. Default \const{user}.
\end{description}
\end{description}