Previous Up Next
7.12 Character input/output
These built-in predicates enable a single character or character code to be input from and output to a text stream. The atom end_of_file is returned as character to indicate the end-of-file. -1 is returned as character code to indicate the end-of-file.

7.12.1 get_char/2, get_char/1, get_code/1, get_code/2

Templates
get_char(+stream_or_alias, ?in_character)
get_char(?in_character)
get_code(+stream_or_alias, ?in_character_code)
get_code(?in_character_code)
Description

get_char(SorA, Char) succeeds if Char unifies with the next character read from the stream associated with the stream-term or alias SorA.

get_code/2 is similar to get_char/2 but deals with character codes.

get_char/1 and get_code/1 apply to the current input stream.

Errors
SorA is a variable    instantiation_error
Char is neither a variable nor an in-character    type_error(in_character, Char)
Code is neither a variable nor an integer    type_error(integer, Code)
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)
The entity input from the stream is not a character    representation_error(character)
Code is an integer but not an in-character code    representation_error(in_character_code)

Portability

ISO predicates.

7.12.2 get_key/2, get_key/1 get_key_no_echo/2, get_key_no_echo/1

Templates
get_key(+stream_or_alias, ?integer)
get_key(?integer)
get_key_no_echo(+stream_or_alias, ?integer)
get_key_no_echo(?integer)
Description

get_key(Code, SorA) succeeds if Code unifies with the character code of the next key read from the stream associated with the stream-term or alias SorA. It is intended to read a single key from the keyboard (thus SorA should refer to current input stream). No buffering is performed (a character is read as soon as available) and function keys can also be read (in that case, Code is an integer > 255). The read character is echoed if it is printable.

This facility is only possible if the linedit facility has been installed (section 3.2.5) otherwise get_key/2 behaves similarly to get_code/2 (section 7.12.1) (the code of the first character is returned) but also pumps remaining characters until a character < space (0x20) is read (in particular RETURN). The same behavior occurs if SorA does not refer to the current input stream or if this stream is not attached to a terminal.

get_key_no_echo/2 behaves similarly to get_key/2 except that the read character is not echoed.

get_key/1 and get_key_no_echo/1 apply to the current input stream.

Errors
SorA is a variable    instantiation_error
Code is neither a variable nor an integer    type_error(integer, Code)
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)

Portability

GNU Prolog predicates.

7.12.3 peek_char/2, peek_char/1, peek_code/1, peek_code/2

Templates
peek_char(+stream_or_alias, ?in_character)
peek_char(?in_character)
peek_code(+stream_or_alias, ?in_character_code)
peek_code(?in_character_code)
Description

peek_char(SorA, Char) succeeds if Char unifies with the next character that will be read from the stream associated with the stream-term or alias SorA. The character is not read.

peek_code/2 is similar to peek_char/2 but deals with character codes.

peek_char/1 and peek_code/1 apply to the current input stream.

Errors
SorA is a variable    instantiation_error
Char is neither a variable nor an in-character    type_error(in_character, Char)
Code is neither a variable nor an integer    type_error(integer, Code)
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)
The entity input from the stream is not a character    representation_error(character)
Code is an integer but not an in-character code    representation_error(in_character_code)

Portability

ISO predicates.

7.12.4 unget_char/2, unget_char/1, unget_code/2, unget_code/1

Templates
unget_char(+stream_or_alias, +character)
unget_char(+character)
unget_code(+stream_or_alias, +character_code)
unget_code(+character_code)
Description

unget_char(SorA, Char) pushes back Char onto the stream associated with the stream-term or alias SorA. Char will be the next character read by get_char/2. The maximum number of characters that can be cumulatively pushed back is given by the max_unget Prolog flag (section 7.22.1).

unget_code/2 is similar to unget_char/2 but deals with character codes.

unget_char/1 and unget_code/1 apply to the current input stream.

Errors
SorA is a variable    instantiation_error
Char is a variable    instantiation_error
Code is a variable    instantiation_error
Char is neither a variable nor a character    type_error(character, Char)
Code is neither a variable nor an integer    type_error(integer, Code)
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)
Code is an integer but not a character code    representation_error(character_code)

Portability

GNU Prolog predicates.

7.12.5 put_char/2, put_char/1, put_code/1, put_code/2, nl/1, nl/0

Templates
put_char(+stream_or_alias, +character)
put_char(+character)
put_code(+stream_or_alias, +character_code)
put_code(+character_code)
nl(+stream_or_alias)
nl
Description

put_char(SorA, Char) writes Char onto the stream associated with the stream-term or alias SorA.

put_code/2 is similar to put_char/2 but deals with character codes.

nl(SorA) writes a new-line character onto the stream associated with the stream-term or alias SorA. This is equivalent to put_char(SorA, '\n').

put_char/1, put_code/1 and nl/0 apply to the current output stream.

Errors
SorA is a variable    instantiation_error
Char is a variable    instantiation_error
Code is a variable    instantiation_error
Char is neither a variable nor a character    type_error(character, Char)
Code is neither a variable nor an integer    type_error(integer, Code)
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)
Code is an integer but not a character code    representation_error(character_code)

Portability

ISO predicates.




Copyright (C) 1999-2002 Daniel Diaz.

Chapters 9 and 10 : Copyright (C) 2002-2003 INRIA, Rémy Haemmerlé.

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