Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Apropos / Subsearch:
optional field

Mail::Box-Overview(3pmUser Contributed Perl DocumentatiMail::Box-Overview(3pm)

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


       The MailBox package is a suite of classes for accessing and managing
       email folders in a folder-independent manner. This package is an
       alternative to the "Mail::Folder" and "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

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

       The 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 sequentially.

       You may want to have a look at the sample scripts in the "scripts"

       The class relations

       Mail::Box::Manager objects play a central role in any program which is
       built with MailBox.  Each program will create one manager, and then
       open folders via that manager.  Besides folders, the manager can also
       be used to discover message threads: sequences of messages with their

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

       Each folder maintains a list of messages.  Much effort is made to hide
       differences between folder types and kinds of messages.  Your program
       can be used for MBOX, MH, Maildir, and POP3 folders with no change at
       all (as long as you stick to the rules).

        Mail::Box::Mbox  <-----------* Mail::Box::Mbox::Message
               ^             <has-a>            ^
               | <isa>                          | <isa>
               |                                |
           Mail::Box     ............. Mail::Box::Message
                                                | <isa>
                                               / \
                                             /     \
                                  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 of abstraction:
       Mail::Box::Dir.  The POP3 folder has an intermediate Mail::Box::Net.

       In the future, when more Mbox-like folder types get implemented, there
       may be a Mail::Box::File level too.  The following is also true for the
       mail boxes

        MB::MH::Message                 MB::POP3::Message
              \  MB::Maildir::Message            /
               \         /                      /
                \       /   MB::Mbox::Message  /
                 \     /         |            /
               MB::Dir::Message  |   MB::Net::Message
                            \    |    /
                             \   |   /

       The Manager

       The mailbox manager Mail::Box::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 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 directly.

       The Messages

           A base class that defines an interface for manipulating the head
           and body of a message.  There are various header object types
           (Mail::Message::Head's) and a bunch of body object types

           The Mail::Message::Construct package is loaded when more complex
           tasks have to be performed on messages, like creating replies,
           bounces, or a forward message.  These functionalities are described
           and implemented in the ::Construct file, but are automatically
           added to the Mail::Message namespace when used.

           Message types which are foreign to MailBox can be used in the
           MailBox environment: there are some converters implemented via
           Mail::Message::Convert.  Particularly the popular Mail::Internet
           and MIME::Entity are supported.

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

           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
           Mail::Message::Body::Multipart, which contains a set of
           Mail::Message::Part objects.  These are just like normal messages,
           except that they are contained in an other message.  The
           Mail::Message::Body::Nested body type is comparible, but contains
           only one message: they are used for "message/rfc822" message

           When needed, the functionality of the body objects is extended with
           Mail::Message::Body::Construct and Mail::Message::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 Mail::Message::TransferEnc packages).  Automatic character
           and mime recodings are on the wish-list.

           The header for a single message. Maintains a set of
           Mail::Message::Field objects, each containing one header line.
           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
           Mail::Message::Head::Complete version knows all lines for sure,
           Mail::Message::Head::Subset maintains an unknown subset of lines,
           and the Mail::Message::Head::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 "::Complete"
           header.  It is fully transparent to the user of MailBox in which
           shape the header really is on the moment.

       The Folder types

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

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

           The base class for all folders which have the messages outside
           direct reach of the MailBox library, for instance on a remote
           system, or in a database.

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

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

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

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

           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.

           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.

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

           Implements the POP3 protocol based on Mail::Box::Net.  The
           Mail::Transport::POP3 implementation handles the protocol details.
           In this kind of folders, you can only read and delete messages.

       Various Other Classes

           Maintains a set of message-threads over one or more folders.  A
           message-thread 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 Mail::Box::Thread::Node
           objects.  Mail::Message::Dummy's fill-up some holes.

           Provides a folder locking interface which is inherited by the
           Mail::Box class.  Currently it supports dot-file locking
           ("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.

           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.

           The parser reads messages, and transforms them into data-structures
           such that the content of header and body can be used within the
           program.  The first parser is implemented in pure Perl.  A second
           parser is under development, and will written in C, to gain speed.

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

           Various ways of sending and receiving messages are implemented.
           Sending is possible via external programs, like "mail", "Mailx",
           "sendmail", or autonomously with direct SMTP.  Receiving is
           currently only implemented via POP3.

           A debugging and logging class which is inherited by most of the
           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 Mail::Box report about problems, or do it
           all yourself.

       All classes are written to be extensible.

       This module is part of Mail-Box distribution version 2.082, built on
       April 28, 2008. Website: http://perl.overmeer.net/mailbox/

       Copyrights 2001-2008 by Mark Overmeer. For other contributors see

       This program is free software; you can redistribute it and/or modify it
       under the same terms as Perl itself.  See

perl v5.10.0                      2008-04-28           Mail::Box-Overview(3pm)