CSV(3) User Contributed Perl Documentation CSV(3)

NAME

Text::CSV - comma-separated values manipulation routines

SYNOPSIS

use Text::CSV;

$version = Text::CSV->version(); # get the module version

$csv = Text::CSV->new(); # 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

DESCRIPTION

Text::CSV provides facilities for the composition and decomposition of

comma-separated values. An instance of the Text::CSV class can combine

fields into a CSV string and parse a CSV string into fields.

FUNCTIONS

version

$version = Text::CSV->version();

This function may be called as a class or an object method. It returns

the current module version.

new

$csv = Text::CSV->new();

This function may be called as a class or an object method. It returns

a reference to a newly created Text::CSV object.

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

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.

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;

my $csv = Text::CSV->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, "\n";

}

print "\n";

} else {

my $err = $csv->error_input;

print "parse() failed on argument: ", $err, "\n";

}

my @sample_input_fields = ('You said, "Hello!"',

5.67,

'Surely',

'',

'3.14159');

if ($csv->combine(@sample_input_fields)) {

my $string = $csv->string;

print $string, "\n";

} else {

my $err = $csv->error_input;

print "combine() failed on argument: ", $err, "\n";

}

CAVEATS

This module is based upon a working definition of CSV format 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).

2 A field within CSV may be surrounded by double-quotes.

3 A field within CSV must be surrounded by double-quotes to contain a

comma.

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.

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>