write_term/2

Availability:built-in

[ISO]write_term(+Term, +Options)

The predicate write_term/2 is the generic form of all Prolog term-write predicates. Valid options are:

attributes(Atom)

Define how attributed variables (see section 8.1) are written. The default is determined by the Prolog flag write_attributes. Defined values are ignore (ignore the attribute), dots (write the attributes as {...}), write (simply hand the attributes recursively to write_term/2) and portray (hand the attributes to attr_portray_hook/2).

back_quotes(Atom)

Fulfills the same role as the back_quotes prolog flag. Notably, the value string causes string objects to be printed between back quotes and symbol_char causes the backquote to be printed unquoted. In all other cases the backquote is printed as a quoted atom.

brace_terms(Bool)

If true (default), write {}(X) as {X}. See also dotlists and ignore_ops.

blobs(Atom)

Define how non-text blobs are handled. By default, this is left to the write handler specified with the blob type. Using portray, portray/1 is called for each blob encountered. See section 12.4.10.

character_escapes(Bool)

If true and quoted(true) is active, special characters in quoted atoms and strings are emitted as ISO escape sequences. Default is taken from the reference module (see below).

character_escapes_unicode(Bool)

If true and character_escapes(true) and quoted(true) are active escapted characters are written using \uXXXX or \UXXXXXXXX syntax. The default depends on the Prolog flag character_escapes_unicode

cycles(Bool)

If true (default), cyclic terms are written as @(Template, Substitutions), where Substitutions is a list Var = Value. If cycles is false, max_depth is not given, and Term is cyclic, write_term/2 raises a domain_error.^{108The
cycles option and the cyclic term representation using the @-term are
copied from SICStus Prolog. However, the default in SICStus is set to false
and SICStus writes an infinite term if not protected by, e.g., the depth_limit
option.} See also the cycles option in read_term/2.

dotlists(Bool)

If true (default false), write lists using the dotted term notation rather than the list notation.^{109Copied
from ECLiPSe.} Note that as of version 7, the list constructor is '[|]'. Using dotlists(true), write_term/2 writes a list using‘.’as constructor. This is intended for communication with programs such as other Prolog systems, that rely on this notation. See also the option no_lists(true) to use the actual SWI-Prolog list functor.

fullstop(Bool)

If true (default false), add a fullstop token to the output. The dot is preceded by a space if needed and followed by a space (default) or newline if the nl(true) option is also given.^{110Compatible with ECLiPSe}

float_format(+Atom)

Print floating point numbers using format/2 as format(Atom, [Float]). The default is ~h. This option is compatible with SICStus. See format/2 for valid format specifiers and the integer_format option for additional comments.

ignore_ops(Bool)

If true, the generic term representation (<functor>(<args> ... )) will be used for all terms. Otherwise (default), operators will be used where appropriate.^{111In
traditional systems this flag also stops the syntactic sugar notation
for lists and brace terms. In SWI-Prolog, these are controlled by the
separate options dotlists and brace_terms}.

integer_format(+Atom)

Print integers using format/2 as format(Atom, [Int]). The default is ~d. This allows to print integers using an alternative radix, using e.g. ~16r or 0x~16r or to use digit grouping using e.g. ~D. Note that the user is reponsible to provide a format that produces valid Prolog syntax if the term must be readable by Prolog. The format must accept exactly one argument. If that is not satisfied, printing an integer results in an exception. See format/2 for for valid format specifiers.

max_depth(Integer)

If the term is nested deeper than Integer, print the remainder as ellipses ( ... ). A 0 (zero) value (default) imposes no depth limit. This option also delimits the number of printed items in a list. Example:

?- write_term(a(s(s(s(s(0)))), [a,b,c,d,e,f]),
              [max_depth(3)]).
a(s(s(...)), [a, b|...])
true.

Used by the top level and debugger to limit screen output. See also the Prolog flags answer_write_options and debugger_write_options.

module(Module)

Define the reference module (default user). This defines the default value for the character_escapes option as well as the operator definitions to use. If Module does not exist it is not created and the user module is used. See also op/3 and read_term/2, providing the same option.

nl(Bool)

Add a newline to the output. See also the fullstop option.

no_lists(Bool)

Do not use list notation. This is similar to dotlists(true), but uses the SWI-Prolog list functor, which is by default '[|]' instead of the ISO Prolog '.'. Used by display/1.

