Term output

Author(s): Adapted from shared code written by Richard A. O'Keefe. Changes by Mats Carlsson, Daniel Cabeza, Manuel Hermenegildo, and Manuel Carro..

Version: 1.10#7 (2006/4/26, 19:22:13 CEST)

Version of last change: 1.9#290 (2004/2/13, 20:20:3 CET)

This library provides different predicates for term output, additional to the kernel predicates display/1- display/2 and displayq/1-displayq/2. All the predicates defined in ISO-Prolog are included, plus other traditionally provided by Prolog Implementations. Output predicates are provided in two versions: one that uses the current output stream and other in which the stream is specified explicitly, as an additional first argument.

• Usage and interface (write)
• Documentation on exports (write)
• Documentation on multifiles (write)

Usage and interface (write)

Documentation on exports (write)

PREDICATE: write_term/3:

Usage: write_term(@Stream, ?Term, +OptList) * ISO *

• Description: Outputs the term Term to the stream Stream, with the list of write-options OptList. See write_option/1 type for default options.
• The following properties hold upon exit: @Stream is an open stream. (streams_basic:stream/1) ?Term is any term. (basic_props:term/1) +OptList is a list of write_options. (basic_props:list/2)

PREDICATE: write_term/2:

Usage: write_term(?Term, +OptList) * ISO *

• Description: Behaves like current_output(S), write_term(S,Term,OptList).
• The following properties hold upon exit: ?Term is any term. (basic_props:term/1) +OptList is a list of write_options. (basic_props:list/2)

PROPERTY: write_option/1:

Opt is a valid write option which affects the predicate write_term/3 and similar ones. Possible write_options are:

• quoted(bool): If bool is true, atoms and functors that can't be read back by read_term/3 are quoted, if it is false, each atom and functor is written as its name. Default value is false.
• ignore_ops(flag): If flag is true, each compound term is output in functional notation, if it is ops, curly bracketed notation and list notation is enabled when outputing compound terms, if it is false, also operator notation is enabled when outputing compound terms. Default value is false.
• numbervars(bool): If bool is true, a term of the form '$VAR'(N) where N is an integer, is output as a variable name consisting of a capital letter possibly followed by an integer, a term of the form '$VAR'(Atom) where Atom is an atom, as this atom (without quotes), and a term of the form '$VAR'(String) where String is a character string, as the atom corresponding to this character string. See predicates numbervars/3 and prettyvars/1. If bool is false this cases are not treated in any special way. Default value is false.
• portrayed(bool): If bool is true, then call multifile predicates portray/1 and portray_attribute/2, to provide the user handlers for pretty printing some terms. portray_attribute/2 is called whenever an attributed variable is to be printed, portray/1 is called whenever a non-variable term is to be printed. If either call succeeds, then it is assumed that the term has been output, else it is printed as usual. If bool is false, these predicates are not called. Default value is false. This option is set by the toplevel when writting the final values of variables, and by the debugging package when writting the goals in the tracing messages. Thus you can vary the forms of these messages if you wish.
• max_depth(depth): depth is a positive integer or cero. If it is positive, it denotes the depth limit on printing compound terms. If it is cero, there is no limit. Default value is 0 (no limit).
• priority(prio): prio is an integer between 1 and 1200. If the term to be printed has higher priority than prio, it will be printed parenthesized. Default value is 1200 (no term parenthesized).

.

Usage: write_option(Opt)

• Description: Opt is a valid write option.

PREDICATE: write/2:

Usage: write(@Stream, ?Term) * ISO *

• Description: Behaves like write_term(Stream, Term, [numbervars(true)]).
• The following properties hold upon exit: @Stream is an open stream. (streams_basic:stream/1) ?Term is any term. (basic_props:term/1)

PREDICATE: write/1:

Usage: write(?Term) * ISO *

• Description: Behaves like current_output(S), write(S,Term).
• The following properties hold upon exit: ?Term is any term. (basic_props:term/1)

PREDICATE: writeq/2:

Usage: writeq(@Stream, ?Term) * ISO *

• Description: Behaves like write_term(Stream, Term, [quoted(true), numbervars(true)]).
• The following properties hold upon exit: @Stream is an open stream. (streams_basic:stream/1) ?Term is any term. (basic_props:term/1)

PREDICATE: writeq/1:

Usage: writeq(?Term) * ISO *

