Character input/output

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.