7.11 | Constant term streams

- Introduction
- `open_input_atom_stream/2`, `open_input_chars_stream/2`,
  `open_input_codes_stream/2`
- `close_input_atom_stream/1`, `close_input_chars_stream/1`,
  `close_input_codes_stream/1`
- `open_output_atom_stream/1`, `open_output_chars_stream/1`,
  `open_output_codes_stream/1`
- `close_output_atom_stream/2`, `close_output_chars_stream/2`,
  `close_output_codes_stream/2`

7.11.1 | Introduction

Constant term streams allow the user to consider a constant term (atom, character list or character code list) as a source/sink by associating to them a stream. Reading from a constant term stream will deliver the characters of the constant term as if they had been read from a standard file. Characters written on a constant term stream are stored to form the final constant term when the stream is closed. The built-in predicates described in this section allow the user to open and close a constant term stream for input or output. However, very often, a constant term stream is created to be only read or written once and then closed. To avoid the creation and the destruction of such a stream, GNU Prolog offers several built-in predicates to perform single input/output from/to constant terms (section 7.15).

7.11.2 | `open_input_atom_stream/2`, `open_input_chars_stream/2`, `open_input_codes_stream/2`

Templates

  `open_input_atom_stream(+atom, -stream)
  open_input_chars_stream(+character_list, -stream)
  open_input_codes_stream(+character_code_list, -stream)`

Description
`open_input_atom_stream(Atom, Stream)` unifies `Stream` with the stream-term which is associated to a new input text-stream whose data are the characters of `Atom`.
`open_input_chars_stream(Chars, Stream)` is similar to `open_input_atom_stream/2` except that data are the content of the character list `Chars`.
`open_input_codes_stream(Codes, Stream)` is similar to `open_input_atom_stream/2` except that data are the content of the character code list `Codes`.
Errors

`Stream` is not a variable |  | `type_error(variable, Stream)`

`Atom` is a variable |  | `instantiation_error`

`Chars` is a partial list or a list with an element `E` which is a variable |  | `instantiation_error`

`Codes` is a partial list or a list with an element `E` which is a variable |  | `instantiation_error`

`Atom` is neither a variable nor a an atom |  | `type_error(atom, Atom)`

`Chars` is neither a partial list nor a list |  | `type_error(list, Chars)`

`Codes` is neither a partial list nor a list |  | `type_error(list, Codes)`

an element `E` of the `Chars` list is neither a variable nor a character |  | `type_error(character, E)`

an element `E` of the `Codes` list is neither a variable nor an integer |  | `type_error(integer, E)`

an element `E` of the `Codes` list is an integer but not a character code |  | `representation_error(character_code)`

Portability
GNU Prolog predicates.

7.11.3 | `close_input_atom_stream/1`, `close_input_chars_stream/1`, `close_input_codes_stream/1`

Templates

  `close_input_atom_stream(+stream_or_alias)
  close_input_chars_stream(+stream_or_alias)
  close_input_codes_stream(+stream_or_alias)`

Description
`close_input_atom_stream(SorA)` closes the constant term stream associated with the stream-term or alias `SorA`. `SorA` must a stream open with `open_input_atom_stream/2` (section 7.11.1).
`close_input_chars_stream(SorA)` acts similarly for a character list stream.
`close_input_codes_stream(SorA)` acts similarly for a character code list stream.
Errors

`SorA` is a variable |  | `instantiation_error`

`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(close, stream, SorA)`

`SorA` is a stream-term or alias but does not refer to a constant term stream. |  | `domain_error(term_stream_or_alias, SorA)`

Portability
GNU Prolog predicates.

7.11.4 | `open_output_atom_stream/1`, `open_output_chars_stream/1`, `open_output_codes_stream/1`

Templates

  `open_output_atom_stream(-stream)
  open_output_chars_stream(-stream)
  open_output_codes_stream(-stream)`

Description
`open_output_atom_stream(Stream)` unifies `Stream` with the stream-term which is associated to a new output text-stream. All characters written to this stream are collected and will be returned as an atom when the stream is closed by `close_ouput_atom_stream/2` (section 7.11.5).
`open_output_chars_stream(Stream)` is similar to `open_output_atom_stream/1` except that the result will be a character list.
`open_output_codes_stream(Stream)` is similar to `open_output_atom_stream/1` except that the result will be a character code list.
Errors

`Stream` is not a variable |  | `type_error(variable, Stream)`

Portability
GNU Prolog predicates.

7.11.5 | `close_output_atom_stream/2`, `close_output_chars_stream/2`, `close_output_codes_stream/2`

Templates

  `close_output_atom_stream(+stream_or_alias, ?atom)
  close_output_chars_stream(+stream_or_alias, ?character_list)
  close_output_codes_stream(+stream_or_alias, ?character_code_list)`

Description
`close_output_atom_stream(SorA, Atom)` closes the constant term stream associated with the stream-term or alias `SorA`. `SorA` must be associated to a stream open with `open_output_atom_stream/1` (section 7.11.4). `Atom` is unified with an atom formed with all characters written on the stream.
`close_output_chars_stream(SorA, Chars)` acts similarly for a character list stream.
`close_output_codes_stream(SorA, Codes)` acts similarly for a character code list stream.
Errors

`SorA` is a variable |  | `instantiation_error`

`Atom` is neither a variable nor an atom |  | `type_error(atom, Atom)`

`Chars` is neither a partial list nor a list |  | `type_error(list, Chars)`

`Codes` is neither a partial list nor a list |  | `type_error(list, Codes)`

`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(close, stream, SorA)`

`SorA` is a stream-term or alias but does not refer to a constant term stream |  | `domain_error(term_stream_or_alias, SorA)`

Portability
GNU Prolog predicates.

Copyright (C) 1999-2002 Daniel Diaz
Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.
More about the copyright