-spec decode(binary() | iolist()) -> csv_result().

Decode a CSV binary or iolist.

Returns a csv_result/0 map #{headers => nil, data => Rows} where Rows is a list of rows, each row a list of binary fields. With the headers option the first row is captured as column names in headers instead of appearing in data. Raises Reason :: t:decode_error/0 on invalid input.

Examples

1> glazer_csv:decode(<<"a,b\n1,2\n3,4\n">>).
#{headers => nil, data => [[<<"a">>,<<"b">>],[<<"1">>,<<"2">>],[<<"3">>,<<"4">>]]}

2> glazer_csv:decode(<<>>).
#{headers => nil, data => []}

3> glazer_csv:decode(<<"\"hello, world\",42\n">>).
#{headers => nil, data => [[<<"hello, world">>,<<"42">>]]}

-spec decode(binary() | iolist(), decode_opts()) -> csv_result().

Decode a CSV binary or iolist with options (see decode_opts/0). Returns a csv_result/0. Raises Reason :: t:decode_error/0 on invalid input.

Examples

%% First row as binary column names
1> glazer_csv:decode(<<"name,age\nAlice,30\nBob,25\n">>, [headers]).
#{headers => [<<"name">>,<<"age">>],
  data    => [[<<"Alice">>,<<"30">>],[<<"Bob">>,<<"25">>]]}

%% Explicit column names — no header row expected in the data
2> glazer_csv:decode(<<"Alice,30\n">>, [{headers, [name, age]}, {return, map}]).
#{headers => [name,age], data => [#{age => <<"30">>, name => <<"Alice">>}]}

%% Per-column type conversion
3> glazer_csv:decode(<<"Alice,30\n">>, [{fields, [binary, integer]}]).
#{headers => nil, data => [[<<"Alice">>,30]]}

%% Semi-colon delimiter, skip first 2 rows, limit to 3
4> glazer_csv:decode(<<"h1;h2\nr1a;r1b\nr2a;r2b\nr3a;r3b\nr4a;r4b\n">>,
                     [{delimiter, $;}, headers, {skip, 1}, {limit, 2}]).
#{headers => [<<"h1">>,<<"h2">>],
  data    => [[<<"r2a">>,<<"r2b">>],[<<"r3a">>,<<"r3b">>]]}

%% Rows as maps with atom keys
5> glazer_csv:decode(<<"a,b\n1,2\n">>, [{headers, existing_atom}, {return, map}]).
#{headers => [a,b], data => [#{a => <<"1">>, b => <<"2">>}]}

%% Rows as tuples
6> glazer_csv:decode(<<"a,b\n1,2\n">>, [{return, tuple}]).
#{headers => nil, data => [{<<"a">>,<<"b">>},{<<"1">>,<<"2">>}]}

-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.

Raises {encode_error, {Msg, Term}} if any row or field cannot be encoded (e.g. an improper list, a map field, or a tuple field).

Examples

1> glazer_csv:encode([[<<"a">>, <<"b">>], [1, 2]]).
<<"a,b\r\n1,2\r\n">>

2> glazer_csv:encode([[<<"hello, world">>, <<"say \"hi\"">>]]).
<<"\"hello, world\",\"say \"\"hi\"\"\"\r\n">>

3> glazer_csv:encode([]).
<<>>

4> glazer_csv:encode([[<<"a">>|<<"b">>]]).
** exception error: {encode_error,{<<"cannot encode improper list as CSV row">>,<<"b">>}}

-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.

Raises {encode_error, {Msg, Term}} if any row or field cannot be encoded.

Examples

