Term input/output

6.14

Term input/output

These built-in predicates enable a Prolog term to be input from or output to a text stream. The atom end_of_file is returned as term to indicate the end-of-file. The syntax of such terms can also be altered by changing the operators (section 6.14.10), and making some characters equivalent to others (section 6.14.12) if the char_conversion Prolog flag is on (section 6.22.1). Double quoted tokens will be returned as an atom or a character list or a character code list depending on the value of the double_quotes Prolog flag (section 6.22.1).

6.14.1 read_term/3, read_term/2, read/2, read/1

Templates

: read_term(+stream_or_alias, ?term, +read_option_list) read_term(?term, +read_option_list) read(+stream_or_alias, ?term) read(?term)

Description

read_term(SorA, Term, Options) is true if Term unifies with the next term read from the stream associated with the stream-term or alias SorA according to the options given by Options.

Read options: Options is a list of read options. If this list contains contradictory options, the rightmost option is the one which applies. Possible options are:

variables(VL): VL is unified with the list of all variables of the input term, in left-to-right traversal order. Anonymous variables are included in the list VL.
variable_names(VNL): VNL is unified with the list of pairs Name = Var where Var is a named variable of the term and Name is the atom associated to the name of Var. Anonymous variables are not included in the list VNL.
singletons(SL): SL is unified with the list of pairs Name = Var where Var is a named variable which occurs only once in the term and Name is the atom associated to the name of Var. Anonymous variables are not included in the list SL.
syntax_error(error/warning/fail): specifies the effect of a syntax error:
- error: a syntax_error is raised.
- warning: a warning message is displayed and the predicate fails.
- fail: the predicate quietly fails.
The default value is the value of the syntax_error Prolog flag (section 6.22.1).
end_of_term(dot/eof): specifies the end-of-term delimiter: dot is the classical full-stop delimiter (a dot followed with a layout character), eof is the end-of-file delimiter. This option is useful for predicates like read_from_atom/2 (section 6.15.1) to avoid to add a terminal dot at the end of the atom. The default value is dot.

read(SorA, Term) is equivalent to read_term(SorA, Term, []).

read_term/2 and read/1 apply to the current input stream.

Errors

SorA is a variable instantiation_error

Options is a partial list or a list with an element E which is a variable instantiation_error

SorA is neither a variable nor a stream-term or alias domain_error(stream_or_alias, SorA)

Options is neither a partial list nor a list type_error(list, Options)

an element E of the Options list is neither a variable nor a valid read option domain_error(read_option, E)

SorA is not associated with an open stream existence_error(stream, SorA)

SorA is an output stream permission_error(input, stream, SorA)

SorA is associated with a binary stream permission_error(input, binary_stream, SorA)

SorA has stream properties end_of_stream(past) and eof_action(error) permission_error(input, past_end_of_stream, SorA)

a syntax error occurs and the value of the syntax_error Prolog flag is error (section 6.22.1) syntax_error(atom explaining the error)

Portability

ISO predicates. The ISO reference raises a representation_error(Flag) where Flag is max_arity, max_integer, or min_integer when the read term breaches an implementation defined limit specified by Flag. GNU Prolog detects neither min_integer nor max_integer violation and treats a max_arity violation as a syntax error. The read options syntax_error/1 and end_of_term/1 are GNU Prolog extensions.

6.14.2 read_atom/2, read_atom/1, read_integer/2, read_integer/1,
read_number/2, read_number/1

Templates

: read_atom(+stream_or_alias, ?atom) read_atom(?atom) read_integer(+stream_or_alias, ?integer) read_integer(?integer) read_number(+stream_or_alias, ?number) read_number(?number)

Description

read_atom(SorA, Atom) succeeds if Atom unifies with the next atom read from the stream associated with the stream-term or alias SorA.

read_integer(SorA, Integer) succeeds if Integer unifies with the next integer read from the stream associated with the stream-term or alias SorA.

