
=head1 NAME


Mail::Box::Tie::HASH - access an existing message folder as a hash

=head1 SYNOPSIS


 tie my(%inbox), 'Mail::Box::Tie::HASH', $folder;

 foreach my $msgid (keys %inbox)
 {   print $inbox{$msgid};
     delete $inbox{$msgid};
 }

 $inbox{$msg->messageId} = $msg;

=head1 DESCRIPTION


Certainly when you look at a folder as being a set of related messages
based on message-id, it is logical to access the folder through a hash.

For a tied hash, the message-id is used as the key.  The message-id is usually
unique, but when two or more instances of the same message are in the same
folder, one will be flagged for deletion and the other will be returned.

This implementation uses basic folder access routines which are related
to the message-id.

=head1 METHODS

=head2 Initiation

=over 4

=item B<tie> HASH, 'Mail::Box::Tie::HASH', FOLDER X<tie>

Connects the FOLDER object to a HASH.

Examples:

 my $mgr    = Mail::Box::Manager->new;
 my $folder = $mgr->open(access => 'rw');
 tie my(%inbox), 'Mail::Box::Tie::HASH', $folder;

=back

=head2 Tied Interface

=over 4

=item B<DELETE> MESSAGE-ID X<DELETE>

Remove the message with the specified MESSAGE-ID.

Examples:

 %inbox = ();
 %inbox = ($msg->messageId, $msg); #before adding msg

=item B<EXISTS> MESSAGE-ID X<EXISTS>

Check whether a message with a certain MESSAGE-ID exists.

Examples:

 if(exists $inbox{$msgid}) ...

=item B<FETCH> MESSAGEID X<FETCH>

Get the message with the specified id.  The returned message may be
a dummy if message thread detection is used.  Returns C<undef> when
there is no message with the specified id.

Examples:

 foreach my $msgid (keys %inbox) ...
 foreach my $msg (values %inbox) ...

 while(my ($msgid, $msg) = each %inbox) {
    $msg->print unless $msg->deleted;
 }

=back

=head1 SEE ALSO

A good start to read is Mail::Box-Overview.
More documentation and a mailinglist are available from the project's
website at L<http://perl.overmeer.net/mailbox/>.

=head1 AUTHOR

Mark Overmeer (L<mark@overmeer.net|mailto:mark@overmeer.net>) with the help of many.

=head1 VERSION

This code is beta, version 2.019.

Copyright (c) 2001-2002 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.
