The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Tie-Handle-CSV-0.06
River stage zero No dependents
1 ++
/ Tie::Handle::CSV

NAME

Tie::Handle::CSV - easy access to CSV files

VERSION

Version 0.06

SYNOPSIS

   use strict;
   use warnings;

   use Tie::Handle::CSV;

   my $csv_fh = Tie::Handle::CSV->new('basic.csv', header => 1);

   while (my $csv_line = <$csv_fh>)
      {
      $csv_line->{'salary'} *= 1.05;  ## give a 5% raise
      print $csv_line, "\n";          ## auto-stringify to CSV line on STDOUT
      }

   close $csv_fh;

DESCRIPTION

Tie::Handle::CSV makes basic access to CSV files easier.

Features

Auto-parse CSV line

When you read from the tied handle, the next line from your CSV is parsed and returned as a data structure ready for access. In the example below $csv_line is a hash reference with the column names for keys and the values being the corresponding data from the second line of the file.

   my $csv_fh = Tie::Handle::CSV->new('foo.csv', header => 1);
   my $csv_line = <$csv_fh>;
   print $csv_line->{'Id'};

In the above example $csv_line is a hash reference because the tied handle was declared as having a header. If the CSV file does not have a header the line is parsed and returned as an array reference:

   my $csv_fh = Tie::Handle::CSV->new('bar.csv', header => 0);
   my $csv_line = <$csv_fh>;
   print $csv->[0];

Auto-stringify to CSV format

When you use the $csv_line in a string context it is automatically reconstituted as a CSV line.

   print $csv_line, "\n";  ## prints "123,abc,xyz\n"

EXAMPLES

Assume basic.csv contains:

   name,salary,job
   steve,20000,picker
   dee,19000,checker

The following script uppercases the first letter of everyone's name, increases their salary by 5% and prints the modified CSV data to STDOUT.

   my $csv_fh = Tie::Handle::CSV->new('basic.csv', header => 1);
   while (my $csv_line = <$csv_fh>)
      {
      $csv_line->{'name'} = ucfirst $csv_line->{'name'};
      $csv_line->{'salary'} *= 1.05;
      print $csv_line . "\n";
      }
   close $csv_fh;

The converted output on STDOUT would appear as:

   Steve,21000,picker
   Dee,19950,checker

METHODS

new

   my $csv_fh = Tie::Handle::CSV->new('basic.csv');

The new method returns a tied filehandle. The default options would make the above equivalent to:

   my $csv_fh = Tie::Handle::CSV->new( file       => 'basic.csv',
                                       header     => 1,
                                       openmode   => undef,
                                       csv_parser => Text::CSV_XS->new(),
                                       sep_char   => undef,
                                       stringify  => 1 );

The options to new are discussed in detail below.

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 );

file

This option specifies the path to the CSV file. As an alternative, the file key can be omitted. When there are an odd number of arguments the first argument is taken to be the file name. 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' );

This option controls whether headers are to be used. If it is false, lines will be represented as array references.

   ## no header
   my $csv_fh = Tie::Handle::CSV->new( 'no_header.csv', header => 0 );
   ## print first field of first line
   my $csv_line = <$csv_fh>;
   print $csv_line->[0], "\n";

If this option is true, and not an array reference the values from the first line of the file are used as the keys in the hash references returned from subsequent line reads.

   ## header in file
   my $csv_fh = Tie::Handle::CSV->new( 'header.csv' );
   ## print 'name' value from first line
   my $csv_line = <$csv_fh>;
   print $csv_line->{'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 'name' value from first line
   my $csv_line = <$csv_fh>;
   print $csv_line->{'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 => '+<' );

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.

stringify

If the stringify value is true then lines are returned as tied hash or array references that auto-stringify back to CSV format. When this option is false line reads return simple hash or array references. This is intended as an optimization for faster reads when you don't need to print the line. The default behavior is stringification.

AUTHOR

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

SEE ALSO

Text::CSV_XS

BUGS

Please report any bugs or feature requests to bug-tie-handle-csv at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Tie-Handle-CSV. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Tie::Handle::CSV

You can also look for information at:

COPYRIGHT & LICENSE

Copyright 2007 Daniel B. Boorstein, all rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.