View Source Table.Reader protocol (Table v0.1.2)

A protocol to read tabular data.

Link to this section Summary

Types

Describes column-based traversal.

Table metadata.

Describes row-based traversal.

t()

Functions

Returns information on how to traverse the given tabular data.

Link to this section Types

@type column_reader() :: {:columns, metadata(), Enumerable.t()}

Describes column-based traversal.

The enumerable should yield columns, where each column is a series of values. The columns should have the same order as columns in the metadata.

@type metadata() :: %{
  :columns => [Table.column()],
  optional(:count) => non_neg_integer(),
  optional({term(), term()}) => any()
}

Table metadata.

User-specific metadata can be added in the form of namespaced tuples as keys. The first element is the namespace key, typically an atom, and the second is any term. The value can also be anything.

@type row_reader() :: {:rows, metadata(), Enumerable.t()}

Describes row-based traversal.

The enumerable should yield rows, where each row is a series of values. The values should follow the order of columns in the metadata.

@type t() :: term()

Link to this section Functions

@spec init(t()) :: row_reader() | column_reader() | :none

Returns information on how to traverse the given tabular data.

There are generally two distinct ways of traversing tabular data, that is, a row-based one and a column-based one. Depending on the underlying data representation, one of them is more natural and more efficient.

The init/1 return value describes either of the two traversal types, see row_reader/0 and column_reader/0 respectively.

Some structs may be tabular only in a subset of cases, therefore :none may be returned to indicate that there is no valid data to read.

The init/1 function should not initiate any form of traversal or open existing resources. If any setup is necessary, it should be performed when the underlying row or column enumerables are traversed.