Previous Up Next

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

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

8.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(SorA, Code) 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 4.2.6) otherwise get_key/2 behaves similarly to get_code/2 (section 8.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.

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

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

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