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

 $csv = Text::CSV->setDelimiter(';');  # define the delimiter

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

new

 $csv->setDelimiter(';');

This function define a delimiter to use. By default, the delimiter is ',' (comma)

new

 $delimiter = $csv->getDelimiter();

This function returns the delimiter in use by the 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"';
  # By default, the delimiter is ',', you don't need to change
  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";
  }

  $csv->setDelimiter(';');
  my $sample_new_input_string = '"I said; ""Hi!""";Yes;"";2.34;;"1.09"';
  if ($csv->parse($sample_new_input_string)) {
    my @fieldN = $csv->fields;
    my $countN = 0;
    for my $column (@fieldN) {
      print ++$count, " => ", $column, "\n";
    }
    print "\n";
  } else {
    my $err = $csv->error_input;
    print "parse() 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 0xFF (ÿ).

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

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

REFERENCES

http://search.cpan.org/~alancitt/Text-CSV-0.01/CSV.pm

THANKS

Many thanks to Alan Citterman, but I didn't found it to continue the original version.

AUTHOR

Eduardo Rangel Thompson <erangel@gmail.com>

SEE ALSO

perl(1), TEXT::CSV