.. index:: csv_protocol
.. _csv_protocol/0:

.. rst-class:: right

**protocol**

``csv_protocol``
================

CSV file and stream reading and writing protocol.

| **Availability:** 
|    ``logtalk_load(csv(loader))``

| **Author:** Jacinto Dávila and Paulo Moura
| **Version:** 2:0:0
| **Date:** 2023-03-13

| **Compilation flags:**
|    ``static``


| **Dependencies:**
|   (none)


| **Remarks:**

   - Type-checking: Some of the predicate file and stream argument type-checking exceptions depend on the Prolog backend compliance with standards.

| **Inherited public predicates:**
|    (none)

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

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

.. index:: read_file/3
.. _csv_protocol/0::read_file/3:

``read_file/3``
^^^^^^^^^^^^^^^

Reads a CSV file saving the data as clauses for the specified object predicate. Fails if the file cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_file(File,Object,Predicate)``
| **Mode and number of proofs:**
|    ``read_file(+atom,+object_identifier,+predicate_indicator)`` - ``zero_or_one``

| **Exceptions:**
|    ``File`` is a variable:
|        ``instantiation_error``
|    ``File`` is neither a variable nor an atom:
|        ``type_error(atom,File)``
|    ``File`` is an atom but not an existing file:
|        ``existence_error(file,File)``
|    ``File`` is an existing file but cannot be opened for reading:
|        ``permission_error(open,source_sink,File)``
|    ``Object`` is a variable:
|        ``instantiation_error``
|    ``Object`` is neither a variable nor an object identifier:
|        ``type_error(object_identifier,Object)``
|    ``Object`` is a valid object identifier but not an existing object:
|        ``existence_error(object,Object)``
|    ``Predicate`` is a variable:
|        ``instantiation_error``
|    ``Predicate`` is neither a variable nor a predicate indicator:
|        ``type_error(predicate_indicator,Predicate)``
|    ``Predicate`` is a valid predicate indicator but not an existing public predicate:
|        ``existence_error(predicate,Predicate)``


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

.. index:: read_stream/3
.. _csv_protocol/0::read_stream/3:

``read_stream/3``
^^^^^^^^^^^^^^^^^

Reads a CSV stream saving the data as clauses for the specified object predicate. Fails if the stream cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_stream(Stream,Object,Predicate)``
| **Mode and number of proofs:**
|    ``read_stream(+stream_or_alias,+object_identifier,+predicate_indicator)`` - ``zero_or_one``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Stream`` is neither a variable nor a stream-term or alias:
|        ``domain_error(stream_or_alias,Stream)``
|    ``Stream`` is not an open stream:
|        ``existence_error(stream,Stream)``
|    ``Stream`` is an output stream:
|        ``permission_error(input,stream,Stream)``
|    ``Stream`` is a binary stream:
|        ``permission_error(input,binary_stream,Stream)``
|    ``Object`` is a variable:
|        ``instantiation_error``
|    ``Object`` is neither a variable nor an object identifier:
|        ``type_error(object_identifier,Object)``
|    ``Object`` is a valid object identifier but not an existing object:
|        ``existence_error(object,Object)``
|    ``Predicate`` is a variable:
|        ``instantiation_error``
|    ``Predicate`` is neither a variable nor a predicate indicator:
|        ``type_error(predicate_indicator,Predicate)``
|    ``Predicate`` is a valid predicate indicator but not an existing public predicate:
|        ``existence_error(predicate,Predicate)``


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

.. index:: read_file/2
.. _csv_protocol/0::read_file/2:

``read_file/2``
^^^^^^^^^^^^^^^

Reads a CSV file returning the data as a list of rows, each row a list of fields. Fails if the file cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_file(File,Rows)``
| **Mode and number of proofs:**
|    ``read_file(+atom,-list(list))`` - ``zero_or_one``

| **Exceptions:**
|    ``File`` is a variable:
|        ``instantiation_error``
|    ``File`` is neither a variable nor an atom:
|        ``type_error(atom,File)``
|    ``File`` is an atom but not an existing file:
|        ``existence_error(file,File)``
|    ``File`` is an existing file but cannot be opened for reading:
|        ``permission_error(open,source_sink,File)``


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

.. index:: read_stream/2
.. _csv_protocol/0::read_stream/2:

``read_stream/2``
^^^^^^^^^^^^^^^^^

Reads a CSV stream returning the data as a list of rows, each row a list of fields. Fails if the stream cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_stream(Stream,Rows)``
| **Mode and number of proofs:**
|    ``read_stream(+stream_or_alias,-list(list))`` - ``zero_or_one``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Stream`` is neither a variable nor a stream-term or alias:
|        ``domain_error(stream_or_alias,Stream)``
|    ``Stream`` is not an open stream:
|        ``existence_error(stream,Stream)``
|    ``Stream`` is an output stream:
|        ``permission_error(input,stream,Stream)``
|    ``Stream`` is a binary stream:
|        ``permission_error(input,binary_stream,Stream)``


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

