hnc_csv (hnc_csv v0.4.0)

Successively calls the given function Fun with each CSV line decoded from the raw binary data in RawData or provided by Provider as first and an accumulator as second arguments.

decode_foreach(ProviderOrRawData, Fun)

Equivalent to decode_foreach(ProviderOrRawData, default_decode_options(), Fun).

decode_foreach(ProviderOrRawData, Options, Fun)

Successively calls the given function Fun with each CSV line decoded from the raw binary data in RawData or provided by Provider as argument.

decode_init(ProviderOrRawData)

Equivalent to decode_init(ProviderOrRawData, default_decode_options()).

decode_init(ProviderOrRawData, Options)

Creates a CSV decoder state to incrementally decode the raw CSV document in RawData or provided by Provider, using the given Options.

decode_map(ProviderOrRawData, Fun)

Equivalent to decode_map(ProviderOrRawData, default_decode_options(), Fun).

decode_map(ProviderOrRawData, Options, Fun)

Successively calls the given function Fun with each CSV line decoded from the raw binary data in RawData or provided by Provider as argument.

decode_next_line(State0)

Decodes and returns the next CSV line in the given decoder state, together with an updated state which can be used for further incremental decoding.

default_decode_options()

Returns the default decode options.

default_encode_options()

Returns the default encode options.

encode(Lines)

Equivalent to encode(Lines, default_encode_options()).

encode(Lines, Options)

Encodes the given CSV data structure into a CSV binary, using the given Options.

flush_provider(Provider)

Flushes and returns all data remaining in the given Provider.

get_binary_provider(Binary)

Equivalent to get_binary_provider(Binary, 1024).

get_binary_provider(Binary, ChunkSize)

Creates a data provider from the given Binary to supply data in chunks of the given ChunkSize.

get_file_provider(IoDevice)

Equivalent to get_file_provider(IoDevice, 1024).

get_file_provider(IoDevice, ChunkSize)

Creates a data provider from an open file given in IoDevice to supply data in chunks of the given ChunkSize.

Types

csv_field/0

-type csv_field() :: binary().

csv_line/0

-type csv_line() :: [csv_field()].

data/0

-type data() :: binary().

decode_options/0

-type decode_options() ::
          #{separator := byte(),
            enclosure := undefined | byte(),
            quote := undefined | enclosure | byte()}.

encode_options/0

-type encode_options() ::
          #{separator := byte(),
            enclosure := undefined | byte(),
            quote := undefined | enclosure | byte(),
            enclose := never | always | optional,
            end_of_line := binary()}.

provider/0

-type provider() :: fun(() -> end_of_data | {data(), provider()}).

state/0

-opaque state()

Functions

decode(ProviderOrRawData)

-spec decode(ProviderOrRawData) -> Lines
                when
                    ProviderOrRawData :: Provider | RawData,
                    Provider :: provider(),
                    RawData :: data(),
                    Lines :: [Line],
                    Line :: csv_line().

Equivalent to decode(ProviderOrRawData, default_decode_options()).

decode(ProviderOrRawData, Options)

-spec decode(ProviderOrRawData, Options) -> Lines
                when
                    ProviderOrRawData :: Provider | RawData,
                    Provider :: provider(),
                    RawData :: data(),
                    Options :: decode_options(),
                    Lines :: [Line],
                    Line :: csv_line().

Decodes the raw CSV document in RawData or provided by Provider, using the given Options, into a CSV data structure.

The return value is a list of CSV lines, which in turn are lists of CSV fields, which in turn are binaries representing the CSV field values.

decode_filter(ProviderOrRawData, Fun)

-spec decode_filter(ProviderOrRawData, Fun) -> Lines
                       when
                           ProviderOrRawData :: Provider | RawData,
                           Provider :: provider(),
                           RawData :: data(),
                           Fun :: fun((Line) -> boolean()),
                           Line :: csv_line(),
                           Lines :: [csv_line()].

Equivalent to decode_filter(ProviderOrRawData, default_decode_options(), Fun).

decode_filter(ProviderOrRawData, Options, Fun)

-spec decode_filter(ProviderOrRawData, Options, Fun) -> Lines
                       when
                           ProviderOrRawData :: Provider | RawData,
                           Provider :: provider(),
                           RawData :: data(),
                           Options :: decode_options(),
                           Fun :: fun((Line) -> boolean()),
                           Line :: csv_line(),
                           Lines :: [csv_line()].