read_number(SorA, Number) succeeds if Number unifies with the next number (integer or floating point number) read from the stream associated with the stream-term or alias SorA.

read_atom/1, read_integer/1 and read_number/1 apply to the current input stream.

Errors

SorA is a variable instantiation_error

Atom is neither a variable nor an atom type_error(atom, Atom)

Integer is neither a variable nor an integer type_error(integer, Integer)

Number is neither a variable nor a number type_error(number, Number)

SorA is neither a variable nor a stream-term or alias domain_error(stream_or_alias, SorA)

SorA is not associated with an open stream existence_error(stream, SorA)

SorA is an output stream permission_error(input, stream, SorA)

SorA is associated with a binary stream permission_error(input, binary_stream, SorA)

SorA has stream properties end_of_stream(past) and eof_action(error) permission_error(input, past_end_of_stream, SorA)

a syntax error occurs and the value of the syntax_error Prolog flag is error (section 6.22.1) syntax_error(atom explaining the error)

Portability

GNU Prolog predicates.

6.14.3 read_token/2, read_token/1

Templates

: read_token(+stream_or_alias, ?nonvar) read_token(?nonvar)

Description

read_token(SorA, Token) succeeds if Token unifies with the encoding of the next Prolog token read from the stream associated with stream-term or alias SorA.

Token encoding:

var(A): a variable is read whose name is the atom A.
an atom A: an atom A is read.
integer N: an integer N is read.
floating point number N: a floating point number N is read.
string(A): a string (double quoted item) is read whose characters forms the atom A.
punct(P): a punctuation character P is read (P is a one-character atom in ()[]{|}, the atom full_stop or the atom end_of_file).
back_quotes(A): a back quoted item is read whose characters forms the atom A.
extended(A): an extended character A (an atom) is read.

As for read_term/3, the behavior of read_token/2 can be affected by some Prolog flags (section 6.14).

read_token/1 applies to the current input stream.

Errors

SorA is a variable instantiation_error

SorA is neither a variable nor a stream-term or alias domain_error(stream_or_alias, SorA)

SorA is not associated with an open stream existence_error(stream, SorA)

SorA is an output stream permission_error(input, stream, SorA)

SorA is associated with a binary stream permission_error(input, binary_stream, SorA)

SorA has stream properties end_of_stream(past) and eof_action(error) permission_error(input, past_end_of_stream, SorA)

a syntax error occurs and the value of the syntax_error Prolog flag is error (section 6.22.1) syntax_error(atom explaining the error)

Portability

GNU Prolog predicates.

6.14.4 syntax_error_info/4

Templates

: syntax_error_info(?atom, ?integer, ?integer, ?atom)

Description

syntax_error_info(FileName, Line, Column, Error) returns the information associated to the last syntax error. Line is the line number of the error, Column is the column number of the error and Error is an atom explaining the error.

Errors

FileName is neither a variable nor an atom type_error(atom, FileName)

Line is neither a variable nor an integer type_error(integer, Line)

Column is neither a variable nor an integer type_error(integer, Column)

Error is neither a variable nor an atom type_error(atom, Error)

Portability

GNU Prolog predicate.

6.14.5 last_read_start_line_column/2

Templates

: last_read_start_line_column(?integer, ?integer)

Description

last_read_start_line_column(Line, Column) unifies Line and Column with the line number and the column number associated to the start of the last read predicate. This predicate can be used after calling one of the following predicates: read_term/3, read_term/2, read/2, read/1 (section 6.14.1), read_atom/2, read_atom/1, read_integer/2, read_integer/1, read_number/2, read_number/1 (section 6.14.2) or read_token/2, read_token/1 (section 6.14.3).

Errors

Line is neither a variable nor an integer type_error(integer, Line)

Column is neither a variable nor an integer type_error(integer, Column)

Portability

GNU Prolog predicate.

