-spec decode(binary() | iolist()) -> [[binary()]] | [#{binary() => binary()}].

Decode a CSV binary or iolist to a list of rows.

By default each row is a list of binary fields. With the headers option, the first row is used as column names and each subsequent row is decoded as a map. Raises unterminated_quoted_field or duplicate_header on invalid input.

-spec decode(binary() | iolist(), decode_opts()) -> [[binary()]] | [map()].

Decode a CSV binary or iolist to a list of rows, with options. Raises Reason::decode_error() on invalid input.

-spec encode([[term()]] | [map()]) -> binary().

Encode a list of rows to a CSV binary.

Each row is a list of fields (binaries, atoms, integers, or floats). Fields containing the delimiter, a double quote, or a line break are quoted per RFC 4180, with embedded quotes doubled.

-spec encode([[term()]] | [map()], encode_opts()) -> binary().

Encode a list of rows to a CSV binary, with options.

With the headers option, Data is a list of maps: the first map's keys become the header row (in iteration order), and each map is encoded as a row in that column order.

-spec read_file(file:name_all()) -> [[binary()]] | [map()].

Read Filename and decode its contents as CSV.

Raises Reason::decode_error() if the file's contents aren't valid CSV, or a binary "Filename: Reason" message (see file:format_error/1) if the file can't be read.

Example

1> glazer_csv:read_file("data.csv").
[[<<"a">>,<<"b">>],[<<"1">>,<<"2">>]]

-spec read_file(file:name_all(), decode_opts()) -> [[binary()]] | [map()].

Read Filename and decode its contents as CSV, with decode options (see decode/2).

-spec stream_decoder() -> stream_decoder().

Create a new incremental decoder for feeding CSV in chunks (e.g. from a socket or file), useful when the whole input isn't available up front.

Each complete row is decoded as soon as its terminating line break is seen, via decode/2 on that single row. Only the row boundary detection is incremental — a small byte-scanner tracks whether the cursor is inside a quoted field across chunks, so that \n/\r\n inside quoted fields doesn't end a row.

With the headers option, the first complete row is captured as the header and used to decode every subsequent row as a map; no row is emitted for the header itself.

Example

1> D0 = glazer_csv:stream_decoder(),
2> {Rows1, D1} = glazer_csv:stream_feed(D0, <<"a,b\n1,2\n3,">>),
3> Rows1.
[[<<"a">>,<<"b">>],[<<"1">>,<<"2">>]]
4> {Rows2, D2} = glazer_csv:stream_feed(D1, <<"4\n">>),
5> Rows2.
[[<<"3">>,<<"4">>]]
6> glazer_csv:stream_eof(D2).
{ok, []}

-spec stream_decoder(decode_opts()) -> stream_decoder().

Create a new incremental CSV decoder, passing Opts through to every decode/2 call.

-spec stream_eof(stream_decoder()) -> {ok, [[binary()]] | [map()]} | {error, term()}.

Signal end-of-stream: decode any remaining buffered bytes as a final row (useful when the input doesn't end with a trailing line break).

Returns {ok, Rows} with zero or one trailing row, or {error, Reason} if the remaining bytes don't form a valid row.

Example

1> D0 = glazer_csv:stream_decoder(),
2> {Rows1, D1} = glazer_csv:stream_feed(D0, <<"a,b\n1,2">>),
3> Rows1.
[[<<"a">>,<<"b">>]]
4> glazer_csv:stream_eof(D1).
{ok, [[<<"1">>,<<"2">>]]}

-spec stream_feed(stream_decoder(), binary() | iolist()) -> {[[binary()]] | [map()], stream_decoder()}.

Feed a chunk of bytes into the decoder, returning any complete CSV rows found so far (in order) along with the updated decoder.

Raises the same exceptions as decode/2 if a row that the scanner deemed complete fails to decode.

Example

loop(Socket, D0) ->
  case gen_tcp:recv(Socket, 0) of
    {ok, Chunk} ->
      {Rows, D1} = glazer_csv:stream_feed(D0, Chunk),
      handle_rows(Rows),
      loop(Socket, D1);
    {error, closed} ->
      case glazer_csv:stream_eof(D0) of
        {ok, Trailing}  -> handle_rows(Trailing);
        {error, Reason} -> handle_truncated_stream(Reason)
      end
  end.

-spec try_decode(binary() | iolist()) -> {ok, [[binary()]]} | {error, decode_error()}.

Decode a CSV binary or iolist, returning {ok, Rows} or {error, Reason} instead of raising, where Reason is a decode_error().

-spec try_decode(binary() | iolist(), decode_opts()) ->
                    {ok, [[binary()]] | [map()]} | {error, decode_error()}.

Decode a CSV binary or iolist with options, returning {ok, Rows} or {error, Reason} instead of raising, where Reason is a decode_error().

-spec write_file(file:name_all(), [[term()]] | [map()]) -> ok.

Encode Data to CSV and write it to Filename, overwriting any existing file.

Raises a binary "Filename: Reason" message (see file:format_error/1) if the file can't be written.

Example

1> glazer_csv:write_file("data.csv", [[<<"a">>,<<"b">>],[1,2]]).
ok

-spec write_file(file:name_all(), [[term()]] | [map()], encode_opts()) -> ok.

Encode Data to CSV with encode options (see encode/2) and write it to Filename, overwriting any existing file.