Constant term streams

### 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 with 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 with 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_output_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 with 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-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