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,3Format char for printf %..wMeaning
as(term) do not assume any particular meaning of the printed term
as(clause)Cprint the term as a clause (apply clause transformations)
as(goal)Gprint the term as a goal (apply goal transformations)
attributes(none) do not print any variable attributes
attributes(pretty)mprint attributes using the corresponding print handlers
attributes(full)Mprint the full contents of all variable attributes
compact(false) print extra blank space (around operators, after commas, etc.) for better readability
compact(true)Kdon’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)Dprint 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 the escape sequence \n
newlines(true)Nprint newlines as line breaks even inside quotes
nl(false) do not add a newline
nl(true)Lprint a newline sequence (as with nl/1) after the term. If this is used together with the fullstop(true) option, this newline serves as the blank space after the fullstop
fullstop(false) do not add a fullstop
fullstop(true)F terminate the term with a fullstop, so it can be read back. If necessary, an extra space will be inserted before the fullstop, in order to separate it from the end of the term
flush(false) do not force a flush after printing the term
flush(true)bflush after printing the term
numbervars(false) do not treat ’$VAR’/1 terms specially
numbervars(true)Iprint 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)Oignore operator declarations and print functor notation
portrayed(false) do not use portray/1,2
portrayed(true)Pcall the user-defined predicate portray/1,2 for printing
precedence(Prec) print assuming given context precedence
quoted(false) do not print quotes around strings or atoms
quoted(true)Qquote strings and atoms if necessary
transform(true) apply portray transformations (write macros)
transform(false)Tdo not apply portray transformations (write macros).
variable_names(VarName) use the given variable names when printing the corresponding variables. VarsNames is a list of terms of the form Name=Var.
variables(default) print variables using their source name (if available)
variables(raw)vprint variables using a system-generated name, e.g., _123
variables(full)Vprint 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).

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.

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, [numbervars(true)]).
writeln(X) :- write_term(X, [numbervars(true)]), 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), numbervars(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