protocol

# `term_io_protocol`

Predicates for term input/output from/to atom, chars, and codes. The predicates are declared as synchronized when the library is compiled using a backend supporting threads.

Availability:
`logtalk_load(term_io(loader))`
Author: Paulo Moura
Version: 1:3:1
Date: 2026-06-15
Compilation flags:
`static`
Dependencies:
(none)
Remarks:

> - Portability notes: To keep calls to these library predicates portable, use only standard read/write options and specify output formats using atoms.

Inherited public predicates:
(none)

## Public predicates

### `read_term_from_atom/3`

Reads a term from an atom using the given read options. A period at the end of the atom is optional. Valid options are those supported by the standard `read_term/3` predicate.

Compilation flags:
`static, synchronized`
Template:
`read_term_from_atom(Atom,Term,Options)`
Mode and number of proofs:
`read_term_from_atom(+atom,-term,+list(read_option))` - `one_or_error`
Exceptions:
`Atom` is a variable:
`instantiation_error`
`Atom` is neither a variable nor an atom:
`type_error(atom,Atom)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(read_option,Option)`

### `read_from_atom/2`

Reads a term from an atom using default read options. Shorthand for `read_term_from_atom(Atom,Term,[])`. A period at the end of the atom is optional.

Compilation flags:
`static`
Template:
`read_from_atom(Atom,Term)`
Mode and number of proofs:
`read_from_atom(+atom,-term)` - `one_or_error`
Exceptions:
`Atom` is a variable:
`instantiation_error`
`Atom` is neither a variable nor an atom:
`type_error(atom,Atom)`
`Atom` text cannot be read as a term:
`syntax_error(BackendDependentArgument)`

### `read_term_from_chars/3`

Reads a term from a list of characters using the given read options. A period at the end of the list is optional. Valid options are those supported by the standard `read_term/3` predicate.

Compilation flags:
`static, synchronized`
Template:
`read_term_from_chars(Chars,Term,Options)`
Mode and number of proofs:
`read_term_from_chars(+list(character),-term,+list(read_option))` - `one_or_error`
Exceptions:
`Chars` contains a variable element:
`instantiation_error`
`Chars` contains an element that is not a character:
`type_error(character,Char)`
`Chars` text cannot be read as a term:
`syntax_error(BackendDependentArgument)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(read_option,Option)`

### `read_term_from_chars/4`

Reads a term from a list of characters using the given read options, also returning the remaining characters. A period at the end of the term is required. Valid options are those supported by the standard `read_term/3` predicate.

Compilation flags:
`static`
Template:
`read_term_from_chars(Chars,Term,Tail,Options)`
Mode and number of proofs:
`read_term_from_chars(+list(character),-term,-list(character),+list(read_option))` - `one_or_error`
Exceptions:
`Chars` contains an element that is not a character:
`type_error(character,Char)`
`Chars` text cannot be read as a term:
`syntax_error(BackendDependentArgument)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(read_option,Option)`

### `read_from_chars/2`

Reads a term from a list of characters using default read options. Shorthand for `read_term_from_chars(Chars,Term,[])`. A period at the end of the list is optional.

Compilation flags:
`static`
Template:
`read_from_chars(Chars,Term)`
Mode and number of proofs:
`read_from_chars(+list(character),-term)` - `one_or_error`
Exceptions:
`Chars` contains a variable element:
`instantiation_error`
`Chars` contains an element that is not a character:
`type_error(character,Char)`
`Chars` text cannot be read as a term:
`syntax_error(BackendDependentArgument)`

### `read_term_from_codes/3`

Reads a term from a list of character codes using the given read options. A period at the end of the list is optional. Valid options are those supported by the standard `read_term/3` predicate.

Compilation flags:
`static, synchronized`
Template:
`read_term_from_codes(Codes,Term,Options)`
Mode and number of proofs:
`read_term_from_codes(+list(character_code),-term,+list(read_option))` - `one_or_error`
Exceptions:
`Codes` contains a variable element:
`instantiation_error`
`Codes` contains an element that is not a character code:
`type_error(integer,Code)`
`Codes` text cannot be read as a term:
`syntax_error(BackendDependentArgument)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(read_option,Option)`

### `read_term_from_codes/4`

Reads a term from a list of character codes using the given read options, also returning the remaining character codes. A period at the end of the term is required. Valid options are those supported by the standard `read_term/3` predicate.

Compilation flags:
`static`
Template:
`read_term_from_codes(Codes,Term,Tail,Options)`
Mode and number of proofs:
`read_term_from_codes(+list(character_code),-term,-list(character_code),+list(read_option))` - `one_or_error`
Exceptions:
`Codes` contains an element that is not a character code:
`type_error(integer,Code)`
`Codes` text cannot be read as a term:
`syntax_error(BackendDependentArgument)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(read_option,Option)`

### `read_from_codes/2`

Reads a term from a list of character codes using default read options. Shorthand for `read_term_from_codes(Codes,Term,[])`. A period at the end of the list is optional.

Compilation flags:
`static`
Template:
`read_from_codes(Codes,Term)`
Mode and number of proofs:
`read_from_codes(+list(character_code),-term)` - `one_or_error`
Exceptions:
`Codes` contains a variable element:
`instantiation_error`
`Codes` contains an element that is not a character code:
`type_error(integer,Code)`
`Codes` text cannot be read as a term:
`syntax_error(BackendDependentArgument)`
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(read_option,Option)`

### `write_term_to_atom/3`

Writes a term to an atom using the given write options. Valid options are those supported by the standard `write_term/3` predicate.

Compilation flags:
`static, synchronized`
Template:
`write_term_to_atom(Term,Atom,Options)`
Mode and number of proofs:
`write_term_to_atom(@term,-atom,+list(write_option))` - `one`
Exceptions:
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(write_option,Option)`

