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

Documentation on exports

PREDICATE

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.

  • The following properties should hold at call time:
    (term_typing:nonvar/1)OptList is currently a term which is not a free variable.
    (streams_basic:stream/1)Stream is an open stream.
    (basic_props:term/1)Term is any term.
    (basic_props:list/2)OptList is a list of write_options.
  • The following properties should hold globally:
    (basic_props:not_further_inst/2)Stream is not further instantiated.

PREDICATE

Usage:ISOwrite_term(Term,OptList)

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

  • The following properties should hold at call time:
    (term_typing:nonvar/1)OptList is currently a term which is not a free variable.
    (basic_props:term/1)Term is any term.
    (basic_props:list/2)OptList is a list of write_options.

PROPERTY
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)

Opt is a valid write option.

    PREDICATE

    (Trust) Usage:ISOwrite(Stream,Term)

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

    • The following properties should hold at call time:
      (streams_basic:stream/1)Stream is an open stream.
      (basic_props:term/1)Term is any term.
    • The following properties hold globally:
      (basic_props:not_further_inst/2)Stream is not further instantiated.
      (native_props:is_det/1)All calls of the form write(Stream,Term) are deterministic.

    PREDICATE

    (Trust) 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.

    PREDICATE

    (Trust) Usage:ISOwriteq(Stream,Term)

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

    • The following properties should hold at call time:
      (streams_basic:stream/1)Stream is an open stream.
      (basic_props:term/1)Term is any term.
    • The following properties hold globally:
      (basic_props:not_further_inst/2)Stream is not further instantiated.
      (native_props:is_det/1)All calls of the form writeq(Stream,Term) are deterministic.

    PREDICATE

    (Trust) 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.

    PREDICATE

    Usage:

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

    • The following properties should hold at call time:
      (basic_props:list/1)Arg1 is a list.

    PREDICATE

    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.

    • The following properties should hold at call time:
      (streams_basic:stream/1)Stream is an open stream.
      (basic_props:term/1)Term is any term.
    • The following properties should hold globally:
      (basic_props:not_further_inst/2)Stream is not further instantiated.

    PREDICATE

    Usage:ISOwrite_canonical(Term)

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

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

    PREDICATE

    Usage:print(Stream,Term)

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

    • The following properties should hold at call time:
      (streams_basic:stream/1)Stream is an open stream.
      (basic_props:term/1)Term is any term.
    • The following properties should hold globally:
      (basic_props:not_further_inst/2)Stream is not further instantiated.

    PREDICATE

    Usage:print(Term)

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

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

    PREDICATE

    Usage:printq(Stream,Term)

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

    • The following properties should hold at call time:
      (streams_basic:stream/1)Stream is an open stream.
      (basic_props:term/1)Term is any term.
    • The following properties should hold globally:
      (basic_props:not_further_inst/2)Stream is not further instantiated.

    PREDICATE

    Usage:printq(Term)

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

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

    PREDICATE

    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.

    • The following properties should hold at call time:
      (streams_basic:stream/1)Stream is an open stream.
      (basic_props:term/1)Clause is any term.
    • The following properties should hold globally:
      (basic_props:not_further_inst/2)Stream is not further instantiated.

    PREDICATE

    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.

    PREDICATE

    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.

    • The following properties should hold at call time:
      (term_typing:nonvar/1)N is currently a term which is not a free variable.
      (basic_props:term/1)Term is any term.
      (basic_props:int/1)N is an integer.
      (basic_props:term/1)M is any term.
    • The following properties should hold upon exit:
      (basic_props:term/1)Term is any term.
      (basic_props:int/1)N is an integer.
      (basic_props:int/1)M is an integer.

    PREDICATE

    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.

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

    PREDICATE

    Usage:printable_char(Char)

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

    • The following properties should hold at call time:
      (term_typing:nonvar/1)Char is currently a term which is not a free variable.
      (basic_props:character_code/1)Char is an integer which is a character code.

    PREDICATE
    No further documentation available for this predicate.

    Documentation on multifiles

    PREDICATE
    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.

    (Trust) Usage:define_flag(Flag,FlagValues,Default)

    • The following properties hold upon exit:
      (basic_props:atm/1)Flag is an atom.
      (basic_props:flag_values/1)Define the valid flag values
    The predicate is multifile.

    PREDICATE

    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 following properties should hold at call time:
      (term_typing:nonvar/1)Attr is currently a term which is not a free variable.
      (term_typing:var/1)Var is a free variable.
    The predicate is multifile.

    PREDICATE

    (Trust) 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 following properties should hold at call time:
      (basic_props:term/1)T is any term.
    • The following properties hold upon exit:
      (basic_props:term/1)T is any term.
    The predicate is multifile.

    Known bugs and planned improvements

    • Run-time checks have been reported not to work with this code. That means that either the assertions here, or the code that implements the run-time checks are erroneous.