
write_term(+Stream, ?Term, ++Options)

   The term Term is written to the output stream Stream in a format specified by Options

Arguments
   Stream              Stream handle or alias (atom)
   Term                An arbitrary term
   Options             List of option terms

Type
   Term I/O

Description

    This is a generalisation of the predicates write/2, writeq/2, print/2,
    display/2, write_canonical/2. It is used to write an arbitrary term
    Term onto the current output stream according to the given options.
    Options is a (possibly empty) list of the options listed below.

    Defaults: for Bool options, the default is false,
    unless otherwise noted.  Defaults may also be overridden by the
    output_options stream property (see set_stream_property/3).


    anonymous(Vars)
        accepts a list of variables, and prints these variables as _
        (anonymous variables) when they occur in Term.  The variables
        should be singletons, i.e. occur only once in the printed
        term, otherwise sharing information will be lost.
        Any nonvariable terms in Vars are ignored.
        

    as(Kind)
        Assume that the printed term is of the given type, and enable
        the corresponding portray-transformations. Kind is one of
        
        term (default): do not assume any particular
            meaning of the printed term.
        clause: print the term as a clause,
            i.e. clause macros will be taken into account.
        goal: print the term as a goal, i.e.
            goal write transformations will be taken into account.
        

    attributes(Style)
        Control how attributes are printed:
        
        none: do not print any variable attributes,
            i.e. print attributed variables like plain variables.
        pretty (default): variable attributes are printed
            using the corresponding print handlers. See meta_attribute/2.
        full: print the full contents of all variable
            attributes.  This is necessary if the term is to be written
            out and read back in.
        

    compact(Bool)
        Deprecated - see spacing(Style)
        

    cycles(Bool)
        Control printing of cyclic subterms.
        
        true: print cyclic terms using cyclic term
            syntax (a variable with quasi-attribute '=').
        false (default): print cyclic terms up
            to the depth limit; if no limit, raise an error.
        

    depth(MaxDepth)
        Deprecated - see max_depth(MaxDepth).
        Control the maximum nesting depth to which terms are printed.
        
        MaxDepth: print the term only up to a maximum
            nesting depth of MaxDepth.  MaxDepth is a positive integer.
        0: print the term only up to a maximum nesting
            depth determined by the global flag 'print_depth'.
            See get_stream_info/3 and get_flag/2.
        full: do not observe any depth limit and print
            the whole term.  If the term may contain cycles, cycles(true)
            should also be selected to prevent an error being raised.
        

    dotlists(Bool)
        If true, write lists in the dot functor notation
        rather than using the square bracket notation, e.g.
        .(1, .(2, [])) rather than [1, 2].
        

    float_precision(Prec)
        Prec is the number of significant digits with which floating-point
        numbers are printed.  The default is 15 for double-precision floats.
        If 0 is specified, the system prints as many
        digits as are needed to read the number back exactly
        (the quoted(true) option also enforces this).
        

    flush(Bool)
	If true, flush the stream after printing the term.
        

    fullstop(Bool)
	If true, terminate the term with a fullstop
        (a dot followed by blank space), so it can be read back.
        The blank space after the dot is a newline if the nl(true)
        option is present, otherwise a space character.
	If necessary, an extra space will be inserted before the fullstop,
	in order to separate it from the end of the term.
        

    ignore_ops(Bool)
	If true, all compound terms are output in functional
        notation.  Neither operator notation, nor list notation, nor
        curly-bracket notation is used when this write-option is in force.
        ISO-Prolog compatibility.  See also portable(Bool).
        

    integer_base(Base)
        Base is an integer between 2 and 36 (default 10), specifying the
        base (radix) for printing integers.  If Base is different from 10,
        all integers are prefixed with BASE', so they can be
        read back correctly.
        

    max_depth(MaxDepth)
        Control the maximum nesting depth to which terms are printed.
        
        MaxDepth: if MaxDepth is a positive integer,
            print the term only up to a maximum nesting depth of MaxDepth.
        0: do not observe any depth limit and print
            the whole term.  If the term may contain cycles, cycles(true)
            should also be selected to prevent an error being raised.
        

    newlines(Bool)
        If true, print newline (NL) characters as newlines
        rather than as an escape sequence, even when they occur in
        quoted atoms or strings.
        This only makes sense together with the quoted(true) option.
        

    nl(Bool)
        If true, print 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.
        

    numbervars(Bool)
        If true, any term of the form '$VAR'(N), where N
        is a non-negative integer, is printed as a variable name
        consisting of a capital letter followed by a number.  The
        capital letter is the ((N mod 26)+1)st letter of the alphabet,
        and the integer is N//26.  If N is an atom representing a valid
        variable name, this atom gets printed instead of the term.
        

    operators(Bool)
        Deprecated - see portable(Bool).  The default is true.
        If false, ignore operator declarations.
        All terms are written in the canonical notation, with a
        functor followed by the arguments in parentheses.
        

    partial(Bool)
        If true, insert a single space ahead of the
        printed term, if this is necessary to ensure token separation
        from previously printed text.  Together with the
        priority(Prio) option, this helps to correctly print
        subterms in the context of larger terms.
        

    portable(Bool)
        If true, ignore operator declarations and output the
        corresponding compound terms in functional notation.  However,
        retain syntactic sugar such as list notation ([...], even for
        improper lists), brace-terms ({...}) and infix commas.
        This option is useful when exchanging text between different
        Prolog contexts, such as modules with different local operator
        declarations, or different Prolog systems.
        

    portrayed(Bool)
        If true, call the user-defined predicate
        portray/1,2 in the way print/1,2 does.
        

    precedence(Prec)
	Prec is an integer between 0 and 1200 (default 1200), representing
	context operator precedence.  Can be used to force correct
	parenthesizing when partial terms are written as arguments of
	operators.  The written term will be enclosed in parentheses if
	its precedence is higher than Prec.
        

    priority(Prec)
        the same as precedence(Prec).
        

    quoted(Bool)
        quote atoms and strings if necessary.  Also print floating point
        numbers with sufficient precision to read back exactly
        (may override the float_precision option).
        

    spacing(Style)
        Control printing of extra white space. Style is one of
        
        compact: don't print blank space unless necessary.
        next_argument: print space after the comma
            separating structure arguments and list elements.
        generous: additionally, print extra blank space
            to separate operators from their arguments.
        

    text_max(Max)
        Limit the length of printed atoms and strings.
        
        Max: if Max is a positive integer, print each
            atom or string only up to a maximum length of Max characters.
        0 (default): do not truncate atoms and strings,
            and print the text in full.
        

    transform(Bool)
        Defaults to true, meaning that portray (write)
        transformations are applied before printing.
        If false, no portray (write) transformations
        are applied.  See also as(Kind).
        

    variable_names(VarsNames)
        use the given variable names when printing the corresponding
	variables.  VarsNames is a list of terms of the form Name=Var
	(where Name is an atom that gives a valid variable name, e.g. 'X').
	If the printed term contains an uninstantiated variable that is
	identical to Var, it is printed as (unquoted) Name. In case of
	ambiguity, the leftmost name is used.
        

    variables(Style)
        Control how variables are printed. Style is one of
        
        default (default): 
            print variables using their source name, if available.
            Otherwise print a system-generated name, which consists of
            an underscore and a number, e.g. _123.
            Note that this format cannot be reliably read back, because
            different variables may have the same source name.  
        raw:
            print all variables using a system-generated name, which
            consists of an underscore and a number, e.g. _123.
            This format is suitable when the term needs to be read back
            later.  It makes sure that multiple occurrences of the same
            variable have the same name, and different variables have
            different names.  
        full:
            print variables using their source name, if available, followed
            by a unique number, e.g. Alpha_132. Variables without source
            name are printed in the raw format. Since variables with
            identical source names are named apart, this format is suitable
            when the term needs to be read back later.  
        anonymous:
            print every variable as a simple underscore. Any information about
            multiple occurrences of a variable is lost with this format. It is
            mainly useful to produce output that can be compared easily with
            the output of a different Eclipse session.  
        


    Boolean options may be abbreviated
    as [option_name] instead of [option_name(true)],
    or [not(option_name)] instead of [option_name(false)].

    In case of conflicting options, the one further down the list
    takes precedence.

    When an option is omitted altogether, then the setting is inherited
    from the stream property 'output_options' (see set_stream_property/3,
    get_stream_info/3, open/4), which may override the above defaults.

    The correspondence between write_term/2,3 and the other output predicates
    is as follows:

    write(S, T) :-
        write_term(S, T, [numbervars]).

    writeln(S, T) :-
        write_term(S, T, [numbervars, nl]).

    writeq(S, T) :-
        write_term(S, T, [quoted, numbervars,
                          max_depth(0), transform(false),
                          variables(raw), attributes(full)]).

    write_canonical(S, T) :-
        write_term(S, T, [ignore_ops, quoted, numbervars,
                          max_depth(0), transform(false),
                          variables(raw), attributes(full)]).

    print(S, T) :-
        write_term(T, [portrayed, numbervars]).

    display(S, T) :-
        write_term(T, [ignore_ops]).


   Note that as usual, the output is buffered, so it may need to be flushed
   either by using the flush-option, calling flush/1, or closing the stream.



