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

#### 8.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 8.15).

#### 8.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 |  | uninstantiation_error(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.

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

#### 8.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 8.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 |  | uninstantiation_error(Stream)

Portability

GNU Prolog predicates.

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