
=head1 NAME

Mail::Box-Overview - objects used by Mail::Box

=head1 DESCRIPTION

The C<Mail::Box> package is a suite of classes for accessing and managing
email folders in a folder-independent manner. This package is an
alternative to the C<Mail::Folder> and C<MIME::*> packages. It abstracts the
details of messages, message storage, and message threads, while
providing better performance than older mail packages. It is meant to
provide an object-oriented toolset for all kinds of e-mail applications,
under which Mail User-Agents (MUA) and mail filtering programs.

This package is modular --parts of it can be used independently of the
rest. For example, the C<Mail::Box::Manager> can automatically determine
that a folder is in Mbox format and return an object of the
C<Mail::Box::Mbox> class, or the user program can bypass the manager and
create C<Mail::Box::Mbox> objects directly. Similarly, if the user program
is only manipulating a single message, a C<Mail::Message>.

The C<Mail::Box> package has special features to help MUA's access folder
data quickly in random order.  You will not really benefit (neither
slower) if you need the full folder sequencially.

This code is beta, which means that there are no serious applications
written with it yet.  Please inform the author when you have, so this
module can be marked as stable.  Read the STATUS file enclosed in the
package for more details.  You may also want to have a look at the sample
scripts in the B<scripts> directory.

=head2 Overview of the C<Mail::Box> Package

                       <has-a>      Mail::Box::Mbox
  Mail::Box::Manager <---------*    (Mail::Box::Dir::MH)
         ^                :         (Mail::Box::Dir::Maildir)
         |           (maintains)
         |                :
         `---------------------*  Mail::Box::Thread::Manager
                      (<has-a>)



  Mail::Box::Mbox  <-----------* Mail::Box::Mbox::Message
         ^             <has-a>            ^
         | <isa>                          | <isa>
         |                                |
     Mail::Box     ............. Mail::Box::Message
                                          ^
                                          | <isa>
                                          |
                                    Mail::Message
                                         / \
                                       <has-a>  
                                       /     \
                            Mail::Message   Mail::Message 
                              ::Body            ::Head

The situation for MH and Maildir folders is a little more complicated,
because they have an extra intermediate level: C<Mail::Box::Dir>.
In the future, when more Mbox-like folder types get implemented, there
may be a C<Mail::Box::File> level too.  The following is also true
for the mail boxes


   Mail::Box         Mail::Box
 ::MH::Message   ::Maildir::Message
          \         /
           \       /
           Mail::Box         Mail::Box
        ::Dir::Message    ::Mbox::Message
                  \         /
                   \       /
                   Mail::Box
                   ::Message
                       |
                       |
                 Mail::Message

The classes and relationships are described as follows:

=over 4

=item C<Mail::Box::Manager>

The mailbox manager encapsulates folder management issues. It maintains a
set of open mail folders (mailboxes), and provides methods for opening and
closing them, efficiently moving messages between folders, and
efficiently appending messages to folders.  It contains C<Mail::Box> objects
which may be of different types.  Most folder types can be detected
automatically.

The main manager also manages message-thread detector objects, and informs them
when the contents of a folder have changed. This manager class is the
only one you instantiate yourself: objects of all other classes will be
provided by your folder manager.

You are strongly advised to use this object, but you can often do without it
and open a specific folder-type yourself.

=item C<Mail::Message>

A base class that defines an interface for manipulating the head and
body of a message.  There are various header-objects
(see C<Mail::Message::Head>) and a bunch of body objects
(C<Mail::Message::Body>).  

The C<Mail::Message::Construct> package is loaded when more complex tasks
have to be performed on messages, like C<reply> or C<forward>.  These
functionalities are descibed and implemented in the C<::Construct>
file, but are added to the C<Mail::Message> namespace when used.

Message types which are foreign to C<Mail::Box> can be used in the
C<Mail::Box> environment: there are some convertors implemented via
C<Mail::Message::Convert>.  Particulary the popular C<Mail::Internet>
and C<MIME::Entity> are supported.

=item C<Mail::Box::Message>

An abstract base class which defines an interface for mail messages
which are stored in any folder.  It inherits from C<Mail::Message>, and
adds the basic idea of location to it.

=item C<Mail::Box>

A base class that defines a standard interface for mail boxes which
is independent of mailbox type. Objects of this class contain
a C<Mail::Box::Locker> and a list of C<Mail::Box::Message> objects.

=item C<Mail::Box::Mbox>

This class derives from C<Mail::Box>, and implements its interface for
mbox-style folders. It maintains a set of C<Mail::Box::Mbox::Message>
objects, which are derived from a C<Mail::Box::Message>.

Mbox-style folders have one file containing multiple messages per
folder.  When folders get large, access tends to get slow.

=item C<Mail::Box::Dir>

The base class for all folders which use a directory organization: each
message is a separate entity (file) grouped in a directory.  Each
C<Mail::Box::Dir::Message> represents one message, one such entity.

=item C<Mail::Box::MH>

This class derives from C<Mail::Box::Dir>, and implements its interface for
MH-style folders. It maintains a set of C<Mail::Box::MH::Message>
objects, which are derived from a C<Mail::Box::Dir::Message>.

MH-style folders are represented by a directory, where each message is
stored in a seperate file.  The message files are sequentially numbered.
It is fast to open one single message, but hard to get an overview.

=item C<Mail::Box::MH:Index>

The base class for MH mailbox indexes which provides methods for reading,
writing, and managing message indexes.  These indexes are used to
speed-up access to directory based folders.

=item C<Mail::Box::MH::Labels>

Also for efficiency reasons, a separate file is maintained which contains
flags about the messages.  This file for instance lists new files.  This
way, the MH message files do not have to be opened to find that out.

=item C<Mail::Box::Maildir>

As the  MH folder type, this class derives from C<Mail::Box::Dir>.  It
implements its interface for Maildir-style folders. It maintains a set
of C<Mail::Box::Maildir::Message> objects, which are derived from a
C<Mail::Box::Dir::Message>.

=item C<Mail::Message::Body>

This is the base-class for all message-bodies.  It describes what you
can do with any kind of body.  The body-types differ on the way how the
keep the body-content during the run of your program.

One special case of the body types is the C<::Multipart>, which
contains a set of C<Mail::Message::Part> objects.  These are just like
normal messages, except that they are contained in an other message.
The C<::Nested> body type contains only one message: they are used
for C<message/rfc822> message encodings.

When needed, the functionality of the body objects is extended with
C<::Body::Construct> and C<::Body::Encode>.  The former package implements
things like concatenation.  The later controls message encoding and
decoding.  In the current implementation this is limited to transfer
encodings (implemented in the C<Mail::Message::TransferEnc> packages),
Character and mime recodings are on the wish-list.

=item C<Mail::Message::Head>

The header for a single message. Maintains a set of C<Mail::Message::Field>
objects, each containing one header line.  Header fields are the only
objects which have no logging and tracing facilities, purely for reasons
of performance.

The header object has three sub-classes: the C<::Complete> version knows
all lines for sure, C<::Subset> maintains an unknown subset of lines, and
the C<::Delayed> has no lines yet but knows where to get them.

The latter two will automatically get the missing header lines from the
mailbox files when needed, and so transform into a C<::Complete> header.
It is fully transparent to the user of C<Mail::Box> in which shape the
header really is on the moment.

=item C<Mail::Box::Thread::Manager>

Maintains a set of message-threads over one or more folders.  A
message-tread is a start message with all the replies on it.  And the
replies on replies, and so on.  This object is used to construct the
thread for a set of open folders.

This object maintains linked lists of C<Mail::Box::Thread::Node> objects.
C<Mail::Box::Message::Dummy>s fill-up some holes.

=item C<Mail::Box::Locker>

Provides a folder locking interface which is inherited by the C<Mail::Box>
class.  Currently it supports dot-file locking (C<filename.lock>),
flock filehandle locking, and locking over NFS.  Each is implemented in a
separate class.  A multi-locker, using a set of lock-methods at the
same time is also available.

=item C<Mail::Box::Search>

The set of search packages implement various search techniques in an uniformal
way.  Although implementing your own search algorithm is simple in general,
in practice multiparts, encodings, and mime-types complicate things.

=item C<Mail::Box::Parser>

Describes the interface to the two current folder parsers: the parser
implemented with C<Inline::C>, and the parser fully in written in Perl.
The first is faster, the second more portable.

=item C<Mail::Box::Tie>

Provides hash (C<::HASH>) or array tied (C<::ARRAY>) access to any mail
folder derived from C<Mail::Box>.  This beautifies your code in some
applications.

=item C<Mail::Reporter>

A debugging and logging class which is inherited by most of the C<Mail::*>
modules.  For each object, you can say what log and error reports must be
kept or directly presented to the user.  This way you can decide to have
C<Mail::Box> report about problems, or do it all yourself.

=back

All classes are written to be extendable.  

=head1 SEE ALSO

L<Mail::Box-Cookbook>

=head1 AUTHOR

Mark Overmeer (F<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.

=head1 VERSION

This code is beta, version $version.

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.

=cut

