pereira@sri-unix.UUCP (08/15/83)
File: Mec:PP.Hlp Author: R.A.O'Keefe Updated: 27 July 82
#source.
The source code for the Prolog pretty-printer may be found in the file
Mec:PP.Pl. It lived in [400,441,PlOdds] for a while, but is generally
useful. The help file is Mec:PP.Hlp.
#needs.
To get help, Mec:Helper.Pl must be compiled.
To work with unloaded files, Mec:Ixref.Pl must be compiled, or
at least suitable '$defn'(MostGeneralTerm, File) facts must be
put in the database. No utilities are used, and the program will
run on its own if it has to.
#purpose.
PP is a pretty-printer for Prolog programs. The Prolog system has a
built in predicate 'listing' already, but it is relatively inflexible.
The original idea of PP was to have variable names printed as words
rather than as numbers with a prefixed underscore. The routine which
did that has now been commented out, as Prolog versions 3.45 and later
will print terms $VAR(N) in a suitable format. 'listing' benefits from
that too. Another thing that PP does is to display clauses in what I
consider to be a more attractive form. Others may disagree, but it is
easy to make a copy of PP and change it to do what you like; there is
no easy way to change 'listing'. PP can also find partially specified
predicates, e.g. pp "pp_*" will display all the predicates whose names
start with "pp_". Finally, PP can make use of IXREF's database to
locate predicates which are compiled or not loaded, or to report on
all the predicates defined in a given file.
#commands.
ca, ca Pattern, ca(Pattern, List) -- see ca. Current Atoms
cf, cf Fn/Arit, cf(Fn/Arit, List) -- see cf. Current Functors
co, co Pattern, co(Pattern, List) -- see co. Current Operators
cp, cp Pattern, cp(Pattern, List) -- see cp. Current Predicates
Command on File -- see on. output goes to File
pp, pp Pattern. -- see pp. Print Predicate
pp help -- display list of topics
#ca,atoms,current_atom.
ca - display all Current Atoms
ca Pattern - display all Current Atoms whose names match Pattern
ca(Pattern,List) - return a list of all selected atoms.
The pattern in this case is an AtomPattern, which is one of
an atom - matches itself
a variable - matches any atom
a string - match on name with "wild cards" "*" and "?"
a list - matches anything matched by any element of the list
Thus (ca "*") and (ca _) both find all the atoms. Note that a variable used
as a pattern will NOT be bound. There isn't much point in asking (ca fred),
as it must always be true.
#cf,functors,current_functor.
cf - display all current functors
cf Pattern - display all matching functors
cf(Pattern,List) - return all matching functors
The result is a list of functors represented as Functor/Arity, sorted into
increasing alphabetic order of Functor then increasing numeric order of
Arity. The Pattern here is a TermPattern, which is one of
AtomPat/Range - matches F/A if AtomPat matches F and A is in Range
AtomPat - matches F/A if AtomPat matches F
a list - matches anything matched by an element of the list
F(_1,..,_N) - matches F/N
See the topic 'ranges' for a description of ranges. Briefly, to see all
the genuine functors, cf "*" / >(0) will exclude F/0. E.g. if you know
that the bag utilities use a functor 'bag' with arity somewhere between
2 and 4, cf bag/(2-4) will check which arities are used.
#co,operators,current_op.
co - display all operator definitions
co Pattern - display selected operators
co(Pattern,List) - return selected operators
co(Prec,Type,Name) - same as co(op(Pred,Type,Name)).
An operator pattern is
op(Range, AtomPat, AtomPat)
or AtomPat - same as op(_,_,AtomPat)
All operators whose names and types match the respective patterns, and
whose priorities are in the given range. The result is a list of
op(P,T,A) terms ordered by numeric priority P, then by type T where
fx < fy < xf < xfx < xfy < yf < yfx < yfy, then finally by name A. That
is the ordering provided by Prolog, and it would be too hard to change.
#cp,predicates,current_predicate.
cp - display all current predicates
cp Patt - display all predicates matching Patt
cp(Patt,Preds) - return all Preds matching Patt.
cp locates current predicates (those which have at least one interpreted
clause) and returns a list of Functor/Arity specifications. The pattern
is a TermPattern as for cf (q.v.) but may also be "from(File)". This is
only useful when you have used IXREF to find out which files predicates
come from, this will tell you which predicates come from that file. E.g.
cref('mec:pp.pl', '$defn'), cp from('mec:pp.pl').
#on,redirection,files.
You can redirect the output of any Pretty-Print command <Command> by
writing "<Command> on <File>", where File is an atom of the sort that
Prolog usually uses for file names. The File will be selected for
output, the Command will be called, and the original output file selected
again. Note that File is NOT closed. Thus you can say
pp op on foobaz.
pp "pp_*" on foobaz.
pp "cp_*" on foobaz.
close(foobaz).
Beware, you have to close the file yourself sometime.
This feature is not restricted to pp commands; any goal which writes to
a file may have its output redirected this way.
#pp,print,listing.
pp -- pretty-print entire program (with operators)
pp help -- display list of topics
pp Pattern -- pretty-print selected predicates
A bare "pp" pretty-prints the entire program (though not things in the
data base). With a Pattern argument, all the Predicates matching the
pattern are pretty-printed. The predicates are displayed in alphabetic
order. If the pattern is a specific Functor/Arity specification, pp
will do something extra. Normally, if a predicate is compiled or not
loaded, pp just won't notice it. But if you ask for it specifically,
and if IXREF (q.v.) has noticed which file the predicate is defined in,
pp will read that file and print the relevant clauses. Note that the
file will NOT be loaded. Also, pp from(File) will display predicates
from that file in alphabetic order, even ones which have been abolished
or compiled. (It will look at interpreted clauses if they exist,
otherwise it will go to the file.)
#ranges.
A range is
a variable - _ matches any number
a number - N matches N
a pair L-U - L-U matches N if L<=N<=U
a relational op and argument - R(L) matches N if N R L
[ Range1 | Range2] - alternatives
For example, [<(2), 4-6, 9, >(10)] will match 0, 1, 4, 5, 6, 9, and
11, 12, 13,... This is useful for specifying arities or priorities.