NAME
Tie::Array::CSV - A tied array which combines the power of Tie::File and Text::CSV
SYNOPSIS
use strict; use warnings;
use Tie::Array::CSV;
tie my @file, 'Tie::Array::CSV', 'filename';
print $file[0][2];
$file[3][5] = "Camel";
DESCRIPTION
This module allows an array to be tied to a CSV file for reading and writing. The array is a standard Perl 2D array (i.e. an array of array references) which gives access to the row and column of the user's choosing. This is done using the well established modules:
-
arbitrary line access
low memory use even for large files
-
row parsing
row updating
uses the speedy Text::CSV_XS if installed
This module was inspired by Tie::CSV_File which (sadly) hasn't been maintained. It also doesn't attempt to do any of the parsing (as that module did), but rather passes all of the heavy lifting to other modules.
Note that while the Tie::File prevents the need to read in the entire file, while in use, a parsed row IS held in memory. This is true whether <hold_row> is in effect or not (see Options below).
CONSTRUCTORS
Since version 0.04 both constructors allow the options that version 0.03 only offered for the new
constructor. The constructors must be passed a file name, either as the first argument, or as the value to the option key file
. Options may be passed as key-value pairs or as a hash reference. This yields the many ways of calling the constructors shown below, one for every taste.
N.B. Should a lone argument filename and a file
option key both be passed to the constructor, the lone argument wins.
tie
Constructor
As with any tied array, the construction uses the tie
function. Basic usage is as follows:
tie my @file, 'Tie::Array::CSV', 'filename';
which would tie the lexically scoped array @file
to the file filename
using this module. Following the first two arguements to tie
, one may optionally pass a key-value pairs or a hashref containing additional configuration or even file specification.
tie my @file, 'Tie::Array::CSV', 'filename', { opt_key => val, ... };
tie my @file, 'Tie::Array::CSV', 'filename', opt_key => val, ... ;
tie my @file, 'Tie::Array::CSV', { file => 'filename', opt_key => val, ... };
tie my @file, 'Tie::Array::CSV', file => 'filename', opt_key => val, ... ;
Of course, the magical Perl tie
can be scary for some, for those people there is the ...
new
Constructor
[ Added in version 0.03 ]
my $array = Tie::Array::CSV->new( 'filename' );
my $array = Tie::Array::CSV->new( 'filename', { opt_key => val, ... });
my $array = Tie::Array::CSV->new( 'filename', opt_key => val, ... );
my $array = Tie::Array::CSV->new( file => 'filename', opt_key => val, ... );
my $array = Tie::Array::CSV->new( { file => 'filename', opt_key => val, ... } );
It only returns a reference to the tie
d array due to a limitations in how tie
magic works.
Options
file
- alternative method for specifing the file totie
. This is overridden by a lone filename or handle passed as the first argument to the constructor.tie_file
- hashref of options which are passed to the Tie::File constructortext_csv
- hashref of options which are passed to the Text::CSV constructorsep_char
- for ease of use, asep_char
option may be specified, which is passed to the Text::CSV constructor. This option overrides a corresponding entry in thetext_csv
pass-through hash.hold_row
- If true, the file is not updated while the reference to the row is still in scope. The default is true. Note: that when false, the parsed row is still held in memory while the row is in scope, the ONLY difference is that the file reflects changes immediately whenhold_row
is false. To reiterate, this option only affects file IO, not memory usage.
Equivalent examples:
tie my @file, 'Tie::Array::CSV', 'filename', {
tie_file => {},
text_csv => { sep_char => ';' },
hold_row => 0
};
tie my @file, 'Tie::Array::CSV', 'filename', sep_char => ';', hold_row => 0;
ERRORS
For simplicity this module croak
s on all errors, which are trappable using a $SIG{__DIE__}
handler.
CAVEATS
Much of the functionality of normal arrays is mimicked using Tie::Array. The interaction of this with Tie::File should be mentioned in that certain actions may be very inefficient. For example,
(un)shift
-ing the first row of data will probably involve Tie::Array asking Tie::File to move each row up one line, one-by-one. As a note, the intra-row(un)shift
does not suffer this problem.Some effort had been made to allow for fields which contain linebreaks. Linebreaks would change line numbers used for row access by Tie::File. This, unfortunately, moved the module far from its stated goals, and therefore far less powerful for its intended purposes. The decision has been made (for now) not to support such files.
SEE ALSO
Tie::CSV_File - inspiration for this module, but problematic
Tie::Array::DBD - tie database connection to array
Tie::DBI - similar but hash based
SOURCE REPOSITORY
http://github.com/jberger/Tie-Array-CSV
AUTHOR
Joel Berger, <joel.a.berger@gmail.com>
COPYRIGHT AND LICENSE
Copyright (C) 2011 by Joel Berger
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.