Previous Up Next

8.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 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:

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:

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.

8.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
~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.

8.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:

SpecifierTypeAssociativity
fxprefixno
fyprefixyes
xfpostfixno
yfpostfixyes
xfxinfixno
yfxinfixleft
xfyinfixright

Prolog predefined operators:

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

FD predefined operators:

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

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-2013 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