6.14.6 write_term/3, write_term/2, write/2, write/1, writeq/2, writeq/1,
write_canonical/2, write_canonical/1, display/2, display/1, print/2,
print/1

Templates

: write_term(+stream_or_alias, ?term, +write_option_list) write_term(?term, +write_option_list) write(+stream_or_alias, ?term) write(?term) writeq(+stream_or_alias, ?term) writeq(?term) write_canonical(+stream_or_alias, ?term) write_canonical(?term) display(+stream_or_alias, ?term) display(?term) print(+stream_or_alias, ?term) print(?term)

Description

write_term(SorA, Term, Options) writes Term to the stream associated with the stream-term or alias SorA according to the options given by Options.

Write options: Options is a list of write options. If this list contains contradictory options, the rightmost option is the one which applies. Possible options are:

quoted(true/false): if true each atom and functor is quoted if this would be necessary for the term to be input by read_term/3. If false no extra quotes are written. The default value is false.
ignore_ops(true/false): if true each compound term is output in functional notation (neither operator notation nor list notation is used). If false operator and list notations are used. The default value is false.
numbervars(true/false): if true a term of the form '$VAR'(N), where N is an integer, is output as a variable name (see below). If false such a term is output normally (according to the other options). The default value is true.
namevars(true/false): if true a term of the form '$VARNAME'(Name), where Name is an atom, is output as a variable name (see below). If false such a term is output normally (according to the other options). The default value is true.
space_args(true/false): if true an extra space character is emitted after each comma separating the arguments of a compound term in functional notation or of a list. If false no extra space is emitted. The default value is false.
portrayed(true/false): if true and if there exists a predicate portray/1, write_term/3 acts as follows: if Term is a variable it is simply written. If Term is non-variable then it is passed to portray/1. If this succeeds then it is assumed that Term has been output. Otherwise write_term/3 outputs the principal functor of Term (Term itself if it is atomic) according to other options and recursively calls portray/1 on the components of Term (if it is a compound term). With ignore_ops(false) a list is first passed to portray/1 and only if this call fails each element of the list is passed to portray/1 (thus every sub-list is not passed). The default value is false.
max_depth(N): controls the depth of output for compound terms. N is an integer specifying the depth. The output of a term whose depth is greater then N gives rise to the output of ... (3 dots). By default there is no depth limit.

Variable numbering: when the numbervars(true) option is passed to write_term/3 any 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. The capital letter is the (I+1)th letter of the alphabet and the integer is J, where I = N mod 26 and J = N // 26. The integer J is omitted if it is zero. For example:

`'$VAR'(0)`		is written as `A`
`'$VAR'(1)`		is written as `B`
`...`
`'$VAR'(25)`		is written as `Z`
`'$VAR'(26)`		is written as `A1`
`'$VAR'(27)`		is written as `B1`

Variable naming: when the namevars(true) option is passed to write_term/3 any term of the form '$VARNAME'(Name) where Name is an atom is output as a variable name consisting of the characters Name. For example: '$VARNAME'('A') is written as A (even in the presence of the quoted(true) option).

write(SorA, Term) is equivalent to write_term(SorA, Term, []).

writeq(SorA, Term) is equivalent to write_term(SorA, Term, [quoted(true)]).

write_canonical(SorA, Term) is equivalent to write_term(SorA, Term, [quoted(true), ignore_ops(true), numbervars(false)]).

display(SorA, Term) is equivalent to write_term(SorA, Term, [ignore_ops(true), numbervars(false)]).

print(SorA, Term) is equivalent to write_term(SorA, Term, [numbervars(false), portrayed(true)]).

write_term/2, write/1, writeq/1, write_canonical/1, display/1 and print/1 apply to the current output stream.

Errors

SorA is a variable instantiation_error

Options is a partial list or a list with an element E which is a variable instantiation_error

Options is neither a partial list nor a list type_error(list, Options)

SorA is neither a variable nor a stream-term or alias domain_error(stream_or_alias, SorA)

