Mail::...::ARRAY(3pm)

📦
version 4.02 · 9 versions
, in ubuntu stonking

🎀 NAME 🎀

Mail::Box::Tie::ARRAY — access an existing message folder as array. yes bestie, your whole folder is literally just an array now 💅

💫 INHERITANCE 💫

Mail::Box::Tie::ARRAY
  is a Mail::Box::Tie

so it picked up everything from its parent, as one does 🧚

✨ SYNOPSIS ✨

use Mail::Box::Manager;
my $mgr    = Mail::Box::Manager->new;
my $folder = $mgr->open(folder => 'inbox');

use Mail::Box::Tie::ARRAY;
tie my(@inbox), 'Mail::Box::Tie::ARRAY', $folder;

# deprecated, but works too
use Mail::Box::Tie;
tie my(@inbox), 'Mail::Box::Tie', $folder;

foreach (@inbox) {print $_->short}
print $_->print foreach @inbox;
my $emails = @inbox;

print $inbox[3];
print scalar @inbox;
push @inbox, Mail::Box::Message->new(...);
delete $inbox[6];
print $inbox[0]->head->get('status');

my $folder = tied @inbox;
untie @inbox;

like look at her go 😭 she's arraying

🌸 DESCRIPTION 🌸

okay so. when you look at a folder, you're basically looking at a list of messages, right? so it's only logical to reach the whole folder through an array. that's the vibe. that's the whole thing.

but — not every array operation is on the menu. lowkey most of the functions that would shrink the array get rewritten instead to just mark messages for deletion. so nothing actually disappears on you, it just gets flagged 👑

examples of what you literally cannot do:

shift/unshift/pop/splice @inbox;

Extends "DESCRIPTION" in Mail::Box::Tie.

🔥 METHODS 🔥

Extends "METHODS" in Mail::Box::Tie.

🫶 Constructors 🫶

Extends "Constructors" in Mail::Box::Tie.

  • tie @array, 'Mail::Box::Tie::ARRAY', FOLDER — create the tie on an existing folder.

» example: tie an array to a folder

my $mgr   = Mail::Box::Manager->new;
my $inbox = $mgr->new(folder => $ENV{MAIL});
tie my(@inbox), 'Mail::Box::Tie::Array', ref $inbox, $inbox;
  • $class->new($folder, $type) — Inherited, see "Constructors" in Mail::Box::Tie

🦋 Attributes 🦋

Extends "Attributes" in Mail::Box::Tie.

  • $obj->folder() — Inherited, see "Attributes" in Mail::Box::Tie
  • $obj->type() — Inherited, see "Attributes" in Mail::Box::Tie

💖 Tied Interface 💖

  • $obj->DELETE() — flag a message to be removed. ⚠️ be warned: the message stays in the folder, and is not removed before the folder is written. so it's giving "marked for death but still at the party" 💀

» example:

delete $inbox[5];
$inbox[5]->delete;   #same
  • $obj->FETCH($index) — get the message at the indicated location in the list of messages contained in this folder. deleted messages will be returned as undef.

» example:

print $inbox[3];     # 4th message in the folder
print @inbox[3,0];   # 4th and first of the folder
print $inbox[-1];    # last message
  • $obj->FETCHSIZE() — return the total number of messages in a folder. this is called when the folder-array is used in scalar context, for instance.

» example:

if(@inbox > 10)    # contains more than 10 messages?
my $nrmsgs = @inbox;
  • $obj->PUSH(@messages) — add @messages to the end of the folder.

» example:

push @inbox, $newmsg;
  • $obj->STORE($index, $message) — random message replacement is not permitted — doing so would disturb threads etc. an error occurs if you try to do this. the only thing which is allowed is to store a message at the first free index at the end of the folder (which is also achievable with PUSH()). so like, stay in your lane bestie 🚫

» example:

$inbox[8]  = $add;
$inbox[-1] = $add;
push @inbox, $add;
  • $obj->STORESIZE($length) — sets all messages behind from $length to the end of folder to be deleted.

⭐ DETAILS ⭐

🌈 Folder tied as array 🌈

Limitations

this module implements "TIEARRAY", "FETCH", "STORE", "FETCHSIZE", "STORESIZE", "DELETE", "PUSH", and "DESTROY".

this module does not implement all other methods as described in the Tie::Array documentation, because the real array of messages is not permitted to shrink or be mutilated. she's protected. she's guarded. no cap.

💀 DIAGNOSTICS 💀

  • Error: cannot simply replace messages in a folder: use delete old, then push new. Cast by STORE()
  • Error: no folder specified to tie to. Cast by new()

👑 SEE ALSO 👑

this module is part of Mail-Box version 4.02, built on April 10, 2026.

Website: http://perl.overmeer.net/CPAN/

🍓 LICENSE 🍓

for contributors see file ChangeLog.

this software is copyright (c) 2001-2026 by Mark Overmeer.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

and that's the whole page, bestie ✨ perl v5.40.1, dated 2026-05-09, from the Mail::...::ARRAY(3pm) era — slay, periodt 💜🦋

📦 where this page comes from