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>

SEE ALSO

perl(1)