Quintus Prolog

`write_term/[2,3]`

Synopsis

write_term(+Term, +Options)

write_term(+Stream, +Term, +Options)

Writes Term to the current output stream or to Stream in a format given by the options.

Arguments

Stream stream_object

a valid Prolog stream, which is open for output

Term term

the term to be written

Options list of term

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

quoted(Bool): Should atoms and functors be quoted as necessary to make them acceptable as input to read?
ignore_ops(Bool): Ignore current operator declarations? If Bool is true, compound terms are always written in the form: predicate name(arg1,...,argn).
portrayed(Bool): Call user:portray/1 for each subterm. By default the behavior of write_term/[2,3] is controlled by Options, but you can change its effect by providing clauses for the predicate portray/1.
character_escapes(Bool): Use character escapes. Bool must be true or false (the default depends on the value of the character_escapes flag as set by prolog_flag/3). If Bool is true then write_term/[2,3] tries to write layout characters (except ASCII 9 and ASCII 32) in the form \lower-case-letter, if possible; otherwise, write_term/[2,3] writes the \^control-char form. If Bool is false then it writes the actual character, without using an escape sequence.
numbervars(Bool): Should terms like '$VAR'(N) be treated specially? If Bool is true, write_term/[2,3] writes A if N=0, B if N=1, ...Z if N=25, A1 if N=26, etc. Terms of this form are generated by numbervars/3.
max_depth(N): Depth limit on printing. N is any integer; 0 means no limit and approximately 33 million is the default.

Description

write_term/[2,3] is the most general of the write family of predicates. write_term/[2,3] subsumes all predicates in the family, with the exception of portray_clause/1. That is, all write predicates can be written as calls to write_term/[2,3].

Exceptions

domain_error: Options contains an undefined option.
instantiation_error: Any of the Options arguments or Stream is not ground.
type_error: In Stream or in Options.
existence_error: Stream is syntactically valid but does not name an open stream.
permission_error: Stream names an open stream but the stream is not open for output.

Comments

If an option is specified more than once the rightmost option takes precedence. This provides for a convenient way of adding default values by putting these defaults at the front of the list of options. For example, the predicate my_write_term/2 defined as

     my_write_term(Term, Options) :-
        write_term(Term, [quoted(true),
                          numbervars(true)|Options]).

is equivalent to write_term/2 except that two of the defaults are different.

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(f('$VAR'('C')),
                        [numbervars(true)]).
     
     f(C)

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 defining a predicate like:

     var_to_names([]) :- !.
     var_to_names([=(Name,Var)|RestofPairs]) :-
          ( var(Var) ->
               Var = '$VAR'(Name)
          ; true
          ),
          var_to_names(RestofPairs).
     
     | ?- read_term([variable_names(Names)], X),
          var_to_names(Names),
          write_term(X, [numbervars(true)]),
          nl,
          fail.
     |: a(X, Y).
     a(X, Y).
     
     no

write_term/[2,3]