NAME

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

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;

METHOD INDEX

The general methods for Mail::Box::Tie::ARRAY objects:

      DELETE                               PUSH [MESSAGES]
      FETCH INDEX                          STORE INDEX, MESSAGE
      FETCHSIZE                            STORESIZE LENGTH

METHODS

tie ARRAY, 'Mail::Box::Tie::ARRAY', FOLDER

tie ARRAY, 'Mail::Box::Tie', FOLDER

Create the tie on an existing folder. The second version is deprecated, but will work because Mail::Box::Tie::TIEARRAY will trigger usage of this class.

Example:

    my $mgr   = Mail::Box::Manager->new;
    my $inbox = $mgr->new(folder => $ENV{MAIL});
    tie my(@inbox), ref $inbox, $inbox;

FETCH INDEX

Get the message which is at the indicated location in the list of messages contained in this folder. Deleted messages will be counted.

Example:

   print $inbox[3];

STORE INDEX, MESSAGE

Random message replacement is 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--see below).

If you want to replace one message in a folder, then do the following:

    $inbox[3]->delete;
    push @inbox, $replacement;

FETCHSIZE

Return the total number of messages in a folder. This is called when the folder-array is used in scalar context, for instance.

    if(@inbox > 10)    # contains more than 10 messages
    my $nrmsgs = @inbox;

PUSH [MESSAGES]

Add messages to the end of the folder.

    push @inbox, $newmsg;

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.

Examples:

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

STORESIZE LENGTH

Sets all messages behind from LENGTH to the end of folder to be deleted.

LIMITATIONS for arrays

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

SEE ALSO

Mail::Box-Overview

AUTHOR

Mark Overmeer (mailbox@overmeer.net). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

VERSION

This code is beta, version 2.006.

Copyright (c) 2001 Mark Overmeer. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.