Re: Low-threshold function in Text::CSV_XS

[Tux]

Thanks for all the feedback so far. What I have created so far is this:

csv

This is an high-level funtion that aims at simple interfaces. It can be used to read/parse a CSV file or stream (the default behavior) or to produce a file or write to a stream (define the out attribute). It returns an array reference on parsing (or undef on fail) or the numeric value of "error_diag" on writing. When this function fails you can get to the error using the class call to "error_diag"

 my $aoa = csv (in => "test.csv") or
     die Text::CSV_XS->error_diag;

This function takes the arguments as key-value pair. It can be passed as a list or as an anonymous hash:

 my $aoa = csv (  in => "test.csv", sep_char => ";");
 my $aoh = csv ({ in => $fh, headers => "auto" });

The arguments passed consist of two parts: the arguments to "csv" itself and the optional attributes to the CSV object used inside the function as enumerated and explained in "new".

If not overridden, the default options used for CSV are

 auto_diag => 1
 binary    => 1

in

Specify the source. This can be a filename (which should exist), a file handle or a CSV structure (when using "out").

 my $aoa = csv (in => "file.csv");

 open my $fh, "<", "file.csv";
 my $aoa = csv (in => $fh);

 my $csv = [ [qw( Foo Bar )], [ 1, 2 ], [ 2, 3 ]];
 my $err = csv (in => $csv, out => "file.csv");

out

In output mode, the default CSV options when producing CSV are

 eol       => "\r\n"

encoding

If passed, it should be an encoding accepted by the :encoding() option to open. There is no default value.

headers

If this attribute is not given, the default behavior is to produce an array of arrays.

If headers is given, it should be either an anonymous list of column names or a flag: auto or skip. When skip is used, the header will not be included in the output.

 my $aoa = csv (in => $fh, headers => "skip");

If auto is used, the first line of the CSV source will be read as the list of field headers and used to produce an array of hashes.

 my $aoh = csv (in => $fh, headers => "auto");

If headers is an anonymous list, it will be used instead

 my $aoh = csv (in => $fh, headers => [qw( Foo Bar )]);

fragment

Only output the fragment as defined in de "fragment" method.

Combining all of them could give something like

 my $aoh = csv (
     in       => "test.txt",
     encoding => "utf-8",
     headers  => "auto",
     sep_char => "|",
     fragment => "row=3;6-9;15-*",
     );
 say $aoh->[15]{Foo};