Main Features

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 returning 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 no-op filter (does not modify or drop any records) would look like the following.

  sub { $_ }

A filter that reversed the order of the columns (assuming the parser is in array mode) might look like the following.

  sub { [ reverse @$_ ] }

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

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

To signal an error, throw an exception

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

Feel free to modify $_ as a side-effect of your filter routine - this will have no effect on anything.

new

"file"

"handle"

To specify the CSV data source, 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.

"csv_attr"

Any parameter for Text::CSV_XS's constructor can also be provided to this "new" method, and they will be passed on to it. 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 => "'",
      },
  );
    

"names"

An optional "names" param can be provided, which should either be an array reference containing the names of the columns:

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

or a true value that's not a reference, indicating that the column names will be read from the first line of the input:

  $parser = Parse::CSV->new(
      file  => 'file.csv',
      names => 1,
  );
    

If the "names" param is provided, the parser will map each line 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, treating them just like all the other rows in the file.

If your CSV file has (or might have) a <Byte-Order Mark|https://en.wikipedia.org/wiki/Byte_order_mark>, you must use the "names" functionality, because this lets us call the "header" method of "Text::CSV_XS", which is the only place the BOM is handled in that module.

"filter"

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 available to the filter as $_ to be changed or converted into an object, or whatever you wish. See the "Writing Filters" section for more details.

fetch

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 check the "errstr" method. If it is an empty 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...
  }

NOTE: currently the "fields" and "string" methods can be used to access the most recently-read row (as an array ref or a formatted string) after using "/fetch". However, this contradicts the documentation for Text::CSV_XS, which says those methods should be "meaningless" after calling "getline" (which "fetch()" internally uses to read the input). Keeping the current behavior also incurs a speed & memory penalty. Therefore, relying on "fields" and "string" to return the current data after "fetch()" is deprecated and will (probably) be removed in a future release.

getline

row

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.

NOTE: relying on "string" to return the current data after "fetch()" is deprecated and will (probably) be removed in a future release. Only rely on its value after "combine()". See similar warnings in "fetch" and "fields".

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.

NOTE: relying on fields to return the current data after "fetch()" is deprecated and will (probably) be removed in a future release. Only rely on its value after "combine()". See similar warnings in "fetch" and "string".

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.

If the parser has no names or fields, returns the null list.

errstr

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