an element E of the Options list is neither a variable nor a valid write-option domain_error(write_option, E)

SorA is not associated with an open stream existence_error(stream, SorA)

SorA is an input stream permission_error(output, stream, SorA)

SorA is associated with a binary stream permission_error(output, binary_stream, SorA)

Portability

ISO predicates except display/1-2 and print/1-2 that are GNU Prolog predicates. namevars/1, space_args/1, portrayed/1 and max_depth/1 options are GNU Prolog extensions.

6.14.7 format/3, format/2

Templates

: format(+stream_or_alias, +character_code_list_or_atom, +list) format(+character_code_list_or_atom, +list)

Description

format(SorA, Format, Arguments) writes the Format string replacing each format control sequence F by the corresponding element of Arguments (formatted according to F) to the stream associated with the stream-term or alias SorA.

Format control sequences: the general format of a control sequence is '~NC'. The character C determines the type of the control sequence. N is an optional numeric argument. An alternative form of N is '*'. '*' implies that the next argument Arg in Arguments should be used as a numeric argument in the control sequence. The use of C printf() formatting sequence (beginning by the character %) is also allowed. The following control sequences are available:

Format sequence	type of the argument	Description
`~a`	atom	print the atom without quoting
`~Nc`	character code	print the character associated to the code. `N` is the number of times to print the character (default: 1)
`~Nf` `~Ne ~NE ~Ng ~NG`	float expression	pass the argument `Arg` and `N` to the C `printf()` function as: if `N` is not specified `printf("%f",Arg)` else `printf("%.Nf",Arg)`. Similarly for `~Ne`, `~NE`, `~Ng` and `~NG`
`~Nd`	integer expression	print the argument. `N` is the number of digits after the decimal point. If `N` is 0 no decimal point is printed (default: 0)
`~ND`	integer expression	identical to `~Nd` except that `','` separates groups of three digits to the left of the decimal point
`~Nr`	integer expression	print the argument according to the radix `N`. 2 £ `N` £ 36 (default: 8). The letters `a-z` denote digits > 9
`~NR`	integer expression	identical to `~Nr` except that the letters `A-Z` denote digits > 9
`~Ns`	character code list	print exactly `N` characters (default: the length of the list)
`~NS`	character list	print exactly `N` characters (default: the length of the list)
`~i`	term	ignore the current argument
`~k`	term	pass the argument to `write_canonical/1` (section 6.14.6)
`~p`	term	pass the argument to `print/1` (section 6.14.6)
`~q`	term	pass the argument to `writeq/1` (section 6.14.6)
`~w`	term	pass the argument to `write/1` (section 6.14.6)
`~~`	none	print the character `'~'`
`~Nn`	none	print `N` new-line characters (default: 1)
`~N`	none	print a new-line character if not at the beginning of a line
`~?`	atom	use the argument as a nested format string
`%F`	atom, integer or float expression	interface to the C function `printf(3)` for outputting atoms (C string), integers and floating point numbers. `*` are also allowed.

format/2 applies to the current output stream.

Errors

SorA is a variable instantiation_error

Format is a partial list or a list with an element E which is a variable instantiation_error

Arguments is a partial list instantiation_error

Format is neither a partial list nor a list or an atom type_error(list, Format)

Arguments is neither a partial list nor a list type_error(list, Arguments)

an element E of the Format list is neither a variable nor a character code representation_error(character_code, E)

SorA is neither a variable nor a stream-term or alias domain_error(stream_or_alias, SorA)

an element E of Format is not a valid format control sequence domain_error(format_control_sequence, E)

the Arguments list does not contain sufficient elements domain_error(non_empty_list, [])

an element E of the Arguments list is a variable while a non-variable term was expected instantiation_error

an element E of the Arguments list is neither variable nor an atom while an atom was expected type_error(atom, E)

an element E of the Arguments cannot be evaluated as an arithmetic expression while an integer or a floating point number was expected an arithmetic error (section 6.6.1)

