NAME
    Text::CSV::Simple - Simpler parsing of CSV files

SYNOPSIS
            my $parser = Text::CSV::Simple->new;
            my @data = $parser->read_file($datafile);
            print @$_ foreach @data;

            # Only want certain fields?
            my $parser = Text::CSV::Simple->new;
            $parser->want_fields(1, 2, 4, 8);
            my @data = $parser->read_file($datafile);

            # Map the fields to a hash?
            my $parser = Text::CSV::Simple->new;
            $parser->field_map(qw/id name null town/);
            my @data = $parser->read_file($datafile);

DESCRIPTION
    Parsing CSV files is nasty. It seems so simple, but it usually isn't.
    Thankfully Text::CSV_XS takes care of most of that nastiness for us.

    Like many modules which have to deal with all manner of nastiness and
    edge cases, however, it can be clumsy to work with in the simple case.

    Thus this module.

    We simply provide a little wrapper around Text::CSV_XS to streamline the
    common case scenario. (Or at least my common case scenario; feel free to
    write your own wrapper if this one doesn't do what you want).

METHODS
  new
            my $parser = Text::CSV::Simple->new(\%options);

    Construct a new parser. This takes all the same options as Text::CSV_XS.

  read_file
            my @data = $parser->read_file($filename);

    Read the data in the given file, parse it, and return it as a list of
    data.

    Each entry in the returned list will be a listref of parsed CSV data.

  want_fields
            $parser->want_fields(1, 2, 4, 8);

    If you only want to extract certain fields from the CSV, you can set up
    the list of fields you want, and, hey presto, those are the only ones
    that will be returned in each listref. The fields, as with Perl arrays,
    are zero based (i.e. the above example returns the second, third, fifth
    and ninth entries for each line)

  field_map
            $parser->field_map(qw/id name null town null postcode/);

    Rather than getting back a listref for each entry in your CSV file, you
    often want a hash of data with meaningful names. If you set up a
    field_map giving the name you'd like for each field, then we do the
    right thing for you! Fields named 'null' vanish into the ether.

TRIGGER POINTS
    To enable you to make this module do things that I haven't dreamed off
    (without you having to bother me with requests to extend the
    functionality), we use Class::Trigger to provide a variety of points at
    which you can hook in and do what you need. In general these should be
    attached to the $parser object you've already created, although you
    could also subclass this module and set these up as class data.

    Each time we call a trigger we wrap it in an eval block. If the eval
    block catches an error we simply call 'next' on the loop. These can
    therefore be used for short-circuiting.on certain conditions.

  before_parse
      $parser->add_trigger(before_parse => sub {
        my ($self, $line) = @_;
        die unless $line =~ /wanted/i;
      });

    Before we call Text::CSV_XS 'parse' on each line of input text, we call
    the before_parse trigger with that line of text.

  after_parse
      $parser->add_trigger(after_parse => sub {
        my ($self, $data) = @_;
        die unless $wanted{$data->[0]};
      });

    After we sucessfully call Text::CSV_XS 'parse' on each line of input
    text, we call the after_parse trigger with a list ref of the values

  error
    Currenly, for each line that we can't parse, we call the 'failure'
    trigger (with the Text::CSV_XS parser object), which emits a warning and
    moves on. This happens in an invisible superclass, so you can supply
    your own behaviour here:

            $parser->add_trigger(on_failure => sub { 
                    my ($self, $csv) = @_;
                    warn "Failed on " . $csv->error_input . "\n";
            });

AUTHOR
    Tony Bowden

BUGS
    This doesn't cope with multi-line fields. Technically the CSV format
    allows this, but this is meant to be a ::Simple module, and coping with
    that is currently outside the cope of this module.

SEE ALSO
    Text::CSV_XS

BUGS and QUERIES
    Please direct all correspondence regarding this module to:
    bug-Text-CSV-Simple@rt.cpan.org

COPYRIGHT AND LICENSE
      Copyright (C) 2004-2005 Tony Bowden.

      This program is free software; you can redistribute it and/or modify
      it under the terms of the GNU General Public License; either version
      2 of the License, or (at your option) any later version.

      This program is distributed in the hope that it will be useful,
      but WITHOUT ANY WARRANTY; without even the implied warranty of
      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.