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, allowing the lines to be treated as hash references. If it did not have a built in header, the lines could still be treated as hash references, by passing a list of header names as an argument to tie or new (see OPTIONS).

If the file did not have a built in header, and no header was passed as an argument to tie or new, then lines are treated as array references.

   $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 or non-existent, 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 or non-existent, 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' );
   ## 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 );

sep_char

Perhaps the most common reason for giving the csv_parser option is to specify a non-comma separator character. For this reason, you can specify a separator character using the sep_char option. This is passed directly to the internally created Text::CSV_XS object.

   ## use colon separators
   my $csv_fh = Tie::Handle::CSV->new( 'basic.csv', sep_char => ':' );

If you specify both the sep_char and csv_parser options, the sep_char option is ignored.

AUTHOR

Daniel B. Boorstein, <danboo@cpan.org>

SEE ALSO

Text::CSV_XS

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.

cpanm Tie::Handle::CSV

perl -MCPAN -e shell
install Tie::Handle::CSV