Term output

Author(s): Richard A. O'Keefe (original version), Mats Carlsson (changes), Daniel Cabeza (changes), Manuel Hermenegildo (changes), Manuel Carro (changes).

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 another in which the stream is specified explicitly, as an additional first argument.

Documentation on exports

PREDICATEwrite_term/3

Usage:ISOwrite_term(Stream,Term,OptList)

Outputs the term Term to the stream Stream, with the list of write-options OptList. See write_option/1 type for default options.

PREDICATEwrite_term/2

Usage:ISOwrite_term(Term,OptList)

Behaves like current_output(S), write_term(S,Term,OptList).

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 writing the final values of variables, and by the debugging package when writing 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)

Opt is a valid write option.

    PREDICATEwrite/2

    Usage:ISOwrite(Stream,Term)

    Behaves like write_term(Stream, Term, [numbervars(true)]).

    PREDICATEwrite/1

    Usage:ISOwrite(Term)

    Behaves like current_output(S), write(S,Term).

    • The following properties should hold at call time:
      (basic_props:term/1)Term is any term.
    • The following properties hold globally:
      (native_props:is_det/1)All calls of the form write(Term) are deterministic.

    PREDICATEwriteq/2

    Usage:ISOwriteq(Stream,Term)

    Behaves like write_term(Stream, Term, [quoted(true), numbervars(true)]).

    PREDICATEwriteq/1

    Usage:ISOwriteq(Term)

    Behaves like current_output(S), writeq(S,Term).

    • The following properties should hold at call time:
      (basic_props:term/1)Term is any term.
    • The following properties hold globally:
      (native_props:is_det/1)All calls of the form writeq(Term) are deterministic.

    PREDICATEwrite_list1/1

    Usage:

    Writes a list to current output one element in each line.

    Usage:ISOwrite_canonical(Stream,Term)

    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.

    Usage:ISOwrite_canonical(Term)

    Behaves like current_output(S), write_canonical(S,Term).

    PREDICATEprint/2

    Usage:print(Stream,Term)

    Behaves like write_term(Stream, Term, [numbervars(true), portrayed(true)]).

    PREDICATEprint/1

    Usage:print(Term)

    Behaves like current_output(S), print(S,Term).

    PREDICATEprintq/2

    Usage:printq(Stream,Term)

    Behaves like write_term(Stream, Term, [quoted(true), numbervars(true), portrayed(true)]).

    PREDICATEprintq/1

    Usage:printq(Term)

    Behaves like current_output(S), printq(S,Term).

    Usage:portray_clause(Stream,Clause)

    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.

    Usage:portray_clause(Clause)

    Behaves like current_output(S), portray_clause(S,Term).

    • The following properties should hold at call time:
      (basic_props:term/1)Clause is any term.

    PREDICATEnumbervars/3

    Usage:numbervars(Term,N,M)

    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.

    PREDICATEprettyvars/1

    Usage:prettyvars(Term)

    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.

    Usage:printable_char(Char)

    Char is the code of a character which can be printed.

    No further documentation available for this predicate.

    Documentation on multifiles

    PREDICATEdefine_flag/3
    Defines flags as follows:
    define_flag(write_strings,[on,off],off).
    
    (See Changing system behaviour and various flags).

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

    Usage:define_flag(Flag,FlagValues,Default)

    The predicate is multifile.

    Usage:portray_attribute(Attr,Var)

    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 predicate is multifile.

    PREDICATEportray/1

    Usage:portray(T)

    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.

    The predicate is multifile.

    Documentation on imports

    This module has the following direct dependencies: