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:1
Date: 2025-05-07
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)

## Public predicates

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

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

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

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

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

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

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

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

### `write_file/3`

Writes a CSV file with the data represented by the solutions to 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)`

### `write_stream/3`

Writes a CSV stream with the data represented by the solutions to 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)`

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

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