Successively calls the given function Fun with each CSV line decoded from the raw binary data in RawData or provided by Provider as argument.

Returns a list of CSV lines for which Fun returned true.

decode_filtermap(ProviderOrRawData, Fun)

-spec decode_filtermap(ProviderOrRawData, Fun) -> Result
                          when
                              ProviderOrRawData :: Provider | RawData,
                              Provider :: provider(),
                              RawData :: data(),
                              Fun :: fun((Line) -> boolean() | {true, Mapped}),
                              Line :: csv_line(),
                              Mapped :: term(),
                              Result :: [Line | Mapped].

Equivalent to decode_filtermap(ProviderOrRawData, default_decode_options(), Fun).

decode_filtermap(ProviderOrRawData, Options, Fun)

-spec decode_filtermap(ProviderOrRawData, Options, Fun) -> Result
                          when
                              ProviderOrRawData :: Provider | RawData,
                              Provider :: provider(),
                              RawData :: data(),
                              Options :: decode_options(),
                              Fun :: fun((Line) -> boolean() | {true, Mapped}),
                              Line :: csv_line(),
                              Mapped :: term(),
                              Result :: [Line | Mapped].

Combines the functionality of decode_filter and decode_map.

If Fun returns true or false for a CSV line given to it, the CSV line is kept or discarded from the result list (filtering). If it returns {true, Mapped}, Mapped is inserted in the result list at the respective position (mapping).

decode_flush(State)

-spec decode_flush(State) -> Result when State :: state(), Result :: [Line], Line :: csv_line().

Reads and decodes any data remaining in the given CSV decoder state.

Returns a list of the remaining CSV lines.

decode_fold(ProviderOrRawData, Fun, Acc0)

-spec decode_fold(ProviderOrRawData, Fun, Acc0) -> Acc1
                     when
                         ProviderOrRawData :: Provider | RawData,
                         Provider :: provider(),
                         RawData :: data(),
                         Fun :: fun((Line, AccIn) -> AccOut),
                         Line :: csv_line(),
                         Acc0 :: term(),
                         Acc1 :: term(),
                         AccIn :: term(),
                         AccOut :: term().

Equivalent to decode_fold(ProviderOrRawData, default_decode_options(), Fun, Acc0).

decode_fold(ProviderOrRawData, Options, Fun, Acc0)

-spec decode_fold(ProviderOrRawData, Options, Fun, Acc0) -> Acc1
                     when
                         ProviderOrRawData :: Provider | RawData,
                         Provider :: provider(),
                         RawData :: data(),
                         Options :: decode_options(),
                         Fun :: fun((Line, AccIn) -> AccOut),
                         Line :: csv_line(),
                         Acc0 :: term(),
                         Acc1 :: term(),
                         AccIn :: term(),
                         AccOut :: term().

Successively calls the given function Fun with each CSV line decoded from the raw binary data in RawData or provided by Provider as first and an accumulator as second arguments.

Returns the final accumulator.

decode_foreach(ProviderOrRawData, Fun)

-spec decode_foreach(ProviderOrRawData, Fun) -> ok
                        when
                            ProviderOrRawData :: Provider | RawData,
                            Provider :: provider(),
                            RawData :: data(),
                            Fun :: fun((Line) -> _),
                            Line :: csv_line().

Equivalent to decode_foreach(ProviderOrRawData, default_decode_options(), Fun).

decode_foreach(ProviderOrRawData, Options, Fun)

-spec decode_foreach(ProviderOrRawData, Options, Fun) -> ok
                        when
                            ProviderOrRawData :: Provider | RawData,
                            Provider :: provider(),
                            RawData :: data(),
                            Options :: decode_options(),
                            Fun :: fun((Line) -> _),
                            Line :: csv_line().

Successively calls the given function Fun with each CSV line decoded from the raw binary data in RawData or provided by Provider as argument.

decode_init(ProviderOrRawData)

-spec decode_init(ProviderOrRawData) -> State
                     when
                         ProviderOrRawData :: Provider | RawData,
                         Provider :: provider(),
                         RawData :: data(),
                         State :: state().

Equivalent to decode_init(ProviderOrRawData, default_decode_options()).

decode_init(ProviderOrRawData, Options)

-spec decode_init(ProviderOrRawData, Options) -> State
                     when
                         ProviderOrRawData :: Provider | RawData,
                         Provider :: provider(),
                         RawData :: data(),
                         Options :: decode_options(),
                         State :: state().