an element E of the Arguments list is neither variable nor character code while a character code was expected representation_error(character_code, E)

SorA is not associated with an open stream existence_error(stream, SorA)

SorA is an input stream permission_error(output, stream, SorA)

SorA is associated with a binary stream permission_error(output, binary_stream, SorA)

Portability

GNU Prolog predicates.

6.14.8 portray_clause/2, portray_clause/1

Templates

: portray_clause(+stream_or_alias, +clause) portray_clause(+clause)

Description

portray_clause(SorA, Clause) pretty prints Clause to the stream associated with the stream-term or alias SorA. portray_clause/2 uses the variable binding predicates name_singleton_vars/1 (section 6.5.1) and numbervars/1 (section 6.5.3). This predicate is used by listing/1 (section 6.23.3).

portray_clause/1 applies to the current output stream.

Errors

Clause is a variable instantiation_error

Clause is neither a variable nor a callable term type_error(callable, Clause)

SorA is a variable instantiation_error

SorA is neither a variable nor a stream-term or alias domain_error(stream_or_alias, SorA)

SorA is not associated with an open stream existence_error(stream, SorA)

SorA is an input stream permission_error(output, stream, SorA)

SorA is associated with a binary stream permission_error(output, binary_stream, SorA)

Portability

GNU Prolog predicates.

6.14.9 get_print_stream/1

Templates

: get_print_stream(-stream)

Description

get_print_stream(Stream) unifies Stream with the stream-term associated to the output stream used by print/2 (section 6.14.6). The purpose of this predicate is to allow a user-defined portray/1 predicate to identify the output stream in use.

Errors

Stream is not a variable type_error(variable, Stream)

Portability

GNU Prolog predicate.

6.14.10 op/3

Templates

: op(+integer, +operator_specifier, +atom_or_atom_list)

Description

op(Priority, OpSpecifier, Operator) alters the operator table. Operator is declared as an operator with properties defined by specifier OpSpecifier and Priority. Priority must be an integer ³ 0 and £ 1200. If Priority is 0 then the operator properties of Operator (if any) are canceled. Operator may also be a list of atoms in which case all of them are declared to be operators. In general, operators can be removed from the operator table and their priority or specifier can be changed. However, it is an error to attempt to change the ',' operator from its initial status. An atom can have multiple operator definitions (e.g. prefix and infix like +) however an atom cannot have both an infix and a postfix operator definitions.

Operator specifiers: the following specifiers are available:

Specifier	Type	Associativity
`fx`	prefix	no
`fy`	prefix	yes
`xf`	postfix	no
`yf`	postfix	yes
`xfx`	infix	no
`yfx`	infix	left
`xfy`	infix	right

Prolog predefined operators:

Priority	Specifier	Operators
`1200`	`xfx`	`:- -->`
`1200`	`fx`	`:-`
`1100`	`xfy`	`;`
`1050`	`xfy`	`->`
`1000`	`xfy`	`,`
`900`	`fy`	`\+`
`700`	`xfx`	`=` `\= =.. ==` `\== @<` `@=<` `@>` `@>= is =:= =\=` `<` `=<` `>` `>=`
`500`	`yfx`	`+ - /\` `\/`
`400`	`yfx`	`* / // rem mod` `<<` `>>`
`200`	`xfy`	`** ^`
`200`	`fy`	`+ -` `\`

FD predefined operators:

Priority	Specifier	Operators
`750`	`xfy`	`#<=>` `#\<=>`
`740`	`xfy`	`#==>` `#\==>`
`730`	`xfy`	`## #\/ #\\/`
`720`	`yfx`	`#/\` `#\/\`
`710`	`fy`	`#\`
`700`	`xfx`	`#= #\= #<` `#=<` `#>` `#>= #=# #\=# #<# #=<# #># #>=#`
`500`	`yfx`	`+ -`
`400`	`yfx`	`* / // rem`
`200`	`xfy`	`**`
`200`	`fy`	`+ -`

