NAME
Tie::Handle::CSV - easy access to CSV files
SYNOPSIS
use strict;
use warnings;
use Tie::Handle::CSV;
my $csv_fh = Tie::Handle::CSV->new('basic.csv', header => 1);
$csv_fh || die $!;
while (my $csv_line = <$csv_fh>)
{
$csv_line->{'salary'} *= 1.05; ## give a 5% raise
print $csv_line, "\n"; ## print new CSV line to STDOUT
}
close $csv_fh;
DESCRIPTION
Tie::Handle::CSV
makes basic access to CSV files easier. When you read from the file handle, a hash reference or an array reference is returned depending on whether headers exist or do not.
Regardless of the type of the returned data, when it is converted to a string, it automatically converts back to CSV format.
Assume basic.csv
contains.
name,salary,job
steve,20000,picker
dee,19000,checker
File handles can either be tied using the tie
builtin...
tie *CSV_FH, 'Tie::Handle::CSV', 'basic.csv', header => 1;
or by constructing one with the new()
method.
my $csv_fh = Tie::Handle::CSV->new('basic.csv', header => 1);
If either tie
or new
return a false value, then open
failed, and you can check $!
as usual.
$csv_fh || die $!;
You can read from this file handle as you normally would.
my $first_line = <$csv_fh>;
At this point, because the header => 1
option was given, $first_line
is actually a hash reference, not a string.
$first_line->{'salary'} *= 1.05; ## cost of living increase
print "$first_line->{'name'} => $first_line->{'salary'}\n";
Despite the fact that $first_line
is a hash reference, printing it or any usage as a string, converts it back to CSV format.
print $first_line, "\n"; ## prints "steve,21000,picker\n"
In the example above, the file has a header. If it did not, 2 options would exist. The header information could be passed in as an argument to tie
or new
(see OPTIONS), or the file could be read with no header information.
This last option means that when your CSV file has no header information (in the file or passed in as an option), then lines are returned as array references and can be accessed by numerical index.
$first_line->[1] *= 1.05; ## cost of living increase
Printing and string conversion still automatically result in CSV conversion as with a hash reference.
OPTIONS
If the number of arguments passed to tie
(after the Tie::Handle::CSV
name is given) or new
is an odd number, then the first argument is assumed to be the name of the CSV file. Any remaining arguments are treated as key-value options pairs.
tie *CSV_FH, 'Tie::Handle::CSV', 'basic.csv';
my $csv_fh = Tie::Handle::CSV->new( 'basic.csv', header => 1 );
If the number of arguments is even, then all are considered to be key-value option pairs.
tie *CSV_FH, 'Tie::Handle::CSV', file => 'basic.csv', header => 1;
my $csv_fh = Tie::Handle::CSV->new( file => 'basic.csv' );
The following option keys are recognized:
file
This option specifies the path to the CSV file. If this option is given in conjunction with an odd number of arguments, the first argument takes precedence over this option.
## same results
my $csv_fh = Tie::Handle::CSV->new( 'basic.csv' );
my $csv_fh = Tie::Handle::CSV->new( file => 'basic.csv' );
header
This option indicates whether and how headers are to be used. If this option is true, lines will be represented as hash references. If it is false, lines will be represented as array references.
## no header
my $csv_fh = Tie::Handle::CSV->new( 'basic.csv', header => 0 );
## print first field of first line
print +( scalar <$csv_fh> )->[0], "\n";
If this option is true, and not an array reference the first line of the file is read at the time of calling tie
or new
and used to define the hash reference keys.
## header in file
my $csv_fh = Tie::Handle::CSV->new( 'basic.csv', header => 1 );
## print first field of first line
print +( scalar <$csv_fh> )->{'name'}, "\n";
If the value for this option is an array reference, the values in the array reference are used as the keys in the hash reference representing the line of data.
## header passed as arg
my $csv_fh = Tie::Handle::CSV->new( 'basic.csv',
header => [qw/ name salary /] );
## print first field of first line
print +( scalar <$csv_fh> )->{'name'}, "\n";
openmode
If this option is defined, the value is used as the MODE argument in the 3-arg form of open
. Otherwise, the file is opened using 2-arg open
.
## open in read-write mode
my $csv_fh = Tie::Handle::CSV->new( 'basic.csv', openmode => '+<' );
csv_parser
Internally, Text::CSV_XS is used to do CSV parsing and construction. By default the Text::CSV_XS instance is instantiated with no arguments. If other behaviors are desired, you can create your own instance and pass it as the value to this option.
## use colon separators
my $csv_parser = Text::CSV_XS->new( sep_char => ':' );
my $csv_fh = Tie::Handle::CSV->new( 'basic.csv',
csv_parser => $csv_parser );
AUTHOR
Daniel B. Boorstein, <danboo@cpan.org>
SEE ALSO
COPYRIGHT AND LICENSE
Copyright 2004 by Daniel B. Boorstein
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.