Constant term streams

6.11 | Constant term streams

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

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

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

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

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