Character input/output
Author: Daniel Diaz
Keywords: GNU Prolog, manual, Prolog, compiler, constraints, finite domains

### 8.12 Character input/output

- get_char/2, get_char/1, get_code/1, get_code/2
- get_key/2, get_key/1 get_key_no_echo/2, get_key_no_echo/1
- peek_char/2, peek_char/1, peek_code/1, peek_code/2
- unget_char/2, unget_char/1, unget_code/2, unget_code/1
- put_char/2, put_char/1, put_code/1, put_code/2, nl/1, nl/0

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