{
    "mode": "perldoc",
    "parameter": "Mail::Box-Overview",
    "section": "",
    "url": "https://www.chedong.com/phpMan.php/perldoc/Mail%3A%3ABox-Overview/json",
    "generated": "2026-06-06T02:46:55Z",
    "sections": {
        "NAME": {
            "content": "Mail::Box-Overview - objects used by Mail::Box\n",
            "subsections": []
        },
        "DESCRIPTION": {
            "content": "",
            "subsections": [
                {
                    "name": "Introduction",
                    "content": "The MailBox package is a suite of classes for accessing and managing email folders in a\nfolder-independent manner. This package is an alternative to the \"Mail::Folder\" and \"MIME::*\"\npackages. It abstracts the details of messages, message storage, and message threads, while\nproviding better performance than older mail packages. It is meant to provide an object-oriented\ntoolset for all kinds of e-mail applications, under which Mail User-Agents (MUA) and mail\nfiltering programs.\n\nThis package is modular --parts of it can be used independently of the rest. For example, the\nMail::Box::Manager can automatically determine that a folder is in Mbox format and return an\nobject of the Mail::Box::Mbox class, or the user program can bypass the manager and create\nMail::Box::Mbox objects directly. Similarly, if the user program is only manipulating a single\nmessage, a Mail::Message.\n\nThe Mail::Box package has special features to help MUA's access folder data quickly in random\norder. You will not really benefit (neither slower) if you need the full folder sequentially.\n\nYou may want to have a look at the sample scripts in the \"scripts\" directory.\n"
                },
                {
                    "name": "Distributions",
                    "content": "Up to MailBox v2, all \"Mail::*\" modules were released as a single distribution. From v3, there\nare a few separate distributions in an attempt to reduce the dependencies:\n\n*   Mail::Message\n\n*   Mail::Transfer\n\n*   Mail::Box\n\n*   Mail::Box::IMAP4\n\n*   Mail::Box::POP3\n\n*   Mail::Box::Parser::C\n\nThe names of the classes are not always ideal: the 'Mail' namespace on CPAN is quite full.\n"
                },
                {
                    "name": "The class relations",
                    "content": "Mail::Box::Manager objects play a central role in any program which is built with MailBox. Each\nprogram will create one manager, and then open folders via that manager. Besides folders, the\nmanager can also be used to discover message threads: sequences of messages with their\nfollow-ups.\n\n<has-a>      Mail::Box::Mbox\nMail::Box::Manager <---------*    (Mail::Box::MH)\n^                :         (Mail::Box::Maildir)\n|           (maintains)    (Mail::Box::POP3)\n|                :\n|                :\n`---------------------*  Mail::Box::Thread::Manager\n(<has-a>)\n\nEach folder maintains a list of messages. Much effort is made to hide differences between folder\ntypes and kinds of messages. Your program can be used for MBOX, MH, Maildir, and POP3 folders\nwith no change at all (as long as you stick to the rules).\n\nMail::Box::Mbox  <-----------* Mail::Box::Mbox::Message\n^             <has-a>            ^\n| <isa>                          | <isa>\n|                                |\nMail::Box     ............. Mail::Box::Message\n^\n| <isa>\n|\nMail::Message\n/ \\\n<has-a>\n/     \\\nMail::Message   Mail::Message\n::Body            ::Head\n\nThe situation for MH and Maildir folders is a little more complicated, because they have an\nextra intermediate level of abstraction: Mail::Box::Dir. The POP3 folder has an intermediate\nMail::Box::Net.\n\nIn the future, when more Mbox-like folder types get implemented, there may be a Mail::Box::File\nlevel too. The following is also true for the mail boxes\n\nMB::MH::Message                 MB::POP3::Message\n\\  MB::Maildir::Message            /\n\\         /                      /\n\\       /   MB::Mbox::Message  /\n\\     /         |            /\nMB::Dir::Message  |   MB::Net::Message\n\\    |    /\n\\   |   /\nMB::Message\n|\n|\nMail::Message\n"
                },
                {
                    "name": "The Manager",
                    "content": "The mailbox manager Mail::Box::Manager encapsulates folder management issues. It maintains a set\nof open mail folders (mailboxes), and provides methods for opening and closing them, efficiently\nmoving messages between folders, and efficiently appending messages to folders. It contains\nMail::Box objects which may be of different types. Most folder types can be detected\nautomatically.\n\nThe main manager also manages message-thread detector objects, and informs them when the\ncontents of a folder have changed. This manager class is the only one you instantiate yourself:\nobjects of all other classes will be provided by your folder manager.\n\nYou are strongly advised to use this object, but you can often do without it and open a specific\nfolder-type directly.\n"
                },
                {
                    "name": "The Messages",
                    "content": "Mail::Message\nA base class that defines an interface for manipulating the head and body of a message.\nThere are various header object types (Mail::Message::Head's) and a bunch of body object\ntypes (Mail::Message::Body's).\n\nThe Mail::Message::Construct package is loaded when more complex tasks have to be performed\non messages, like creating replies, bounces, or a forward message. These functionalities are\ndescribed and implemented in the ::Construct file, but are automatically added to the\nMail::Message namespace when used.\n\nMessage types which are foreign to MailBox can be used in the MailBox environment: there are\nsome converters implemented via Mail::Message::Convert. Particularly the popular\nMail::Internet and MIME::Entity are supported.\n\nMail::Box::Message\nAn abstract base class which defines an interface for mail messages which are stored in any\nfolder. It inherits from Mail::Message, and adds the basic idea of *location* to a message.\n\nMail::Message::Body\nThis is the base class for all message bodies. It describes what you can do with any kind of\nbody. The body types differ on the way how the keep the body content during the run of your\nprogram.\n\nOne special case of the body types is the Mail::Message::Body::Multipart, which contains a\nset of Mail::Message::Part objects. These are just like normal messages, except that they\nare contained in an other message. The Mail::Message::Body::Nested body type is comparible,\nbut contains only one message: they are used for \"message/rfc822\" message encodings.\n\nWhen needed, the functionality of the body objects is extended with\nMail::Message::Body::Construct and Mail::Message::Body::Encode. The former package\nimplements things like concatenation, the later controls message encoding and decoding. In\nthe current implementation this is limited to transfer encodings (implemented in the\nMail::Message::TransferEnc packages). Automatic character and mime recodings are on the\nwish-list.\n\nMail::Message::Head\nThe header for a single message. Maintains a set of Mail::Message::Field objects, each\ncontaining one header line. Fields are the only objects which have no logging and tracing\nfacilities, purely for reasons of performance.\n\nThe header object has three sub-classes: the Mail::Message::Head::Complete version knows all\nlines for sure, Mail::Message::Head::Subset maintains an unknown subset of lines, and the\nMail::Message::Head::Delayed has no lines yet but knows where to get them.\n\nThe latter two will automatically get the missing header lines from the mailbox files when\nneeded, and so transform into a \"::Complete\" header. It is fully transparent to the user of\nMailBox in which shape the header really is on the moment.\n"
                },
                {
                    "name": "The Folder types",
                    "content": "Mail::Box\nA base class that defines a standard interface for mail boxes which is independent of\nmailbox type. Objects of this class contain a Mail::Box::Locker and a list of\nMail::Box::Message objects.\n\nMail::Box::Dir\nThe base class for all folders which use a directory organization: each message is a\nseparate entity (file) grouped in a directory. Each Mail::Box::Dir::Message represents one\nmessage, one such entity.\n\nMail::Box::Net\nThe base class for all folders which have the messages outside direct reach of the MailBox\nlibrary, for instance on a remote system, or in a database.\n\nMail::Box::Mbox\nThis class derives from Mail::Box, and implements its interface for mbox-style folders. It\nmaintains a set of Mail::Box::Mbox::Message objects, which are derived from a\nMail::Box::Message.\n\nMbox-style folders have one file containing multiple messages per folder. When folders get\nlarge, access tends to get slow.\n\nMail::Box::MH\nThis class derives from Mail::Box::Dir, and implements its interface for MH-style folders.\nIt maintains a set of Mail::Box::MH::Message objects, which are derived from a\nMail::Box::Dir::Message.\n\nMH-style folders are represented by a directory, where each message is stored in a separate\nfile. The message files are sequentially numbered. It is fast to open one single message,\nbut hard to get an overview.\n\nMail::Box::MH::Index\nThe base class for MH mailbox indexes which provides methods for reading, writing, and\nmanaging message indexes. These indexes are used to speed-up access to directory based\nfolders.\n\nMail::Box::MH::Labels\nAlso for efficiency reasons, a separate file is maintained which contains flags about the\nmessages. This file for instance lists new files. This way, the MH message files do not have\nto be opened to find that out.\n\nMail::Box::Maildir\nLike the MH folder type, this class derives from Mail::Box::Dir. It implements its interface\nfor Maildir-style folders. It maintains a set of Mail::Box::Maildir::Message objects, which\nare derived from a Mail::Box::Dir::Message.\n\nMail::Box::POP3\nImplements the POP3 protocol based on Mail::Box::Net. The Mail::Transport::POP3\nimplementation handles the protocol details. In this kind of folders, you can only read and\ndelete messages.\n"
                },
                {
                    "name": "Various Other Classes",
                    "content": "Mail::Box::Thread::Manager\nMaintains a set of message-threads over one or more folders. A message-thread is a start\nmessage with all the replies on it. And the replies on replies, and so on. This object is\nused to construct the thread for a set of open folders.\n\nThis object maintains linked lists of Mail::Box::Thread::Node objects.\nMail::Message::Dummy's fill-up some holes.\n\nMail::Box::Locker\nProvides a folder locking interface which is inherited by the Mail::Box class. Currently it\nsupports dot-file locking (\"filename.lock\"), flock filehandle locking, and locking over NFS.\nEach is implemented in a separate class. A multi-locker, using a set of lock-methods at the\nsame time is also available.\n\nMail::Box::Search\nThe set of search packages implement various search techniques in an uniformal way. Although\nimplementing your own search algorithm is simple in general, in practice multiparts,\nencodings, and mime-types complicate things.\n\nMail::Box::Parser\nThe parser reads messages, and transforms them into data-structures such that the content of\nheader and body can be used within the program. The first parser is implemented in pure\nPerl. A second parser is under development, and will written in C, to gain speed.\n\nMail::Box::Tie\nProvides hash (Mail::Box::Tie::HASH) or array tied (Mail::Box::Tie::ARRAY) access to any\nmail folder derived from Mail::Box. This beautifies your code in some applications.\n\nMail::Transport\nVarious ways of sending and receiving messages are implemented. Sending is possible via\nexternal programs, like \"mail\", \"Mailx\", \"sendmail\", or autonomously with direct SMTP.\nReceiving is currently only implemented via POP3.\n\nMail::Reporter\nA debugging and logging class which is inherited by most of the Mail:: modules. For each\nobject, you can say what log and error reports must be kept or directly presented to the\nuser. This way you can decide to have Mail::Box report about problems, or do it all\nyourself.\n\nAll classes are written to be extensible.\n"
                }
            ]
        },
        "SEE ALSO": {
            "content": "This module is part of Mail-Box distribution version 3.009, built on August 18, 2020. Website:\nhttp://perl.overmeer.net/CPAN/\n",
            "subsections": []
        },
        "LICENSE": {
            "content": "Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see ChangeLog.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself. See http://dev.perl.org/licenses/\n",
            "subsections": []
        }
    },
    "summary": "Mail::Box-Overview - objects used by Mail::Box",
    "flags": [],
    "examples": [],
    "see_also": []
}