Term Output Formats

## 11.4 Term Output Formats

- Write_term and Printf
- Other Term Output Predicates
- Default Output Options

### 11.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.

write_term/2,3
output option | printf/2,3 %..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 blank space around operators, after commas, etc.
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 the escape sequence `\n`
newlines(true) | N | print newlines as line breaks even inside quotes
nl(false) |  | do not add a newline
nl(true) | L | print a newline sequence (as with nl/1) after the term.
fullstop(false) |  | do not add a fullstop
fullstop(true) | F | terminate the term with a fullstop, so it can be read back.
flush(false) |  | do not force a flush after printing the term
flush(true) | b | flush after printing the term
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
precedence(Prec) |  | print assuming given context precedence
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).
variable_names(VarNames) |  | 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) | v | print variables using a system-generated name, e.g., _123
variables(full) | V | print variables as source name plus 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)])

### 11.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),
>                   numbervars(true)]).
>     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)]).

### 11.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.