6.1.5 Term I/O

read(?Term)

ISO
A HiLog term is read from the current or designated input stream, and unified with Term according to the operator declarations in force. (See Section 4.1 for the definition and syntax of HiLog terms). The term must be delimited by a full stop (i.e. a ``.'' followed by a carriage-return, space or tab). Predicate read/1 does not return until a valid HiLog term is successfully read; that is, in the presence of syntax errors read/1 does not fail but continues reading terms until a term with no syntax errors is encountered. If a call to read(Term) causes the end of the current input stream to be reached, variable Term is unified with the term end_of_file. In that case, further calls to read/1 for the same input stream will cause an error failure.

In Version 3.0, read/[1,2] are non ISO-compliant in how they handle syntax errors or their behavior when encountering an end of file indicator.

read(+Stream_or_alias, ?Term)

ISO
read/2 has the same behavior as read/1 but the input stream is explicitly designated by Stream_or_alias.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open stream
  • existence_error(stream,Stream_or_alias)

read_canonical(-Term)

ISO
Reads a term that is in canonical format from the current input stream and returns it in Term. On end-of-file, it returns the atom end_of_file. If it encounters an error, it prints an error message on stderr and returns the atom read_canonical_error. This is significantly faster than read/1, but requires the input to be in canonical form.

In Version 3.0, read_canonical/[1,2] are non ISO-compliant in how they handle syntax errors or their behavior when encountering an end of file indicator.

read_canonical(+Stream_or_alias),-Term)

ISO
Behaves as read_canonical/1, but reads from Stream_or_alias.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open input stream
  • existence_error(stream,Stream_or_alias)

read_term(?Term,?OptionsList)

ISO
A term is read from the current input stream as in read/1; but OptionsList is a (possibly empty) list of read options that specifies additional behavior. The read options include

• variables(Vars): once a term has been read, Vars is a list of the variables in the term, in left-to-right order.
• variable_names(VN_List): once a term has been read VN_List is a list of non-anonymous variables in the term. The elements of the list have the form A = V where V is a non-anonymous variable of the term, and A is the string used to denote the variable in the input stream.
• singletons(VS_List): once a term has been read VN_List is a list of the non-anonymous singleton variables in the term. The elements of the list have the form A = V where V is a non-anonymous variable of the term, and A is the string used to denote the variable in the input stream.

Error Cases

• OptionsList is a variable, or is a list containing a variable element.
  • instantiation_error
• OptionsList contains a non-variable element O that is not a read option.
  • domain_error(read_option,O)

read_term(+Stream_or_alias, ?Term,?OptionsList)

ISO
read_term/3 has the same behavior as read_term/2 but the input stream is explicitly designated using the first argument.

Error Cases are the same as read_term/2, but with the additional errors that may arise in stream checking.

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open stream
  • existence_error(stream,Stream_or_alias)

write(?Term)

ISO
The HiLog term Term is written to the current output stream, according to the operator declarations in force. Any uninstantiated subterm of term Term is written as an anonymous variable (an underscore followed by a token).

All proper HiLog terms (HiLog terms which are not also Prolog terms) are not written in their internal Prolog representation. Predicate write/1 always succeeds without producing an error.

HiLog (or Prolog) terms that are output by write/1 cannot in general be read back using read/1. This happens for two reasons:

• The atoms appearing in term Term are not quoted. In that case the user must use writeq/1 or write_canonical/1 described below, which quote around atoms whenever necessary.
• The output of write/1 is not terminated by a full-stop; therefore, if the user wants the term to be accepted as input to read/1, the terminating full-stop must be explicitly sent to the current output stream.

Predicate write/1 treats terms of the form '$VAR'(N) specially: it writes 'A' if N=0, 'B' if N=1, $\ldots$, 'Z' if N=25, 'A1' if N=26, etc. Terms of this form are generated by numbervars/[1,3] described in the section Library Utilities in Volume 2. '$VAR'(-1) is written as the anonymous variable '_'.

write(+Stream_or_alias, ?Term)

ISO
write/2 has the same behavior as write/1 but the output stream is explicitly designated using the first argument.

Error Cases are the same as read_term/2, but with the additional errors that may arise in stream checking.

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open output stream
  • existence_error(stream,Stream_or_alias)

writeq(?Term)

ISO
Acts as write(Term), but atoms and functors are quoted whenever necessary to make the result acceptable as input to read/1. writeq/1 treats treats terms of the form '\VAR'(N) the same way as write/1, writing A if N= 0, etc. In addition, output is in accordance with current operator definitions. writeq/1 always succeeds without producing an error.

writeq(+Stream_or_alias, ?Term)

ISO
writeq/2 has the same behavior as writeq/1 but the output stream is explicitly designated using the first argument.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open output stream
  • existence_error(stream,Stream_or_alias)

write_canonical(?Term)

