.. index:: single: term_io_protocol
.. _term_io_protocol/0:

.. rst-class:: right

**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:0
| **Date:** 2021-10-04

| **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)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: read_term_from_atom/3
.. _term_io_protocol/0::read_term_from_atom/3:

``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``


------------

.. index:: read_from_atom/2
.. _term_io_protocol/0::read_from_atom/2:

``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``


------------

.. index:: read_term_from_chars/3
.. _term_io_protocol/0::read_term_from_chars/3:

``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``


------------

.. index:: read_term_from_chars/4
.. _term_io_protocol/0::read_term_from_chars/4:

``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``


------------

.. index:: read_from_chars/2
.. _term_io_protocol/0::read_from_chars/2:

``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``


------------

.. index:: read_term_from_codes/3
.. _term_io_protocol/0::read_term_from_codes/3:

``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``


------------

.. index:: read_term_from_codes/4
.. _term_io_protocol/0::read_term_from_codes/4:

``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``


------------

.. index:: read_from_codes/2
.. _term_io_protocol/0::read_from_codes/2:

``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``


------------

.. index:: write_term_to_atom/3
.. _term_io_protocol/0::write_term_to_atom/3:

``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``


------------

.. index:: write_to_atom/2
.. _term_io_protocol/0::write_to_atom/2:

``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``


------------

.. index:: write_term_to_chars/3
.. _term_io_protocol/0::write_term_to_chars/3:

``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``


------------

.. index:: write_term_to_chars/4
.. _term_io_protocol/0::write_term_to_chars/4:

``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``


------------

.. index:: write_to_chars/2
.. _term_io_protocol/0::write_to_chars/2:

``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``


------------

.. index:: write_term_to_codes/3
.. _term_io_protocol/0::write_term_to_codes/3:

``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``


------------

.. index:: write_term_to_codes/4
.. _term_io_protocol/0::write_term_to_codes/4:

``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``


------------

.. index:: write_to_codes/2
.. _term_io_protocol/0::write_to_codes/2:

``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``


------------

.. index:: format_to_atom/3
.. _term_io_protocol/0::format_to_atom/3:

``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``


------------

.. index:: format_to_chars/3
.. _term_io_protocol/0::format_to_chars/3:

``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``


------------

.. index:: format_to_chars/4
.. _term_io_protocol/0::format_to_chars/4:

``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``


------------

.. index:: format_to_codes/3
.. _term_io_protocol/0::format_to_codes/3:

``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``


------------

.. index:: format_to_codes/4
.. _term_io_protocol/0::format_to_codes/4:

``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``


------------

.. index:: with_output_to/2
.. _term_io_protocol/0::with_output_to/2:

``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)