.. index:: read_file_by_line/3
.. _csv_protocol/0::read_file_by_line/3:

``read_file_by_line/3``
^^^^^^^^^^^^^^^^^^^^^^^

Reads a CSV file saving the data as clauses for the specified object predicate. The file is read line by line. Fails if the file cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_file_by_line(File,Object,Predicate)``
| **Mode and number of proofs:**
|    ``read_file_by_line(+atom,+object_identifier,+predicate_indicator)`` - ``zero_or_one``

| **Exceptions:**
|    ``File`` is a variable:
|        ``instantiation_error``
|    ``File`` is neither a variable nor an atom:
|        ``type_error(atom,File)``
|    ``File`` is an atom but not an existing file:
|        ``existence_error(file,File)``
|    ``File`` is an existing file but cannot be opened for reading:
|        ``permission_error(open,source_sink,File)``
|    ``Object`` is a variable:
|        ``instantiation_error``
|    ``Object`` is neither a variable nor an object identifier:
|        ``type_error(object_identifier,Object)``
|    ``Object`` is a valid object identifier but not an existing object:
|        ``existence_error(object,Object)``
|    ``Predicate`` is a variable:
|        ``instantiation_error``
|    ``Predicate`` is neither a variable nor a predicate indicator:
|        ``type_error(predicate_indicator,Predicate)``
|    ``Predicate`` is a valid predicate indicator but not an existing public predicate:
|        ``existence_error(predicate,Predicate)``


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

.. index:: read_stream_by_line/3
.. _csv_protocol/0::read_stream_by_line/3:

``read_stream_by_line/3``
^^^^^^^^^^^^^^^^^^^^^^^^^

Reads a CSV stream saving the data as clauses for the specified object predicate. The stream is read line by line. Fails if the stream cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_stream_by_line(Stream,Object,Predicate)``
| **Mode and number of proofs:**
|    ``read_stream_by_line(+stream_or_alias,+object_identifier,+predicate_indicator)`` - ``zero_or_one``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Stream`` is neither a variable nor a stream-term or alias:
|        ``domain_error(stream_or_alias,Stream)``
|    ``Stream`` is not an open stream:
|        ``existence_error(stream,Stream)``
|    ``Stream`` is an output stream:
|        ``permission_error(input,stream,Stream)``
|    ``Stream`` is a binary stream:
|        ``permission_error(input,binary_stream,Stream)``
|    ``Object`` is a variable:
|        ``instantiation_error``
|    ``Object`` is neither a variable nor an object identifier:
|        ``type_error(object_identifier,Object)``
|    ``Object`` is a valid object identifier but not an existing object:
|        ``existence_error(object,Object)``
|    ``Predicate`` is a variable:
|        ``instantiation_error``
|    ``Predicate`` is neither a variable nor a predicate indicator:
|        ``type_error(predicate_indicator,Predicate)``
|    ``Predicate`` is a valid predicate indicator but not an existing public predicate:
|        ``existence_error(predicate,Predicate)``


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

.. index:: read_file_by_line/2
.. _csv_protocol/0::read_file_by_line/2:

``read_file_by_line/2``
^^^^^^^^^^^^^^^^^^^^^^^

Reads a CSV file returning the data as a list of rows, each row a list of fields. The file is read line by line. Fails if the file cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_file_by_line(File,Rows)``
| **Mode and number of proofs:**
|    ``read_file_by_line(+atom,-list(list))`` - ``zero_or_one``

| **Exceptions:**
|    ``File`` is a variable:
|        ``instantiation_error``
|    ``File`` is neither a variable nor an atom:
|        ``type_error(atom,File)``
|    ``File`` is an atom but not an existing file:
|        ``existence_error(file,File)``
|    ``File`` is an existing file but cannot be opened for reading:
|        ``permission_error(open,source_sink,File)``


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

.. index:: read_stream_by_line/2
.. _csv_protocol/0::read_stream_by_line/2:

``read_stream_by_line/2``
^^^^^^^^^^^^^^^^^^^^^^^^^

Reads a CSV stream returning the data as a list of rows, each row a list of fields. The stream is read line by line. Fails if the stream cannot be parsed.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``read_stream_by_line(Stream,Rows)``
| **Mode and number of proofs:**
|    ``read_stream_by_line(+stream_or_alias,-list(list))`` - ``zero_or_one``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Stream`` is neither a variable nor a stream-term or alias:
|        ``domain_error(stream_or_alias,Stream)``
|    ``Stream`` is not an open stream:
|        ``existence_error(stream,Stream)``
|    ``Stream`` is an output stream:
|        ``permission_error(input,stream,Stream)``
|    ``Stream`` is a binary stream:
|        ``permission_error(input,binary_stream,Stream)``


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

