Easy to use Perl CSV file/handle reader class that's meant for reading typical CSV files having a CSV header row.
This was designed with the idea of using an iterator interface, but Perl does not support interators (nor interfaces) yet :(
You can also find this module on cpan: https://metacpan.org/pod/CSV::Reader
use CSV::Reader ();
use open OUT => ':locale'; # optional; make perl aware of your terminal's encoding
# Create reader from file name:
my $reader = new CSV::Reader('/path/to/file.csv');
# Create reader from a file handle (GLOB):
open(my $h, '<', $filename) || die("Failed to open $filename: $!");
# or preferred method that can handle files having a UTF-8 BOM:
open(my $h, '<:via(File::BOM)', $filename) || die("Failed to open $filename: $!");
my $reader = new CSV::Reader($h);
# Create reader from an IO::Handle based object:
my $io = IO::File->new(); # subclass of IO::Handle
$io->open($filename, '<:via(File::BOM)') || die("Failed to open $filename: $!");
my $reader = new CSV::Reader($io);
# Create reader with advanced options:
my $reader = new CSV::Reader('/path/to/file.csv',
'delimiter' => ';',
'enclosure' => '',
'field_normalizer' => sub {
my $nameref = shift;
$$nameref = lc($$nameref); # lowercase
$$nameref =~ s/\s/_/g; # whitespace to underscore
},
'field_aliases' => {
'postal_code' => 'postcode', # applied after normalization
},
'mutators' => {
'postcode' => sub { # if postalcode is Dutch, then make sure it has no spaces and is in uppercase.
my $val_ref = shift;
my $row_ref = shift;
if (defined($$val_ref) && defined($row_ref->{'country'}) && ($row_ref->{'country'} eq 'NL')) {
$$val_ref =~ s/\s+//;
$$val_ref = uc($$val_ref);
}
},
'has_fiber_internet' => sub { # set a default for an empty (undef) value
my $val_ref = shift;
$$val_ref //= 0; # defined-or assignment operator (in case you didn't know)
},
},
);
# Show the field names found in the header row:
print "Field names:\n" . join("\n", $reader->fieldNames()) . "\n";
# Iterate over the data rows:
while (my $row = $reader->nextRow()) {
# It's recommended to validate the $row hashref first with something such as Params::Validate.
# Now do whatever you want with the (validated) row hashref...
require Data::Dumper; local $Data::Dumper::Terse = 1;
print Data::Dumper::Dumper($row);
}
Constructor.
$file
can be a string file name, an open file handle (GLOB), or an IO::Handle based object (e.g. IO::File or IO::Scalar).
If a string file name is given, then the file is opened via File::BOM.
The following %options
are supported:
debug
: boolean, if true, then debug messages are emitted using warn().field_aliases
: hashref of case insensitive alias (in file) => real name (as expected in code) pairs.field_normalizer
: callback that receives a field name by reference to normalize (e.g. make lowercase).include_fields
: arrayref of field names to include. If given, then all other field names are excluded.delimiter
: string, default ','enclosure
: string, default '"'escape
: string, default backslashmutators
: hashref of field name => callback($value_ref, $row_ref) pairs.
Note: the option field_aliases
is processed after the option field_normalizer
if given.
Note: the callbacks given with the mutators
option are called in their key order (which is an unpredictable order unless they're tied with Tie::IxHash).
Returns the field names as an array.
Returns the current row.
Returns the current row index.
Reads the next row.
Returns boolean
Rewinds the file handle.
- File::BOM (recommended; not required)
- Params::Validate
- Text::CSV
- Tie::IxHash
CSV::Reader may be installed through the CPAN shell in the usual manner:
# perl -MCPAN -e 'install CSV::Reader'
or you can install the component from the CPAN prompt:
cpan> install CSV::Reader
perl Makefile.PL
make
make test
make install
Craig Manley
Copyright (C) 2020 Craig Manley. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.