Character input/output

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

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

6.12.2 | `get_code_no_echo/2`, `get_code_no_echo/1`

Templates

  `get_code_no_echo(+stream_or_alias, ?integer)
  get_code_no_echo(?integer)`

Description
`get_code_no_echo/2` is similar to `get_code/2` (section 6.12.1) except that if the associated source is a terminal the input is not echoed. This is possible only if the `linedit` facility has been installed (section 2.2.5) otherwise `get_code_no_echo/2` is similar to `get_code/2`. Any integer can be returned (not only an in-character code) to allow for function key reading.
`get_code_no_echo/1` applies 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.

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

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

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