Errors

Priority is a variable instantiation_error

OpSpecifier is a variable instantiation_error

Operator is a partial list or a list with an element E which is a variable instantiation_error

Priority is neither a variable nor an integer type_error(integer, Priority)

OpSpecifier is neither a variable nor an atom type_error(atom, OpSpecifier)

Operator is neither a partial list nor a list nor an atom type_error(list, Operator)

an element E of the Operator list is neither a variable nor an atom type_error(atom, E)

Priority is an integer not ³ 0 and £ 1200 domain_error(operator_priority, Priority)

OpSpecifier is not a valid operator specifier domain_error(operator_specifier, OpSpecifier)

Operator is ',' or an element of the Operator list is ',' permission_error(modify, operator, ',')

OpSpecifier is a specifier such that Operator would have a postfix and an infix definition. permission_error(create, operator, Operator)

Portability

ISO predicate.

The ISO reference implies that if a program calls current_op/3, then modifies an operator definition by calling op/3 and backtracks into the call to current_op/3, then the changes are guaranteed not to affect that current_op/3 goal. This is not guaranteed by GNU Prolog.

6.14.11 current_op/3

Templates

: current_op(?integer, ?operator_specifier, ?atom)

Description

current_op(Priority, OpSpecifier, Operator) succeeds if Operator is an operator with properties defined by specifier OpSpecifier and Priority. This predicate is re-executable on backtracking.

Errors

Priority is neither a variable nor an operator priority domain_error(operator_priority, Priority)

OpSpecifier is neither a variable nor an operator specifier domain_error(operator_specifier, OpSpecifier)

Operator is neither a variable nor an atom type_error(atom, Operator)

Portability

ISO predicate.

6.14.12 char_conversion/2

Templates

: char_conversion(+character, +character)

Description

char_conversion(InChar, OutChar) alters the character-conversion mapping. This mapping is used by the following read predicates: read_term/3 (section 6.14.1), read_atom/2, read_integer/2, read_number/2 (section 6.14.2) and read_token/2 (section 6.14.3) to replace any occurrence of a character InChar by OutChar. However the conversion mechanism should have been previously activated by switching on the char_conversion Prolog flag (section 6.22.1). When InChar and OutChar are the same, the effect is to remove any conversion of a character InChar.

Note that the single character read predicates (e.g. get_char/2) never do character conversion. If such behavior is required, it must be explicitly done using current_char_conversion/2 (section 6.14.13).

Errors

InChar is a variable instantiation_error

OutChar is a variable instantiation_error

InChar is neither a variable nor a character type_error(character, InChar)

OutChar is neither a variable nor a character type_error(character, OutChar)

Portability

ISO predicate. The type_error(character,...) is a GNU Prolog behavior, the ISO reference instead defines a representation_error(character) in this case. This seems to be an error of the ISO reference since, for many other built-in predicates accepting a character (e.g. char_code/2, put_char/2), a type_error is raised.

The ISO reference implies that if a program calls current_char_conversion/2, then modifies the character mapping by calling char_conversion/2, and backtracks into the call to current_char_conversion/2 then the changes are guaranteed not to affect that current_char_conversion/2 goal. This is not guaranteed by GNU Prolog.

6.14.13 current_char_conversion/2

Templates

: current_char_conversion(?character, ?character)

Description

current_char_conversion(InChar, OutChar) succeeds if the conversion of InChar is OutChar according to the character-conversion mapping. In that case, InChar and OutChar are different. This predicate is re-executable on backtracking.

Errors

InChar is neither a variable nor a character type_error(character, InChar)

OutChar is neither a variable nor a character type_error(character, OutChar)

Portability

ISO predicate. Same remark as for char_conversion/2 (section 6.14.12).

Copyright (C) 1999,2000 Daniel Diaz

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

More about the copyright