numbervars(Bool)

If true, terms of the format $VAR(N), where N is an integer that fits in 64-bit,^{112Larger
integers are ignored. As no term that fits into memory can have that
many variables, this is not a restriction.} will be written as a variable name. For N in 0..25 it emits A..Z. For higher numbers it emits An..Zn, where n is N//26. For negative numbers it emits S_N, which is used for representing shared sub-terms and cyclic terms.

If N is an atom that is syntactically a valid variable it is written without quotes. This extension allows for writing variables with user-provided names.

The default for this flag is false unless the portrayed option is enabled. See also numbervars/3 and the option variable_names.

partial(Bool)

If true (default false), do not reset the logic that inserts extra spaces that separate tokens where needed. This is intended to solve the problems with the code below. Calling write_value(.) writes .., which cannot be read. By adding partial(true) to the option list, it correctly emits . .. Similar problems appear when emitting operators using multiple calls to write_term/3.

write_value(Value) :-
        write_term(Value, [partial(true)]),
        write('.'), nl.

In addition, if the priority is not 1200 or 999 this assumes we are printing an operant of an operator. If Term is an atom that is also an operator it will always be embraced.^{113If
the priority is 1200 it is assumed to be a toplevel term and if the
priority is 999 it is assumed to be a list element or argument of a
compound term.}

portray(Bool)

Same as portrayed(Bool). Deprecated.

portray_goal(:Goal)

Implies portray(true), but calls Goal rather than the predefined hook portray/1. Goal is called through call/3, where the first argument is Goal, the second is the term to be printed and the 3rd argument is the current write option list. The write option list is copied from the write_term call, but the list is guaranteed to hold an option priority that reflects the current priority.

portrayed(Bool)

If true, the hook portray/1 is called before printing a term that is not a variable. If portray/1 succeeds, the term is considered printed. See also print/1. The default is false. This option is an extension to the ISO write_term options. If this option is set, the numbervars option defaults to true.

priority(Integer)

An integer between 0 and 1200 representing the‘context priority’. Default is 1200. Can be used to write partial terms appearing as the argument to an operator. For example:

        format('~w = ', [VarName]),
        write_term(Value, [quoted(true), priority(699)])

quoted(Bool)

If true, atoms and strings that need quotes will be quoted. The default is false. If character_escapes is true (default) characters in the quoted atom or string are escaped using backslash (\) sequences. To the minimum, the quote itself, newlines and backslash characters are escaped to make the output valid for read/1. All unassigned unicode characters and characters in the Unicode separator (Z*) and control (C*) classes except for the ASCII space (\u0020) are escaped. For those characters for which an ISO Prolog single character escape, e.g., \t is defined, this is used. Otherwise the output depends on the option character_escapes_unicode. If this flag applies(default) the widely accepted \uXXXX or \UXXXXXXXX is used. Otherwise the ISO Prolog \x<hex>\ syntax is used.

quote_non_ascii(Bool)

Quote an atom that contains non-ASCII, i.e., larger than 127 code points. The Prolog standard only describes non-quoted atom syntax containing ASCII characters. While SWI-Prolog extends this to Unicode (see section 2.15.1.9), transferring atoms holding non-ASCII text to other Prolog implementations may cause problems. This flag is used by write_canonical/1.

spacing(+Spacing)

Determines whether and where extra white space is added to enhance readability. The default is standard, adding only space where needed for proper tokenization by read_term/3. Currently, the only other value is next_argument, adding a space after a comma used to separate arguments in a term or list.

variable_names(+List)

Assign names to variables in Term. List is a list of terms Name = Var, where Name is an atom that represents a valid Prolog variable name. Terms where Var is bound or is a variable that does not appear in Term are ignored. Raises an error if List is not a list, one of the members is not a term Name = Var, Name is not an atom or Name does not represent a valid Prolog variable name.

The implementation binds the variables from List to a term '$VAR'(Name). Like write_canonical/1, terms that where already bound to '$VAR'(X) before write_term/2 are printed normally, unless the option numbervars(true) is also provided. If the option numbervars(true) is used, the user is responsible for avoiding collisions between assigned names and numbered names. See also the variable_names option of read_term/2.

Possible variable attributes (see section 8.1) are ignored. In most cases one should use copy_term/3 to obtain a copy that is free of attributed variables and handle the associated constraints as appropriate for the use-case.