NAME
CSV::Reader - CSV reader class
DESCRIPTION
Simple CSV reader class that uses Text::CSV internally. The CSV files are expected to have a header row of column names. This was designed with the idea of using an iterator interface, but Perl does not support interators (nor interfaces) yet :(
SYNOPSIS
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;
},
},
);
# Show the field names found in the header row:
print 'Field names: ' . 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);
}PUBLIC STATIC METHODS
new($file, %options)
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 backslash
- mutators: 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).
DESTROY
Closes the private file handle, if any.
PROTECTED STATIC METHODS
_new_text_csv_object($args_hashref)
Creates and returns a new Text::CSV object using the given arguments. Child classes may override this method in order to tweak the arguments and/or customize the creation of the internal Text::CSV object.
PROTECTED OBJECT METHODS
_read()
Reads the next CSV data row and sets internal variables.
PUBLIC OBJECT METHODS
fieldNames()
Returns the field names as an array.
current()
Returns the current row.
linenum()
Returns the current row index.
nextRow()
Reads the next row.
eof()
Returns boolean
rewind()
Rewinds the file handle.
SEE ALSO
Text::CSV used by this class internally.
AUTHOR
Craig Manley
COPYRIGHT
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.