• Description: Behaves like current_output(S), writeq(S,Term).
• The following properties hold upon exit: ?Term is any term. (basic_props:term/1)

PREDICATE: write_canonical/2:

Usage: write_canonical(@Stream, ?Term) * ISO *

• Description: Behaves like write_term(Stream, Term, [quoted(true), ignore_ops(true)]). The output of this predicate can always be parsed by read_term/2 even if the term contains special characters or if operator declarations have changed.
• The following properties hold upon exit: @Stream is an open stream. (streams_basic:stream/1) ?Term is any term. (basic_props:term/1)

PREDICATE: write_canonical/1:

Usage: write_canonical(?Term) * ISO *

• Description: Behaves like current_output(S), write_canonical(S,Term).
• The following properties hold upon exit: ?Term is any term. (basic_props:term/1)

PREDICATE: print/2:

Usage: print(@Stream, ?Term)

• Description: Behaves like write_term(Stream, Term, [numbervars(true), portrayed(true)]).
• The following properties hold upon exit: @Stream is an open stream. (streams_basic:stream/1) ?Term is any term. (basic_props:term/1)

PREDICATE: print/1:

Usage: print(?Term)

• Description: Behaves like current_output(S), print(S,Term).
• The following properties hold upon exit: ?Term is any term. (basic_props:term/1)

PREDICATE: write_list1/1:

Usage:

• Description: Writes a list to current output one element in each line.
• Calls should, and exit will be compatible with: Arg1 is a list. (basic_props:list/1)

PREDICATE: portray_clause/2:

Usage: portray_clause(@Stream, ?Clause)

• Description: Outputs the clause Clause onto Stream, pretty printing its variables and using indentation, including a period at the end. This predicate is used by listing/0.
• The following properties hold upon exit: @Stream is an open stream. (streams_basic:stream/1) ?Clause is any term. (basic_props:term/1)

PREDICATE: portray_clause/1:

Usage: portray_clause(?Clause)

• Description: Behaves like current_output(S), portray_clause(S,Term).
• The following properties hold upon exit: ?Clause is any term. (basic_props:term/1)

PREDICATE: numbervars/3:

Usage: numbervars(?Term, +N, ?M)

• Description: Unifies each of the variables in term Term with a term of the form '$VAR'(I) where I is an integer from N onwards. M is unified with the last integer used plus 1. If the resulting term is output with a write option numbervars(true), in the place of the variables in the original term will be printed a variable name consisting of a capital letter possibly followed by an integer. When N is 0 you will get the variable names A, B, ..., Z, A1, B1, etc.
• The following properties hold upon exit: ?Term is any term. (basic_props:term/1) +N is an integer. (basic_props:int/1) ?M is an integer. (basic_props:int/1)

PREDICATE: prettyvars/1:

Usage: prettyvars(?Term)

• Description: Similar to numbervars(Term,0,_), except that singleton variables in Term are unified with '$VAR'('_'), so that when the resulting term is output with a write option numbervars(true), in the place of singleton variables _ is written. This predicate is used by portray_clause/2.
• The following properties hold upon exit: ?Term is any term. (basic_props:term/1)

PREDICATE: printable_char/1:

Usage: printable_char(+Char)

• Description: Char is the code of a character which can be printed.
• The following properties should hold upon exit: +Char is currently instantiated to a number. (term_typing:number/1)

Documentation on multifiles (write)

PREDICATE: define_flag/3:

Defines flags as follows:

define_flag(write_strings,[on,off],off).

(See section Changing system behaviour and various flags).

If flag is on, lists which may be written as strings are.

The predicate is multifile.

PREDICATE: portray_attribute/2:

The predicate is multifile.

Usage: portray_attribute(Attr, Var)

• Description: A user defined predicate. When an attributed variable Var is about to be printed, this predicate receives the variable and its attribute Attr. The predicate should either print something based on Attr or Var, or do nothing and fail. In the latter case, the default printer ( write/1) will print the attributed variable like an unbound variable, e.g. _673.
• The following properties should hold at call time: Attr is currently a term which is not a free variable. (term_typing:nonvar/1) Var is a free variable. (term_typing:var/1)

PREDICATE: portray/1:

The predicate is multifile.

Usage: portray(?Term)

• Description: A user defined predicate. This should either print the Term and succeed, or do nothing and fail. In the latter case, the default printer (write/1) will print the Term.

Go to the first, previous, next, last section, table of contents.