Mail::Box::Tie::ARRAY(3pm)

NAME
Mail::Box::Tie::ARRAY - access an existing message folder as array

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

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;

DESCRIPTION
Certainly when you look at a folder as a list of messages, it is logical to access the folder through an array.

Not all operations on arrays are supported. Actually, most functions which would reduce the size of the array are modified instead to mark messages for deletion.

Examples what you 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 that the message stays in the folder, and is not removed before the folder is written.

    » example:

      delete $inbox[5];
      $inbox[5]->delete;   #same

$obj->FETCH($index)
    Get the message which is 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()).

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

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.01, built on December 13, 2025. Website: http://perl.overmeer.net/CPAN/

LICENSE
For contributors see file ChangeLog.

This software is copyright (c) 2001-2025 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.