Previous
Up
Next
8.14 Term input/output
- read_term/3,
read_term/2,
read/2,
read/1
- read_atom/2,
read_atom/1,
read_integer/2,
read_integer/1,
read_number/2,
read_number/1
- read_token/2,
read_token/1
- syntax_error_info/4
- last_read_start_line_column/2
- 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
- format/3,
format/2
- portray_clause/2,
portray_clause/1
- get_print_stream/1
- op/3
- current_op/3
- char_conversion/2
- current_char_conversion/2
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 8.14.10), and making some
characters equivalent to others (section 8.14.12) if the
char_conversion Prolog flag is on
(section 8.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 8.22.1). Similarly, back quoted tokens are returned depending on the value of the
back_quotes Prolog flag.
8.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:
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
8.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 and
end_of_term are GNU Prolog extensions.
8.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
8.22.1)
syntax_error(atom explaining the error) Portability
GNU Prolog predicates.
8.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 8.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
8.22.1)
syntax_error(atom explaining the error) Portability
GNU Prolog predicates.
8.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 with 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.
8.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 with
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 8.14.1), read_atom/2, read_atom/1,
read_integer/2, read_integer/1, read_number/2,
read_number/1 (section 8.14.2) or read_token/2,
read_token/1 (section 8.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.
8.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 false.
- namevars(true/false): if true a
term of the form ’$VARNAME’(Name), where Name is an atom
respecting the syntax of variable names, 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 false.
- variable_names(VNL): VNL is
a list of pairs Name = Var where Var is a
variable and Name is the atom associated with the
name of Var. Each variable Var is written as the atom
Name (with quoted(false)) iff a term
Name = Var is an element of the list VNL.
If several pairs exist for the same variable name the first one applies.
- 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 than N gives rise to the output of
... (3 dots). By default there is no depth limit.
- priority(N): specifies the starting priority
to output the term. This option controls if Term should be enclosed
in brackets. N is a positive integer ≤ 1200. By default
N = 1200.
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, [numbervars(true),
namevars(true)]).
writeq(SorA, Term) is equivalent to
write_term(SorA, Term, [quoted(true),
numbervars(true), namevars(true)]).
write_canonical(SorA, Term) is equivalent to
write_term(SorA, Term, [quoted(true),
ignore_ops(true), numbervars(false), namevars(false)]).
display(SorA, Term) is equivalent to
write_term(SorA, Term, [ignore_ops(true),
numbervars(false), namevars(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, variable_names space_args,
portrayed, max_depth and priority
options are GNU Prolog extensions.
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
~Na
atom
print the atom without quoting.
N is minimal number of characters to print using spaces on the right if needed (default: the length of the atom)
~Nc
character code
print the character associated with 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
8.14.6)
~p
term
pass the argument to
print/1
(section
8.14.6)
~q
term
pass the argument to
writeq/1
(section
8.14.6)
~w
term
pass the argument to
write/1
(section
8.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
8.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.
8.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 8.5.1) and
numbervars/1 (section 8.5.3). This predicate is
used by listing/1 (section 8.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.
8.14.9 get_print_stream/1
Templates
-
get_print_stream(?stream)
Description
get_print_stream(Stream) unifies Stream with the
stream-term associated with the output stream used by print/2
(section 8.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 neither a variable nor a stream-term domain_error(stream, Stream)
Portability
GNU Prolog predicate.
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
700 xfx = \= =.. == \== @<
@=< @> @>= is =:= =\= < =< > >=
400 yfx * / // rem mod div <<
>>
FD predefined operators:
Priority Specifier
Operators
700 xfx #= #\= #< #=<
#> #>= #=# #\=# #<# #=<# #>#
#>=#
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 (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)
Operator (or an element of the Operator list) is
| and it would have a prefix or a postfix definition or its
Priority would be ≤ 1100. permission_error(create, operator, ’|’)
Operator (or an element of the Operator list) is
[] or {}. 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.
8.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.
8.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 8.14.1), read_atom/2,
read_integer/2, read_number/2 (section 8.14.2) and
read_token/2 (section 8.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 8.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 8.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.
8.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 8.14.12).
Copyright (C) 1999-2021 Daniel Diaz
Verbatim copying and distribution of this entire article is permitted in any
medium, provided this notice is preserved.
More about the copyright
Previous
Up
Next