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)