Tie::Array::CSV(3pm)

💖 Tie::Array::CSV 💖

okay bestie, so this is Tie::Array::CSV — a Perl module, from the User Contributed Perl Documentation collection, and it is literally the moment a tied array got the best of both worlds: the power of Tie::File ✨ plus Text::CSV 🎀. Buckle up, it's giving genius.

---

✨ NAME ✨

Tie::Array::CSV — a tied array which combines the power of Tie::File and Text::CSV. periodt. 💅

---

🌸 SYNOPSIS 🌸

use strict; use warnings;
use Tie::Array::CSV;
tie my @file, 'Tie::Array::CSV', 'filename';

print $file[0][2];
$file[3][5] = "Camel";

like. look at that. you just print a cell and write a cell. iconic. 👑

---

🦋 DESCRIPTION 🦋

So here's the tea, bestie: this module lets you tie an array 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 you access to the row and column of your choosing. No cap. 💯

It pulls this off by standing on the shoulders of two extremely 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 itself (which that module did) — instead it passes all of the heavy lifting to other modules. delegation queen fr fr.

⚠️ Note that while Tie::File prevents the need to read in the entire file, while in use, a parsed row IS held in memory. so like, one row at a time, not the whole thing. vibe check passed.

---

🎀 CONSTRUCTORS 🎀

Since version 0.04, both constructors allow the options that version 0.03 only offered for the new constructor. glow-up behavior.

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. it's the main character, obviously.

💫 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 arguments to tie, one may optionally pass key-value pairs or a hashref containing additional configuration or even file specification. so many options, we love a flexible bestie:

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 tied array due to limitations in how tie magic works. yeah. the magic has ✨rules✨. we don't make them. 🧚

👑 Options 👑

• file — alternative method for specifying the file to tie. This is overridden by a lone filename or handle passed as the first argument to the constructor. (so, again: lone argument = main character energy.)
• 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, or
  • 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, because we love a both-ways-work moment:

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. she moved out and got her own place, we respect it. 🫶

---

💀 ERRORS 💀

For simplicity this module croaks on almost all errors, which are trappable using a $SIG{__DIE__} handler. Modifying a severed row object issues a warning. not me getting a warning 😭 handle your errors bestie.

---

🙈 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. (so: whole-row shuffle = slow. inside-a-row shuffle = fine. iykyk.)
• At one time, some effort had 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. it's a whole saga, we don't talk about it. 💀

---

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

---

okay that's the whole page, bestie, you're officially certified 📜✨ — this was Tie::Array::CSV for perl v5.40.1, dated 2025-09-23, mwah 💋 go write some CSV cells, slay 🦋💅