README

csv.erl
=======

csv.erl is the erlang library for csv records manipulating (rfc4180).


Build
==========

make && make test


API
==========

make/2
    Make a CSV text record from supplied fields.

put_rec/3
    Put a CSV record into a Fio.

put_recs/3
    Put all CSV records into a Fio.

put_frecs/3
    Put all CSV records into a file. Open a file with [append] modes.

put_frecs/4
    Put all CSV records into a file. Open a file with supplied modes.

parse/2
    Parse a CSV text record into fields.

get_rec/2
    Get a CSV record from a Fio.

get_recs/2
    Get all CSV records from a Fio.

get_frecs/2
    Get all CSV records from a file.

See details in doc/index.html (created by "make doc" command).
All functions get a csv record as the first argument. It contain the next fields:

sep
    a field separator
    "," - by default
quote
    a quote construct
    "\"" - by default
eor
    an end of record construct
    "\n" - by default
cb_make
    a callback for make/2.
    undefined - by default
cb_parse
    a callback for parse/2 (used by get_rec/2, get_recs/2, get_frecs/2).
    undefined - by default


Callbacks
==========

A callback take two arguments:

Opts
    csv record (see csv.hrl).
Rec
    a record.

And must return:

{ok, Rec_new}
    a converted record.
{error, Reason}
    an error.

make/2 callback is called before the main make/2 code and must convert a user
supplied data to a list of fields with which make/2 works.
For a make/2 callback, Rec is a user supplied record from a second make/2
argument. Rec_new for a make/2 callback is a list of fields to make a CSV
record from.

parse/2 callback is called after the main parse/2 code and must convert a list
of fields to a user data format.
For a parse/2 callback, Rec is a list of fields we parsed from a user supplied
text from a second parse/2 argument (a CSV text record). Rec_new for a parse/2
callback is a parsed record in a user format.


Examples
==========

The example csv file used in examples:

one,11,info1
two,22,info2

Make a csv record from fields:

1> csv:make(#csv{}, [1,2,3]).
{ok, "1,2,3\n"}

Make a csv record from fields with ; as a separator:

1> csv:make(#csv{sep = ";"}, [1,2,3]).
{ok, "1;2;3\n"}

Make a csv record from a tuple:

1> F = fun(_Opts, Rec) -> {ok, tuple_to_list(Rec)} end.
#Fun<erl_eval.12.80484245>
2> csv:make(#csv{cb_make=F}, {1,2,3}).
{ok,"1,2,3\n"}

Append csv records into a file:

1> csv:put_frecs(#csv{}, [[1, 2, "field"], [yet, "another", row]], "testfile").
ok


Read all records from a file:

1> csv:get_frecs(#csv{}, "ex.csv").
{ok,[["one","11","info1"],["two","22","info2"]]}

Read all records as tuples from a file:

1> F = fun(_Opts, Rec) -> {ok, list_to_tuple(Rec)} end.
#Fun<erl_eval.12.80484245>
2> csv:get_frecs(#csv{cb_parse=F}, "ex.csv").
{ok,[{"one","11","info1"},{"two","22","info2"}]}

Read all records as records from a file:

13> F = fun(_Opts, Rec) -> csv:cb_list_to_rec(Rec, my_rec) end. 
#Fun<erl_eval.12.80484245>
14> csv:get_frecs(#csv{cb_parse=F}, "ex.csv").            
{ok,[{my_rec, "one","11","info1"},
     {my_rec, "two","22","info2"}]}


Write records to a file(convert each field from unicode to utf8):

25> Ff = fun(Field) when is_list(Field) ->
25>   Bin = unicode:characters_to_binary(Field),
25>   binary_to_list(Bin);
25> (Field) ->
25>   Field
25> end.
#Fun<erl_eval.6.50752066>
26> Fr = fun(_Opts, Rec) ->
26>   {ok, lists:map(Ff, Rec)}
26> end.
#Fun<erl_eval.12.50752066>
27> csv:put_frecs(#csv{cb_make=Fr}, [["Тест", 1233]], "test.csv").
ok
28> csv:put_frecs(#csv{cb_make=Fr}, [["我", 123]], "test.csv").
ok