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:

       •   Tie::File

           •   arbitrary line access

           •   low memory use even for large files

       •   Text::CSV

           •   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.

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 to "tie". 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 constructor

       •   "text_csv" - either:

           •   hashref of options which are passed to the Text::CSV constructor

           •   an object which satisfies isa('Text::CSV') (added in version 0.05)

       •   "sep_char"  - for ease of use, a "sep_char" option may be specified, which is passed to the Text::CSV
           constructor. This option overrides a corresponding entry in the "text_csv" pass-through hash.

       Equivalent examples:

        tie my @file, 'Tie::Array::CSV', 'filename', {
          tie_file => {},
          text_csv => { sep_char => ';' },
        };

        tie my @file, 'Tie::Array::CSV', 'filename', sep_char => ';';

       Note that as of version 0.05 the functionality from the former "hold_row" option has been separated  into
       its  own  subclass  module  Tie::Array::CSV::HoldRow.  If deferring row operations is of interest to you,
       please see that module.

ERRORS

       For simplicity this module "croak"s on all almost all errors, which are trappable using  a  $SIG{__DIE__}
       handler. Modifing a severed row object issues a warning.

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.

       •   At  one  time,  some  effort  was  been made to allow for fields which contain linebreaks. Quickly it
           became clear that linebreaks would change line numbers used for row access by Tie::File. Attempts  to
           compensate  for  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

SOURCE REPOSITORY

       <http://github.com/jberger/Tie-Array-CSV>

AUTHOR

       Joel Berger, <joel.a.berger@gmail.com>

CONTRIBUTORS

       Christian Walde (Mithaldu) Graham Ollis (plicease)

COPYRIGHT AND LICENSE

       Copyright (C) 2013 by "AUTHOR" and "CONTRIBUTORS".

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

perl v5.40.1                                       2025-09-23                               Tie::Array::CSV(3pm)