.. index:: write_file/3
.. _csv_protocol/0::write_file/3:

``write_file/3``
^^^^^^^^^^^^^^^^

Writes a CSV file with the data represented by the clauses of the specified object predicate.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``write_file(File,Object,Predicate)``
| **Mode and number of proofs:**
|    ``write_file(+atom,+object_identifier,+predicate_indicator)`` - ``one``

| **Exceptions:**
|    ``File`` is a variable:
|        ``instantiation_error``
|    ``File`` is neither a variable nor an atom:
|        ``type_error(atom,File)``
|    ``File`` is an atom but cannot be opened for writing:
|        ``permission_error(open,source_sink,File)``
|    ``Object`` is a variable:
|        ``instantiation_error``
|    ``Object`` is neither a variable nor an object identifier:
|        ``type_error(object_identifier,Object)``
|    ``Object`` is a valid object identifier but not an existing object:
|        ``existence_error(object,Object)``
|    ``Predicate`` is a variable:
|        ``instantiation_error``
|    ``Predicate`` is neither a variable nor a predicate indicator:
|        ``type_error(predicate_indicator,Predicate)``
|    ``Predicate`` is a valid predicate indicator but not an existing public predicate:
|        ``existence_error(predicate,Predicate)``


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

.. index:: write_stream/3
.. _csv_protocol/0::write_stream/3:

``write_stream/3``
^^^^^^^^^^^^^^^^^^

Writes a CSV stream with the data represented by the clauses of the specified object predicate.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``write_stream(Stream,Object,Predicate)``
| **Mode and number of proofs:**
|    ``write_stream(+stream_or_alias,+object_identifier,+predicate_indicator)`` - ``one``

| **Exceptions:**
|    ``Stream`` is a variable:
|        ``instantiation_error``
|    ``Stream`` is neither a variable nor a stream-term or alias:
|        ``domain_error(stream_or_alias,Stream)``
|    ``Stream`` is not an open stream:
|        ``existence_error(stream,Stream)``
|    ``Stream`` is an input stream:
|        ``permission_error(output,stream,Stream)``
|    ``Stream`` is a binary stream:
|        ``permission_error(output,binary_stream,Stream)``
|    ``Object`` is a variable:
|        ``instantiation_error``
|    ``Object`` is neither a variable nor an object identifier:
|        ``type_error(object_identifier,Object)``
|    ``Object`` is a valid object identifier but not an existing object:
|        ``existence_error(object,Object)``
|    ``Predicate`` is a variable:
|        ``instantiation_error``
|    ``Predicate`` is neither a variable nor a predicate indicator:
|        ``type_error(predicate_indicator,Predicate)``
|    ``Predicate`` is a valid predicate indicator but not an existing public predicate:
|        ``existence_error(predicate,Predicate)``


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

.. index:: guess_separator/2
.. _csv_protocol/0::guess_separator/2:

``guess_separator/2``
^^^^^^^^^^^^^^^^^^^^^

Guesses the separator used in a given file, asking the user to confirm.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``guess_separator(File,Separator)``
| **Mode and number of proofs:**
|    ``guess_separator(+atom,-atom)`` - ``one``

| **Exceptions:**
|    ``File`` is a variable:
|        ``instantiation_error``
|    ``File`` is neither a variable nor an atom:
|        ``type_error(atom,File)``
|    ``File`` is an atom but not an existing file:
|        ``existence_error(file,File)``
|    ``File`` is an atom but cannot be opened for writing:
|        ``permission_error(open,source_sink,File)``


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

.. index:: guess_arity/2
.. _csv_protocol/0::guess_arity/2:

``guess_arity/2``
^^^^^^^^^^^^^^^^^

Guesses the arity of records in a given file, asking the user to confirm.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``guess_arity(File,Arity)``
| **Mode and number of proofs:**
|    ``guess_arity(+atom,-number)`` - ``one``

| **Exceptions:**
|    ``File`` is a variable:
|        ``instantiation_error``
|    ``File`` is neither a variable nor an atom:
|        ``type_error(atom,File)``
|    ``File`` is an atom but not an existing file:
|        ``existence_error(file,File)``
|    ``File`` is an atom but cannot be opened for writing:
|        ``permission_error(open,source_sink,File)``


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

Protected predicates
--------------------

(none)

Private predicates
------------------

(none)

Operators
---------

(none)