README Mail::Box v2 The Mail::Box folder is a modern mail-folder manager -- at least at the moment of this writing ;) It is written to replace Mail::Folder, although it interface is different. The most important modules are Mail::Box::Manager, Mail::Box, and Mail::Message. Their documentation explain the features in more detail than this document. The Mail::Box-Overview page describe each set of modules in more detail. Other descriptive documents in this module: README.FAQ Frequently asked questions README.plans Design for Mail::Box v2.0 README.status Detailed status of current implementation README.todo Thoughts about possible extensions README.doc_updates Keeps track on full doc reviews, most of it the work of David Coppit Mail::Box version 1.xxx runs on perl 5.005 and up Mail::Box version 2.xxx is much faster and more flexible, but only runs on perl 5.6.0 and up. It is not fully compatible with previous versions, although conversion will usually not be too hard. ===== Contributors A full list of contributors can be found in the Changelog, but a few people have to mentioned in special: * Mark Overmeer - 99% of the code - initial version of documentation * David Coppit - massive corrections and additions in all documentation - many valid suggestions to the design and parts of the implementation -- and some invalid ones ;) -- you really must know what you are talking about to convince stubern Mark. * Tassilo von Parseval - scripts/takemail - suggestions how to cope with the problems in MIME::Parser. ===== Status Although the implementation of Mail::Box is young, it already has a large number of features. See the file README.status to see what has been tested and what hasn't. Version 1.300 contained 300 tests, but that is certainly not sufficient to call the module `well tested'. Version 2.01 has over 500 tests, which is quite ok. Mail Box version 2.01 contains close to 1900 tests, contains 7000 lines of pure code in 64 packages. ===== Features = AUTOLOAD messages. The Mail::Box modules try to keep messages stored in the mailbox file(s) for as long as possible. The message is read from file and parsed only if the user really needs the contents of the message. This is called 'delay loading'. Demand- or delayed-loading of messages is implemented using the standard AUTOLOAD mechanism, which means that it is not visible to the user of the folder! This mechanism also reduces the memory footprint of the program enormously. For some folder types, not only the content (body) of the message is delayed, but even the header. In those cases, the opening of a folder is just counting the messages: really fast. The implementation also avoids parsing and then unparsing mail messages. If you read from a folder, then use it and write to it to a different folder, unmodified messages are not reformated from memory. Instead they are copied from the old folder into a new one byte-by-byte. When you open a folder with 1000 messages, and modify two messages, only those two get parsed and recomposed. All 998 other messages are simple byte-by-byte copied into the replacement file. = Support for various folder types Currently supported: * Mbox folders, see Mail::Box::Mbox One file per folder, with many messages in each file. * MH folders, see Mail::Box::MH One directory per folder, with each message in a seperate file. See STATUS for my wishlist of supported folder types. = Support for message thread construction The current implementation has a very basic message thread construction algorithm. At the moment, only the In-Reply-To and the References fields are taken into account. This could be optimized, for instance by looking at the subject. Read more about threading in Mail::Box::Threads. = Various kinds of locking There are three kinds of locking: * Locking via a .lock (dotlock) file. * Locking using flock (mbox folders only) * Locking via a .lock (dotlock) file which is NFS-safe. Read more about locking in Mail::Box::Locker. = Managing folders A special folder manager was designed to keep track of opened folders. This is the main object that most users will use. (Read its documentation Mail::Box::Manager before trying anything else.) = Tied access If you like, you can tie a folder to an array, and use it that way. See Mail::Box::Tie. ===== Differences with Mail::Folder The popular Mail::Folder package has been around for many years. It is written to use Mail::Internet, instead of the more powerful MIME::Entity messages. But Mail::Message objects are even more flexible. Mail::Folder does not support discussion thread detection, nor autoloading of message data. Therefore, it is much slower in accessing the folders. Another major difference is that the object structure of Mail::Folder is less clear than that of Mail::Box. The supported mailbox types are seperately implemented and share less code than they could. The folders manage themselves instead of being managed by a separate folder manager object. ====== Author: Mark Overmeer mailbox@overmeer.net