### `write_to_atom/2`

Writes a term to an atom using default write options. Shorthand for `write_term_to_atom(Term,Atom,[])`.

Compilation flags:
`static`
Template:
`write_to_atom(Term,Atom)`
Mode and number of proofs:
`write_to_atom(@term,-atom)` - `one`

### `write_term_to_chars/3`

Writes a term to a list of characters using the given write options. Shorthand for `write_term_to_chars(Term,Chars,[],Options)`. Valid options are those supported by the standard `write_term/3` predicate.

Compilation flags:
`static`
Template:
`write_term_to_chars(Term,Chars,Options)`
Mode and number of proofs:
`write_term_to_chars(@term,-list(character),+list(write_option))` - `one_or_error`
Exceptions:
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(write_option,Option)`

### `write_term_to_chars/4`

Writes a term to a list of characters with the given tail using the given write options. Valid options are those supported by the standard `write_term/3` predicate.

Compilation flags:
`static, synchronized`
Template:
`write_term_to_chars(Term,Chars,Tail,Options)`
Mode and number of proofs:
`write_term_to_chars(@term,-list(character),@term,+list(write_option))` - `one_or_error`
Exceptions:
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(write_option,Option)`

### `write_to_chars/2`

Writes a term to a list of characters using default write options. Shorthand for `write_term_to_chars(Term,Chars,[],[])`.

Compilation flags:
`static`
Template:
`write_to_chars(Term,Chars)`
Mode and number of proofs:
`write_to_chars(@term,-list(character))` - `one`

### `write_term_to_codes/3`

Writes a term to a list of character codes using the given write options. Shorthand for `write_term_to_codes(Term,Codes,[],Options)`. Valid options are those supported by the standard `write_term/3` predicate.

Compilation flags:
`static`
Template:
`write_term_to_codes(Term,Codes,Options)`
Mode and number of proofs:
`write_term_to_codes(@term,-list(character_code),+list(write_option))` - `one_or_error`
Exceptions:
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(write_option,Option)`

### `write_term_to_codes/4`

Writes a term to a list of character codes with the given tail using the given write options. Valid options are those supported by the standard `write_term/3` predicate.

Compilation flags:
`static, synchronized`
Template:
`write_term_to_codes(Term,Codes,Tail,Options)`
Mode and number of proofs:
`write_term_to_codes(@term,-list(character_code),@term,+list(write_option))` - `one_or_error`
Exceptions:
`Options` is a variable:
`instantiation_error`
`Options` is neither a variable nor a list:
`type_error(list,Options)`
An element `Option` of the list `Options` is a variable:
`instantiation_error`
An element `Option` of the list `Options` is neither a variable nor a compound term:
`type_error(compound,Option)`
An element `Option` of the list `Options` is a compound term but not a valid option:
`domain_error(write_option,Option)`

### `write_to_codes/2`

Writes a term to a list of character codes using default write options. Shorthand for `write_term_to_chars(Term,Codes,[],[])`.

Compilation flags:
`static`
Template:
`write_to_codes(Term,Codes)`
Mode and number of proofs:
`write_to_codes(@term,-list(character_code))` - `one`

### `format_to_atom/3`

Writes a list of arguments to an atom using the given format (specified as in the de facto standard `format/2` predicate).

Compilation flags:
`static, synchronized`
Template:
`format_to_atom(Format,Arguments,Atom)`
Mode and number of proofs:
`format_to_atom(@atom,+list(term),-atom)` - `one`

### `format_to_chars/3`

Writes a list of arguments to a list of characters using the given format (specified as in the de facto standard `format/2` predicate). Shorthand for `format_to_chars(Format,Arguments,Chars,[])`.

Compilation flags:
`static`
Template:
`format_to_chars(Format,Arguments,Chars)`
Mode and number of proofs:
`format_to_chars(@term,+list(term),-list(character))` - `one`

### `format_to_chars/4`

Writes a term to a list of characters with the given tail using the given format (specified as in the de facto standard `format/2` predicate).

Compilation flags:
`static, synchronized`
Template:
`format_to_chars(Format,Arguments,Chars,Tail)`
Mode and number of proofs:
`format_to_chars(@term,+list(term),-list(character),@term)` - `one`

### `format_to_codes/3`

Writes a list of arguments to a list of character codes using the given format (specified as in the de facto standard `format/2` predicate). Shorthand for `format_to_codes(Format,Arguments,Codes,[])`.

Compilation flags:
`static`
Template:
`format_to_codes(Format,Arguments,Codes)`
Mode and number of proofs:
`format_to_codes(@term,+list(term),-list(character_code))` - `one`

### `format_to_codes/4`

Writes a list of arguments to a list of character codes with the given tail using the given format (specified as in the de facto standard `format/2` predicate).

Compilation flags:
`static, synchronized`
Template:
`format_to_codes(Format,Arguments,Codes,Tail)`
Mode and number of proofs:
`format_to_codes(@term,+list(term),-list(character_code),@term)` - `one`

### `with_output_to/2`

Calls a goal deterministically with output to the given format: `atom(Atom)`, `chars(Chars)`, `chars(Chars,Tail)`, `codes(Codes)`, or `codes(Codes,Tail)`.

Compilation flags:
`static, synchronized`
Template:
`with_output_to(Output,Goal)`
Meta-predicate template:
`with_output_to(*,0)`
Mode and number of proofs:
`with_output_to(+compound,+callable)` - `zero_or_one`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)