ISO
This predicate is provided so that the HiLog term Term, if written to a file, can be read back using read/1 regardless of special characters appearing in Term or prevailing operator declarations. Like write_prolog/1, write_canonical/1 writes all proper HiLog terms to the current output stream using the standard Prolog syntax (see Section 4.1 on the standard syntax of HiLog terms). write_canonical/1 also quotes atoms and functors as writeq/1 does, to make them acceptable as input of read/1. Operator declarations are not taken into consideration, and compound terms are therefore always written in the form:

$$\langle predicate name \rangle (\langle arg_1 \rangle, \ldots, \langle arg_n \rangle)$$

Unlike writeq/1, write_canonical/1 does not treat terms of the form '$VAR'(N) specially. It writes square bracket lists using '.'/2 and [] (that is, [foo, bar] is written as '.'(foo,'.'(bar,[]))).

write_canonical(+Stream_or_alias, ?Term)

ISO
write_canonical/2 has the same behavior as write_canonical/1 but the output stream is explicitly designated using the first argument.

Error Cases

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open output stream
  • existence_error(stream,Stream_or_alias)

write_term(?Term,+Options)

ISO
Outputs +Term to the current output stream. Stream (write_term/3) according to the list of write options, Options. The current set of write options which form a superset of the ISO-standard write options, are as follows:

• quoted(+Bool). If Bool = true, then atoms and functors that can't be read back by read/1 are quoted, if Bool = false, each atom and functor is written as its unquoted name. Default value is false.
• ignore_ops(+Bool). If Bool = true each compound term is output in functional notation; curly brackets and list braces are ignored, as are all explicitly defined operators. If Bool = false, curly bracketed notation and list notation is enabled when outputting compound terms, and all other operator notation is enabled. Default value is false.
• numbervars(+Bool). If Bool = 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, is output as itself (without quotes). Finally, a term of the form '$VAR'(String) where String is a character string, is output as the atom corresponding to this character string. If bool is false this cases are not treated in any special way. Default value is false.
• max_depth(+Depth). Depth is a positive integer or zero. If positive, it denotes the depth limit on printing compound terms. If Depth is zero, 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).

From the following examples it can be seen that write_term/[2,3] can duplicate the behavior of a number of other I/O predicates such as write/[1,2], writeq/[1,2], write_canonical/[1,2], etc.

| ?- write_term(f(1+2,'A',"string",'$VAR'(3),'$VAR'('Temp'),(multifile foo)),[]).
f(1 + 2,A,"string",$VAR(3),$VAR(Temp),(multifile foo))
yes

| ?- write_term(f(1+2,'A',"string",'$VAR'(3),'$VAR'('Temp'),(multifile foo)),
                [quoted(true)]).
f(1 + 2,'A',"string",'$VAR'(3),'$VAR'('Temp'),(multifile foo))
yes

| ?- write_term(f(1+2,'A',"string",'$VAR'(3),'$VAR'('Temp'),(multifile foo)),
                [quoted(true),ignore_ops(true),numbervars(true)]).
f(+(1,2),'A','.'(115,'.'(116,'.'(114,'.'(105,'.'(110,'.'(103,[])))))),D,Temp,(multifile foo))
yes

| ?- write_term(f(1+2,'A',"string",'$VAR'(3),'$VAR'('Temp'),(multifile foo)),
                [quoted(true),ignore_ops(true),numbervars(true),priority(1000)]).
f(+(1,2),'A','.'(115,'.'(116,'.'(114,'.'(105,'.'(110,'.'(103,[])))))),D,Temp,multifile(foo))
yes

Error Cases

• Options is a variable
  • instantiation_error
• Options neither a variable nor a list
  • type_error(list,Options)
• Options contains a variable element, O
  • instantiation_error
• Options contains an element O that is neither a variable nor a write option.
  • domain_error(write_option,O)

write_term(+Stream_or_alias,?Term,+Options)

ISO
Behaves as write_term/2, but writes to Stream_or_alias.

Error Cases are the same as write_term/2 but with these additions.

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open output stream
  • existence_error(stream,Stream_or_alias)

writeln(?Term)

writeln(Term) can be defined as write(Term), nl.

writeln(+Stream,?Term)

writeln(Term) can be defined as write(Stream,Term), nl(Stream).

display(?Term)

The HiLog term Term is displayed on the terminal (standard output stream), according to the operator declarations in force. In other words, display/1 is similar to write/1 but the result is always written on ``userout''. Like write/1, display/1 always succeeds without producing an error. After returning from a call to this predicate, the current output stream remains unchanged.

write_prolog(?Term)

HiLog
This predicate acts as does write/1 except that any HiLog term Term is written as a Prolog term. write_prolog/1 outputs Term according to the operator declarations in force. Because of this, it differs from write_canonical/1 described above, despite the fact that both predicates write HiLog terms as Prolog terms.

write_prolog(+Stream_or_alias,?Term)

HiLog
write_prolog/2 has the same behavior as write_prolog/1 but the output stream is explicitly designated using the first argument.

Error Cases are the same as write_term/2 but with these additions.

• Stream_or_alias is not instantiated to a stream term or alias.
  • domain_error(stream_or_alias,Stream_or_alias)
• Stream_or_alias is not associated with an open output stream
  • existence_error(stream,Stream_or_alias)