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 = Text::CSV->version();
This function may be called as a class or an object method. It returns the current module version.
 $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.
 $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.
 $line = $csv->string();
This object function returns the input to `parse()' or the resultant CSV string of `combine()', whichever was called more recently.
 $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.
 @columns = $csv->fields();
This object function returns the input to `combine()' or the resultant decomposed fields of `parse()', whichever was called more recently.
 $status = $csv->status();
This object function returns success (or failure) of `combine()' or `parse()', whichever was called more recently.
 $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. Allowable characters within a CSV field include 0x09 (tab) and the inclusive range of 0x20 (space) through 0x7E (tilde). A field within CSV may be surrounded by double-quotes. A field within CSV must be surrounded by double-quotes to contain a comma. A field within CSV must be surrounded by double-quotes to contain an embedded double-quote, represented by a pair of consecutive double-quotes. A CSV string may be terminated by 0x0A (line feed) or by 0x0D,0x0A (carriage return, line feed).

AUTHOR
Alan Citterman <alan@mfgrtl.com>

SEE ALSO
perl(1)