Creates a CSV decoder state to incrementally decode the raw CSV document in RawData or provided by Provider, using the given Options.

The return value can be used as argument to the function decode_next_line/1 to obtain CSV lines one by one.

See also: decode_next_line/1.

decode_map(ProviderOrRawData, Fun)

-spec decode_map(ProviderOrRawData, Fun) -> Result
                    when
                        ProviderOrRawData :: Provider | RawData,
                        Provider :: provider(),
                        RawData :: data(),
                        Fun :: fun((Line) -> Mapped),
                        Line :: csv_line(),
                        Mapped :: term(),
                        Result :: [Mapped].

Equivalent to decode_map(ProviderOrRawData, default_decode_options(), Fun).

decode_map(ProviderOrRawData, Options, Fun)

-spec decode_map(ProviderOrRawData, Options, Fun) -> Result
                    when
                        ProviderOrRawData :: Provider | RawData,
                        Provider :: provider(),
                        RawData :: data(),
                        Options :: decode_options(),
                        Fun :: fun((Line) -> Mapped),
                        Line :: csv_line(),
                        Mapped :: term(),
                        Result :: [Mapped].

Successively calls the given function Fun with each CSV line decoded from the raw binary data in RawData or provided by Provider as argument.

Returns a list of the values returned by Fun.

decode_next_line(State0)

-spec decode_next_line(State0) -> Result
                          when
                              State0 :: state(),
                              Result :: end_of_data | {Line, State1},
                              Line :: csv_line(),
                              State1 :: state().

Decodes and returns the next CSV line in the given decoder state, together with an updated state which can be used for further incremental decoding.

If the provider of the decoder state is exhausted, the atom end_of_data is returned instead of a line.

default_decode_options()

-spec default_decode_options() -> decode_options().

Returns the default decode options.

separator: $,
enclosure: $"
quote: enclosure

default_encode_options()

-spec default_encode_options() -> encode_options().

Returns the default encode options.

separator: $,
enclosure: $"
quote: enclosure
enclose: optional
end_of_line: <<"\r\n">>

encode(Lines)

-spec encode(Lines) -> RawData when Lines :: [Line], Line :: csv_line(), RawData :: data().

Equivalent to encode(Lines, default_encode_options()).

encode(Lines, Options)

-spec encode(Lines, Options) -> RawData
                when Lines :: [Line], Line :: csv_line(), Options :: encode_options(), RawData :: data().

Encodes the given CSV data structure into a CSV binary, using the given Options.

flush_provider(Provider)

-spec flush_provider(Provider) -> RawData when Provider :: provider(), RawData :: data().

Flushes and returns all data remaining in the given Provider.

get_binary_provider(Binary)

-spec get_binary_provider(Binary) -> Provider when Binary :: binary(), Provider :: provider().

Equivalent to get_binary_provider(Binary, 1024).

get_binary_provider(Binary, ChunkSize)

-spec get_binary_provider(Binary, ChunkSize) -> Provider
                             when Binary :: binary(), ChunkSize :: pos_integer(), Provider :: provider().

Creates a data provider from the given Binary to supply data in chunks of the given ChunkSize.

This provider can be used in decode_init/1,2. decode_fold/3,4, decode_foreach/2,3, decode_filter/2,3, decode_map/2,3 and decode_filtermap/2,3.

get_file_provider(IoDevice)

-spec get_file_provider(IoDevice) -> Provider
                           when IoDevice :: file:io_device() | io:device(), Provider :: provider().

Equivalent to get_file_provider(IoDevice, 1024).

get_file_provider(IoDevice, ChunkSize)

-spec get_file_provider(IoDevice, ChunkSize) -> Provider
                           when
                               IoDevice :: file:io_device() | io:device(),
                               ChunkSize :: pos_integer(),
                               Provider :: provider().

Creates a data provider from an open file given in IoDevice to supply data in chunks of the given ChunkSize.

The file must have been opened with modes read and binary.

Note that this provider is stateful, because the underlying IoDevice is stateful. This means that reading from the provider changes the state of the IoDevice (namely, advancing the position), and is itself affected by any external changes to the state of the IoDevice.

When the position of the IoDevice is at eof, the provider is exhausted.

The IoDevice is not closed implicitly by the provider, instead the code using this provider is responsible for closing it.

This provider can be used in decode_init/1,2. decode_fold/3,4, decode_foreach/2,3, decode_filter/2,3, decode_map/2,3 and decode_filtermap/2,3.