csv_xs(3)
NAME
Text::CSV_XS - comma-separated values manipulation rou
tines
SYNOPSIS
use Text::CSV_XS;
$csv = Text::CSV_XS->new(); # create a new object
$csv = Text::CSV_XS->new(attr); # create a new object
$status = $csv->combine(@columns); # combine columns
into a string
$line = $csv->string(); # get the combined
string
$status = $csv->parse($line); # parse a CSV
string into fields
@columns = $csv->fields(); # get the parsed
fields
$status = $csv->status(); # get the most recent status
$bad_argument = $csv->error_input(); # get the most recent bad argument
$status = $csv->print($io, $columns); # Write an array of
fields immediately
# to a file $io
$columns = $csv->getline($io); # Read a line from
file $io, parse it
# and return an array ref of fields
$csv->types(@t_array); # Set column types
DESCRIPTION
Text::CSV_XS provides facilities for the composition and
decomposition of comma-separated values. An instance of
the Text::CSV_XS class can combine fields into a CSV
string and parse a CSV string into fields.
FUNCTIONS
- version()
- (Class method) Returns the current module version.
- new(attr)
- (Class method) Returns a new instance of Text::CSV_XS.
The objects attributes are described by the (optional)
hash ref "attr". Currently the following attributes
are available: - quote_char
The char used for quoting fields containing
blanks, by default the double quote character
("""). A value of undef suppresses quote
chars. (For simple cases only). - eol An end-of-line string to add to rows, usually
- "undef" (nothing, default), " 12" (Line Feed)
or " 15 12" (Carriage Return, Line Feed) - escape_char
- The char used for escaping certain characters
inside quoted fields, by default the same
character. (""") - sep_char
- The char used for separating fields, by
default a comme. (",") - binary If this attribute is TRUE, you may use binary
- characters in quoted fields, including line
feeds, carriage returns and NUL bytes. (The
latter must be escaped as ""0".) By default
this feature is off. - types A set of column types; this attribute is imme
- diately passed to the types method below. You
must not set this attribute otherwise, except
for using the types method. For details see
the description of the types method below. - always_quote
- By default the generated fields are quoted
only, if they need to, for example, if they
contain the separator. If you set this
attribute to a TRUE value, then all fields
will be quoted. This is typically easier to
handle in external applications. (Poor crea
tures who aren't using Text::CSV_XS. :-) - To sum it up,
$csv = Text::CSV_XS->new();- is equivalent to
$csv = Text::CSV_XS->new({'quote_char' => '"',
'escape_char' => '"',
'sep_char' => ',',
'binary' => 0- });
- combine
- $status = $csv->combine(@columns);
- This object function constructs a CSV string from the
arguments, returning success or failure. Failure can
result from lack of arguments or an argument contain
ing an invalid character. Upon success, "string()"
can be called to retrieve the resultant CSV string.
Upon failure, the value returned by "string()" is
undefined and "error_input()" can be called to
retrieve an invalid argument. - $status = $csv->print($io, $columns);
- Similar to combine, but it expects an array ref as
input (not an array!) and the resulting string is not
really created, but immediately written to the $io
object, typically an IO handle or any other object
that offers a print method. Note, this implies that
the following is wrong:
open(FILE, ">whatever");
$status = $csv->print(ILE, $columns);- The glob "ILE" is not an object, thus it doesn't
have a print method. The solution is to use an
IO::File object or to hide the glob behind an IO::Wrap
object. See IO::File(3) and IO::Wrap(3) for details. - For performance reasons the print method doesn't cre
ate a result string. In particular the
$csv->string(), $csv->status(), $csv-fields()> and $csv->error_input() methods are meaningless after exe cuting this method. - string
- $line = $csv->string();
- This object function returns the input to "parse()" or
the resultant CSV string of "combine()", whichever was
called more recently. - parse
- $status = $csv->parse($line);
- This object function decomposes a CSV string into
fields, returning success or failure. Failure can
result from a lack of argument or the given CSV string
is improperly formatted. Upon success, "fields()" can
be called to retrieve the decomposed fields . Upon
failure, the value returned by "fields()" is undefined
and "error_input()" can be called to retrieve the
invalid argument. - You may use the types() method for setting column
types. See the description below. - getline
- $columns = $csv->getline($io);
- This is the counterpart to print, like parse is the
counterpart to combine: It reads a row from the IO
object $io using $io->getline() and parses this row into an array ref. This array ref is returned by the
function or undef for failure. - The $csv->string(), $csv->fields() and $csv->status() methods are meaningless, again.
- types
- $csv->types(@tref);
- This method is used to force that columns are of a
given type. For example, if you have an integer col
umn, two double columns and a string column, then you
might do a
$csv->types([Text::CSV_XS::IV(),Text::CSV_XS::NV(),
Text::CSV_XS::NV(),
Text::CSV_XS::PV()]);- Column types are used only for decoding columns, in
other words by the parse() and getline() methods. - You can unset column types by doing a
$csv->types(undef);- or fetch the current type settings with
$types = $csv->types();- fields
- @columns = $csv->fields();
- This object function returns the input to "combine()"
or the resultant decomposed fields of "parse()",
whichever was called more recently. - status
- $status = $csv->status();
- This object function returns success (or failure) of
"combine()" or "parse()", whichever was called more
recently. - error_input
- $bad_argument = $csv->error_input();
- This object function returns the erroneous argument
(if it exists) of "combine()" or "parse()", whichever
was called more recently.
EXAMPLE
require Text::CSV_XS;
my $csv = Text::CSV_XS->new;
- my $column = '';
my $sample_input_string = '"I said, - ""Hi!""",Yes,"",2.34,,"1.09"';
if ($csv->parse($sample_input_string)) { - my @field = $csv->fields;
my $count = 0;
for $column (@field) {print ++$count, " => ", $column, "0; - }
print "0; - } else {
- my $err = $csv->error_input;
print "parse() failed on argument: ", $err, "0; - }
- my @sample_input_fields = ('You said, "Hello!"',
- 5.67,
'Surely',
'',
'3.14159'); - if ($csv->combine(@sample_input_fields)) {
- my $string = $csv->string;
print $string, "0; - } else {
- my $err = $csv->error_input;
print "combine() failed on argument: ", $err, "0; - }
CAVEATS
This module is based upon a working definition of CSV for
mat which may not be the most general.
- 1 Allowable characters within a CSV field include 0x09
- (tab) and the inclusive range of 0x20 (space) through
0x7E (tilde). In binary mode all characters are
accepted, at least in quoted fields: - 2 A field within CSV may be surrounded by double-quotes.
- (The quote char)
- 3 A field within CSV must be surrounded by double-quotes
- to contain a comma. (The separator char)
- 4 A field within CSV must be surrounded by double-quotes
- to contain an embedded double-quote, represented by a
pair of consecutive double-quotes. In binary mode you
may additionally use the sequence ""0" for representa
tion of a NUL byte. - 5 A CSV string may be terminated by 0x0A (line feed) or
- by 0x0D,0x0A (carriage return, line feed).
AUTHOR
Alan Citterman <alan@mfgrtl.com> wrote the original Perl
module. Please don't send mail concerning Text::CSV_XS to
Alan, as he's not involved in the C part which is now the
main part of the module.
Jochen Wiedmann <joe@ispsoft.de> rewrote the encoding and
decoding in C by implementing a simple finite-state
machine and added the variable quote, escape and separator
characters, the binary mode and the print and getline
methods.