NAME
   Parse::CSV - Highly flexible CSV parser for large files

SYNOPSIS
     # Simple headerless comma-seperated column parser
     my $simple = Parse::CSV->new(
         file => 'file.csv',
     );

 while ( my $array_ref = $simple->fetch ) {
        # Do something...
     }

   ... or a more complex example...

     # Parse a colon-seperated variables file  from a handle as a hash
     # based on headers from the first line.
     # Then filter, so we emit objects rather than the plain hash.
     my $objects = Parse::CSV->new(
         handle => $io_handle,
         sep_char   => ';',
         names      => 1,
         filter     => sub { My::Object->new( $_ ) },
     );

 while ( my $object = $objects->fetch ) {
         $object->do_something;
     }

DESCRIPTION
   Surely the CPAN doesn't need yet another CSV parsing module.

   Text::CSV_XS is the standard parser for CSV files. It is fast as hell,
   but unfortunately it can be a bit verbose to use.

   A number of other modules have attempted to put usability wrappers
   around this venerable module, but they have all focussed on parsing the
   entire file into memory at once.

   This method is fine unless your CSV files start to get large. Once that
   happens, the only existing option is to fall back on the relatively slow
   and heavyweight XML::SAXDriver::CSV module.

   Parse::CSV fills this functionality gap. It provides a flexible and
   light-weight streaming parser for large, extremely large, or arbitrarily
   large CSV files.

 Main Features
   Stream-Based Parser - All parsing a line at a time.

   Array Mode - Parsing can be done in simple array mode, returning a
   reference to an array if the columns are not named.

   Hash Mode - Parsing can be done in hash mode, putting the data into a
   hash and return a reference to it.

   Filter Capability - All items returned can be passed through a custom
   filter. This filter can either modify the data on the fly, or drop
   records you don't need.

 Writing Filters
   A Parse::CSV filter is a subroutine reference that is passed the raw
   record as $_, and should "return" the alternative or modified record to
   return to the user.

   The null filter (does not modify or drop any records) looks like the
   following.

     sub { $_ };

   A filter which reversed the order of the columns (assuming they are
   passed as an array) might look like the following.

     sub { return [ reverse @$_ ] };

   To drop the record, you should return "undef" from the filter. The
   parser will then keep pulling and parsing new records until one passes
   the filter.

     # Only keep records where foo is true
     sub { $_->{foo} ? $_ : undef }

   To signal an error, throw an exception

     sub {
         $_->{foo} =~ /bar/ or die "Assumption failed";
         return $_;
     }

METHODS
 new
   The "new" constructor creates and initialise a new CSV parser.

   It takes a number of params.

   To specify the CSV data source, you should provide either the "file"
   param, which should be the name of the file to read, or the "handle"
   param, which should be a file handle to read instead.

   The actual parsing is done using Text::CSV_XS. Any of it's
   constructor/parsing params can also be provided to this "new" method,
   and they will be passed on.

   Alternatively, they can be passed as a single "HASH" reference as the
   "csv_attr" param. For example:

     $parser = Parse::CSV->new(
         file     => 'file.csv',
         csv_attr => {
             sep_char   => ';',
             quote_char => "'",
         },
     );

   An optional "names" param can be provided, which should be an array
   reference containing the names of the columns in the CSV file.

     $parser = Parse::CSV->new(
         file  => 'file.csv',
         names => [ 'col1', 'col2', 'col3' ],
     );

   If the "names" param is provided, the parser will map the columns to a
   hash where the keys are the field names provided, and the values are the
   values found in the CSV file.

   If the "names" param is not provided, the parser will return simple
   array references of the columns.

   If the "names" param is true and not a reference, the names will be
   automatically determined by reading the first line of the CSV file and
   using those values as the field names.

   The optional "filter" param will be used to filter the records if
   provided. It should be a "CODE" reference or any otherwise callable
   scalar, and each value parsed (either array reference or hash reference)
   will be passed to the filter to be changed or converted into an object,
   or whatever you wish.

   Returns a new Parse::CSV object, or throws an exception (dies) on error.

 fetch
   Once a Parse::CSV object has been created, the "fetch" method is used to
   parse and return the next value from the CSV file.

   Returns an "ARRAY", "HASH" or the output of the filter, based on the
   configuration of the object, or "undef" in a variety of situations.

   Returning "undef" means either some part of the parsing and filtering
   process has resulted in an error, or that the end of file has been
   reached.

   On receiving "undef", you should the "errstr" method. If it is a null
   string you have reached the end of file. Otherwise the error message
   will be returned. Thus, the basic usage of Parse::CSV will look like the
   following.

     my $parser = Parse::CSV->new(
         file => 'file.csv',
         );
     while ( my $value = $parser->fetch ) {
         # Do something...
     }
     if ( $parser->errstr ) {
         # Handle errors...
     }

 row
   The "row" method returns the current row of the CSV file.

   This is a one-based count, so when you first create the parser, the
   value of "row" will be zero (unless you are using "names" on automatic
   in which case it will be 1).

 combine
     $status = $csv->combine(@columns);

   The "combine" method is provided as a convenience, and is passed through
   to the underlying Text::CSV_XS object.

 string
     $line = $csv->string;

   The "string" method is provided as a convenience, and is passed through
   to the underlying Text::CSV_XS object.

 print
     $status = $csv->print($io, $columns);

   The "print" method is provided as a convenience, and is passed through
   to the underlying Text::CSV_XS object.

 fields
     @fields = $csv->fields;

   The "fields" method is provided as a convenience, and is passed through
   to the underlying Text::CSV_XS object. It shows the actual row as an
   array.

 names
     # Get the current column names in use
     my @names = $csv->names;

 # Change the column names on the fly mid stream
     $csv->names( 'fn1', 'fn2' );

   The "names" method gets or sets the column name mapping for the parser.

 errstr
   On error, the "errstr" method returns the error that occured.

   If the last action was NOT an error, returns the null string ''.

SUPPORT
   Bugs should always be reported via the CPAN bug tracker at

   <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Parse-CSV>

   For other issues, or commercial enhancement or support, contact the
   author.

AUTHORS
   Adam Kennedy <[email protected]>

CONTRIBUTORS
   Uwe Sarnowski <[email protected]>

SEE ALSO
   Text::CSV_XS, <http://ali.as/>

COPYRIGHT
   Copyright 2006 - 2011 Adam Kennedy.

   This program is free software; you can redistribute it and/or modify it
   under the same terms as Perl itself.

   The full text of the license can be found in the LICENSE file included
   with this module.

You are viewing proxied material from ftp.icm.edu.pl. The copyright of proxied material belongs to its original authors. Any comments or complaints in relation to proxied material should be directed to the original authors of the content concerned. Please see the disclaimer for more details.