Modes and Determinism
   write_term(+, ?, ++) is det

Modules
   This predicate is sensitive to its module context (tool predicate, see @/2).

Exceptions
     4 --- Stream is not instantiated.
     5 --- Stream is not an atom or a stream handle.
     5 --- Options is not a list of compound terms.
     6 --- Options list contains a unrecognised option.
     9 --- Term contains a cycle that can't be printed.
   192 --- Stream is not an output stream.
   193 --- Stream is an illegal stream specification.

Examples
   
        ?- write_term(*(^(1,2),+(3,4)), []).
        1 ^ 2 * (3 + 4)

        ?- write_term(*(^(1,2),+(3,4)), [spacing(compact)]).
        1^2*(3+4)

        ?- write_term(*(^(1,2),+(3,4)), [portable(true)]).
        *(^(1, 2), +(3, 4))

        ?- write_term(['a-b',"cd"], []). 
        [a-b, cd]

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

        ?- write_term(['a-b',"cd"], [quoted(true),ignore_ops(true)]).
        .('a-b', .("cd", []))

        ?- write_term(hello, [fullstop(true)]).
        hello.

        ?- write_term(***, [fullstop(true)]).
        *** .

        ?- write('X = '), write_term(a=b, [precedence(699)]).
        X = (a = b)

        ?- write_term(foo(X,Y,Z), [variables(raw),variable_names(['X'=X,'Z'=Z])]).
        foo(X, _69, Z)

        ?- write_term(foo(X,Y,Z), [anonymous([Y]),variable_names(['X'=X,'Z'=Z])]).
        foo(X, _, Z)

        ?- C=f(C), write_term(g(C), [cycles(true)]).
        g(_122{= : f(_122)})

        ?- C=f(C), write_term(g(C), [max_depth(5)]).
        g(f(f(f(f(...)))))

        ?- X is 1/3, write_term(X, [float_precision(5)]).
        0.33333

        ?- write_term([175, 244], [integer_base(16)]).
        [16'af, 16'f4]


See Also
   write_term / 2, meta_attribute / 2, portray / 3, display / 2, print / 2, printf / 3, write / 2, writeln / 2, writeq / 2, write_canonical / 2, get_stream_info / 3, get_flag / 2
