Previous Up

10.4  Term Output Formats

10.4.1  Write_term and Printf

The way ECLiPSe terms are printed can be customised in a number of ways. The most flexible predicates to print terms are write_term/3 and printf/3. They both allow all variants of term output, but the format is specified in a different way. The following figure gives an overview.
Output Option for write_term/2,3 Format char for printf %..w Meaning
as(term)   do not assume any particular meaning of the printed term
as(clause) C print the term as a clause (apply clause transformations)
as(goal) G print the term as a goal (apply goal transformations)
attributes(none)   do not print any variable attributes
attributes(pretty) m print attributes using the corresponding print handlers
attributes(full) M print the full contents of all variable attributes
compact(false)   print extra blank space (around operators, after commas, etc.) for better readability
compact(true) K don't print blank space unless necessary
depth(Max) <Max> print the term only up to a maximum nesting depth of Max (a positive integer)
depth(0)   observe the stream-specific or global flag 'print_depth'
depth(full) D print the whole term (may loop when the term is cyclic!)
dotlists(false)   write lists in square bracket notation, e.g. [a,b]
dotlists(true) . write lists as terms with functor ./2
newlines(false)   print newlines inside quotes as escape sequence \n
newlines(true) N print newlines as line breaks even inside quotes
numbervars(false)   do not treat '$VAR'/1 terms specially
numbervars(true) I print terms of the form '$VAR'(N) as named variables: '$VAR'(0) is printed as A, '$VAR'(25) as Z, '$VAR'(26) as A1 and so on. When the argument is an atom or a string, just this argument is printed.
operators(true)   obey operator declarations and print prefix/infix/postfix
operators(false) O ignore operator declarations and print functor notation
portrayed(false)   do not use portray/1,2
portrayed(true) P call the user-defined predicate portray/1,2 for printing
quoted(false)   do not print quotes around strings or atoms
quoted(true) Q quote strings and atoms if necessary
transform(true)   apply portray transformations (write macros)
transform(false) T do not apply portray transformations (write macros).
variables(default)   print variables using their source name (if available)
variables(raw) v print variables using a system-generated name, e.g. _123
variables(full) V print variables using source name followed by a number, e.g. Alpha_132
variables(anonymous) _ print every variable as a simple underscore

Overview of term output options (see write_term/3 for more details)
The write_term/2 and write_term/3 predicates print a single ECLiPSe term and accept a list of output options (first column in the table 10.4.1).

The printf/2 and printf/3 predicates are similar to C's printf(3) function, but provide additional format characters for printing ECLiPSe terms. The basic format string for printing arbitrary terms is "%w". Additional format characters can go between % and w, according to the second column in the table 10.4.1.

For example, the following pairs of printing goals are equivalent:
printf("%mw",  [X])  <->   write_term(X, [attributes(pretty)])
printf("%O.w", [X])  <->   write_term(X, [operators(false),dotlist(true)])
printf("%5_w", [X])  <->   write_term(X, [depth(5),variables(anonymous)])

10.4.2  Other Term Output Predicates

The other term output predicates write/1, writeln/1, writeq/1, write_canonical/1, display/1, print/1 can all be defined in terms of write_term/2 (or, similarly in terms of printf/2) as follows:
write(X)   :- write_term(X, []).
writeln(X)   :- write_term(X, []), nl.
writeq(X)  :- write_term(X, [variables(raw), attributes(full),
                transform(false), quoted(true), depth(full)]).
write_canonical(X) :- write_term(X, [variables(raw), attributes(full),
                transform(false), quoted(true), depth(full),
                dotlist(true), operators(false)]).
display(X) :- write_term(X, [dotlist(true), operators(false)]).
print(X)   :- write_term(X, [portrayed(true)]).

10.4.3  Default Output Options

It is possible to set default output options for an output stream in order to globally affect all output to this particular stream. The set_stream_property/3 predicate can be used to assign default options (in the same form as accepted by write_term/3) to a stream. These options will then be observed by all output predicates which do not override the particular option.

Previous Up