%% Maps to CSV with a header row
1> glazer_csv:encode([#{<<"name">> => <<"Alice">>, <<"age">> => 30}], [headers]).
<<"age,name\r\n30,Alice\r\n">>

%% Maps to CSV with an explicit column order
2> glazer_csv:encode([#{<<"name">> => <<"Alice">>, <<"age">> => 30}],
                     [{headers, [<<"name">>, <<"age">>]}]).
<<"name,age\r\nAlice,30\r\n">>

%% Semicolon delimiter with LF line endings
3> glazer_csv:encode([[<<"a">>, <<"b">>], [1, 2]],
                     [{delimiter, $;}, {line_ending, lf}]).
<<"a;b\n1;2\n">>

-spec read_file(file:name_all()) -> csv_result().

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.

Examples

%% File contains: name,age\nAlice,30\n
1> glazer_csv:read_file("data.csv").
#{headers => nil, data => [[<<"name">>,<<"age">>],[<<"Alice">>,<<"30">>]]}

2> glazer_csv:read_file("missing.csv").
** exception error: <<"missing.csv: no such file or directory">>

-spec read_file(file:name_all(), decode_opts()) -> csv_result().

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

Examples

%% File contains: name,age\nAlice,30\nBob,25\n
1> glazer_csv:read_file("data.csv", [headers, {return, map}]).
#{headers => [<<"name">>,<<"age">>],
  data    => [#{<<"age">> => <<"30">>,  <<"name">> => <<"Alice">>},
              #{<<"age">> => <<"25">>,  <<"name">> => <<"Bob">>}]}

2> glazer_csv:read_file("data.csv", [headers, {fields, [binary, integer]}]).
#{headers => [<<"name">>,<<"age">>], data => [[<<"Alice">>,30],[<<"Bob">>,25]]}

-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; no row is emitted for it. Passes the same options as decode/2 to every row decode internally (see stream_decoder/1 to supply options).

Examples

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

2> {Rows2, D2} = glazer_csv:stream_feed(D1, <<"4\n">>),
   Rows2.
[[<<"3">>,<<"4">>]]

3> glazer_csv:stream_eof(D2).
{ok, []}

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

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

All options from decode/2 are accepted except {skip, ...} and {limit, ...}, which are ignored in streaming mode (the caller controls which rows to process by consuming the output of stream_feed/2).

When {headers, [List]} is given, the explicit header names are pre-populated and no header row is consumed from the stream.

Examples

%% Headers option: first row captured, data rows returned as field lists
1> D0 = glazer_csv:stream_decoder([headers]),
   {Rows, D1} = glazer_csv:stream_feed(D0, <<"name,age\nAlice,30\n">>),
   Rows.
[[<<"Alice">>,<<"30">>]]

%% Explicit headers + map output
2> D0 = glazer_csv:stream_decoder([{headers, [name, age]}, {return, map}]),
   {Rows, _D1} = glazer_csv:stream_feed(D0, <<"Alice,30\n">>),
   Rows.
[#{age => <<"30">>, name => <<"Alice">>}]

%% Semicolon delimiter
3> D0 = glazer_csv:stream_decoder([{delimiter, $;}]),
   {Rows, _D1} = glazer_csv:stream_feed(D0, <<"a;b\n1;2\n">>),
   Rows.
[[<<"a">>,<<"b">>],[<<"1">>,<<"2">>]]

-spec stream_eof(stream_decoder()) -> {ok, [[term()]] | [tuple()] | [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.

Examples

%% Input without a trailing newline
1> D0 = glazer_csv:stream_decoder(),
   {Rows1, D1} = glazer_csv:stream_feed(D0, <<"a,b\n1,2">>),
   Rows1.
[[<<"a">>,<<"b">>]]

2> glazer_csv:stream_eof(D1).
{ok, [[<<"1">>,<<"2">>]]}

%% Input ending with a newline — nothing left at EOF
3> D0 = glazer_csv:stream_decoder(),
   {_Rows, D1} = glazer_csv:stream_feed(D0, <<"a,b\n">>),
   glazer_csv:stream_eof(D1).
{ok, []}

%% Unterminated quoted field surfaces here
4> D0 = glazer_csv:stream_decoder(),
   {[], D1} = glazer_csv:stream_feed(D0, <<"\"unterminated">>),
   glazer_csv:stream_eof(D1).
{error, unterminated_quoted_field}

-spec stream_feed(stream_decoder(), binary() | iolist()) ->
                     {[[term()]] | [tuple()] | [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.

Examples

%% Rows split across two feed calls
1> D0 = glazer_csv:stream_decoder(),
   {Rows1, D1} = glazer_csv:stream_feed(D0, <<"a,b\n1,">>),
   Rows1.
[[<<"a">>,<<"b">>]]

2> {Rows2, D2} = glazer_csv:stream_feed(D1, <<"2\n">>),
   Rows2.
[[<<"1">>,<<"2">>]]

3> glazer_csv:stream_eof(D2).
{ok, []}

%% Typical socket-reading loop
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, csv_result()} | {error, decode_error()}.

Decode a CSV binary or iolist, returning {ok, Result} or {error, Reason} instead of raising. Result is a csv_result/0; Reason is a decode_error/0.

Examples

1> glazer_csv:try_decode(<<"a,b\n1,2\n">>).
{ok, #{headers => nil, data => [[<<"a">>,<<"b">>],[<<"1">>,<<"2">>]]}}

2> glazer_csv:try_decode(<<"\"unterminated">>).
{error, unterminated_quoted_field}

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

Decode a CSV binary or iolist with options (see decode_opts/0), returning {ok, Result} or {error, Reason} instead of raising. Result is a csv_result/0; Reason is a decode_error/0.

Examples

1> glazer_csv:try_decode(<<"name,age\nAlice,30\n">>, [headers]).
{ok, #{headers => [<<"name">>,<<"age">>], data => [[<<"Alice">>,<<"30">>]]}}

2> glazer_csv:try_decode(<<"x">>,
                         [{fields, [#{type => integer, on_failure => raise}]}]).
{error, {invalid_field_value, 1, 1}}

-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.

Examples

1> glazer_csv:write_file("out.csv", [[<<"name">>,<<"age">>],[<<"Alice">>,30]]).
ok

2> glazer_csv:write_file("/read-only/out.csv", []).
** exception error: <<"/read-only/out.csv: permission denied">>

-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.

Examples

%% Write maps as CSV with a header row and LF line endings
1> glazer_csv:write_file("out.csv",
                         [#{<<"name">> => <<"Alice">>, <<"score">> => 99}],
                         [headers, {line_ending, lf}]).
ok

%% Write with a semicolon delimiter
2> glazer_csv:write_file("out.csv",
                         [[<<"a">>, <<"b">>], [1, 2]],
                         [{delimiter, $;}]).
ok