Character input/output

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

#### 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(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 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-2009 Daniel Diaz Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved. More about the copyright