11.3.254 write_term/[2,3]   hookable, ISO

Synopsis

write_term(+Stream, +Term, +Options)

write_term(+Term, +Options)

Writes Term on Stream, subject to +Options.

Arguments

Stream

stream_object, must be ground

A valid open Prolog stream, defaults to the current output stream.

Term

term

Options

list of term.

A list of zero or more of the following, where Boolean must be true or false (false is the default).

quoted(Boolean)

If selected, then atoms and functors are quoted where necessary to make the result acceptable as input to read/1. write_canonical/1, writeq/1, and portray_clause/1 select this.

Any output produced by write_term/2 with the option quoted(true) will be in Normal Form C, as defined by Unicode. See ref-syn-syn-tok for further details.

ignore_ops(Boolean)

If selected, then Term is written in standard functional notation instead of using operators. write_canonical/1 and display/1 select this.

portrayed(Boolean)

If selected, then user:portray/1 is called for each non-variable subterm. print/1 selects this.

variable_names(Names)   since release 4.3

Names should be a list of Name=Var pairs, where each Name is an atom indicating the name to be used if Var is a variable occurring in the written term.

This argument has the same form as the corresponding read_term/[2,3] option and provides a convenient and safe way to preserve variable names when writing a previously read term.

numbervars(Boolean)

If selected, then terms of the form '$VAR'(N) where N is an integer >= 0 are treated specially (see numbervars/3). print/1, write/1, writeq/1, and portray_clause/1 select this.

legacy_numbervars(Boolean)   since release 4.3

If selected, then terms of the form '$VAR'(N) where N is an integer >= 0, an atom, or a code list, are treated specially, in a way consistent with versions prior to release 4.3, as follows.

If N is an integer >= 0, then the behavior is as for the numbervars/1 option. Otherwise the characters of the atom or code list are written instead of the term.

The preferred way to specify variable names is with the variable_names/1 option.

cycles(Boolean)

If selected, then the potentially cyclic term is printed in finite @/2 notation, as discussed for read_term/[2,3] (see mpg-ref-read_term).

indented(Boolean)

If selected, then the term is printed with the same indentation as is used by portray_clause/1 and listing/[0,1].

max_depth(Depth)

Depth limit on printing. Depth is an integer. 0 (the default) means no limit.

quoted_charset(Charset)

Only relevant if quoted(true) holds. Charset should be a legal value of the quoted_charset Prolog flag, where it takes its default value from. write_canonical/1 selects the value portable. See ref-lps-flg.

float_format(Spec)

How to print floats. Spec should be an atom of the form ‘~NC’, like one of the format/[2,3] character sequences for printing floats. The default is ‘~H’.

priority(Prio)

The term is printed as if in the context of an associative operator of precedence Prio, where Prio is an integer. The default is 1201, meaning that no parentheses will be printed around the term. See ref-syn-ops.

Description

This predicate subsumes the predicates that output terms except portray_clause/[1,2], which additionally prints a period and a newline, and removes module prefixes that are redundant wrt. the current type-in module.

During debugging, goals are written out by this predicate with options given by the debugger_print_options Prolog flag.

Top-level variable bindings are written out by this predicate with options given by the toplevel_print_options Prolog flag.

Exceptions

Stream errors (see ref-iou-sfh-est), plus:

instantiation_error

type_error

domain_error

in Options.

Examples

How certain options affect the output of write_term/2:

| ?- write_term('a b', [quoted(true)]).
'a b'

| ?- write_term(a+b, [ignore_ops(true)]).
+(a,b)

| ?- write_term(f('$VAR'(2)), 
                   [numbervars(true)].)
f(C)


| ?- write_term(A+B,
                      [variable_names(['Hello'=A, 'World'=B])]).
Hello+World

If your intention is to name variables such as that generated by read_term/2 with the variable_names option, then this can be done by simply passing on the variable_names option to write_term/2:

| ?- read_term(T, [variable_names(Names)]),
     write_term(T, [variable_names(Names),quoted(true)]),
     nl,
     fail.
|: a(X, Y).
a(X, Y)
no

There is, currently, no documented way to write single-occurrence variables as _, e.g. as done by portray_clause/1 (see mpg-ref-portray_clause).

See Also

ref-iou-tou, ref-lps-flg, user:portray/1.