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.