1Mail::Box-Overview(3) User Contributed Perl DocumentationMail::Box-Overview(3)
2
6 Mail::Box-Overview - objects used by Mail::Box
7
9 Introduction
10 The MailBox package is a suite of classes for accessing and managing
11 email folders in a folder-independent manner. This package is an
12 alternative to the "Mail::Folder" and "MIME::*" packages. It abstracts
13 the details of messages, message storage, and message threads, while
14 providing better performance than older mail packages. It is meant to
15 provide an object-oriented toolset for all kinds of e-mail
16 applications, under which Mail User-Agents (MUA) and mail filtering
17 programs.
18 This package is modular --parts of it can be used independently of the
20 rest. For example, the Mail::Box::Manager can automatically determine
21 that a folder is in Mbox format and return an object of the
22 Mail::Box::Mbox class, or the user program can bypass the manager and
23 create Mail::Box::Mbox objects directly. Similarly, if the user program
24 is only manipulating a single message, a Mail::Message.
25 The Mail::Box package has special features to help MUA's access folder
27 data quickly in random order. You will not really benefit (neither
28 slower) if you need the full folder sequentially.
29 You may want to have a look at the sample scripts in the "scripts"
31 directory.
32 The class relations
34 Mail::Box::Manager objects play a central role in any program which is
35 built with MailBox. Each program will create one manager, and then
36 open folders via that manager. Besides folders, the manager can also
37 be used to discover message threads: sequences of messages with their
38 follow-ups.
39 <has-a> Mail::Box::Mbox
41 Mail::Box::Manager <---------* (Mail::Box::MH)
42 ^ : (Mail::Box::Maildir)
43 | (maintains) (Mail::Box::POP3)
44 | :
45 | :
46 `---------------------* Mail::Box::Thread::Manager
47 (<has-a>)
48 Each folder maintains a list of messages. Much effort is made to hide
50 differences between folder types and kinds of messages. Your program
51 can be used for MBOX, MH, Maildir, and POP3 folders with no change at
52 all (as long as you stick to the rules).
53 Mail::Box::Mbox <-----------* Mail::Box::Mbox::Message
55 ^ <has-a> ^
56 | <isa> | <isa>
57 | |
58 Mail::Box ............. Mail::Box::Message
59 ^
60 | <isa>
61 |
62 Mail::Message
63 / \
64 <has-a>
65 / \
66 Mail::Message Mail::Message
67 ::Body ::Head
68 The situation for MH and Maildir folders is a little more complicated,
70 because they have an extra intermediate level of abstraction:
71 Mail::Box::Dir. The POP3 folder has an intermediate Mail::Box::Net.
72 In the future, when more Mbox-like folder types get implemented, there
74 may be a Mail::Box::File level too. The following is also true for the
75 mail boxes
76 MB::MH::Message MB::POP3::Message
78 \ MB::Maildir::Message /
79 \ / /
80 \ / MB::Mbox::Message /
81 \ / | /
82 MB::Dir::Message | MB::Net::Message
83 \ | /
84 \ | /
85 MB::Message
86 |
87 |
88 Mail::Message
89 The Manager
91 The mailbox manager Mail::Box::Manager encapsulates folder management
92 issues. It maintains a set of open mail folders (mailboxes), and
93 provides methods for opening and closing them, efficiently moving
94 messages between folders, and efficiently appending messages to
95 folders. It contains Mail::Box objects which may be of different
96 types. Most folder types can be detected automatically.
97 The main manager also manages message-thread detector objects, and
99 informs them when the contents of a folder have changed. This manager
100 class is the only one you instantiate yourself: objects of all other
101 classes will be provided by your folder manager.
102 You are strongly advised to use this object, but you can often do
104 without it and open a specific folder-type directly.
105 The Messages
107 Mail::Message
108 A base class that defines an interface for manipulating the head
109 and body of a message. There are various header object types
110 (Mail::Message::Head's) and a bunch of body object types
111 (Mail::Message::Body's).
112 The Mail::Message::Construct package is loaded when more complex
114 tasks have to be performed on messages, like creating replies,
115 bounces, or a forward message. These functionalities are described
116 and implemented in the ::Construct file, but are automatically
117 added to the Mail::Message namespace when used.
118 Message types which are foreign to MailBox can be used in the
120 MailBox environment: there are some converters implemented via
121 Mail::Message::Convert. Particularly the popular Mail::Internet
122 and MIME::Entity are supported.
123 Mail::Box::Message
125 An abstract base class which defines an interface for mail messages
126 which are stored in any folder. It inherits from Mail::Message,
127 and adds the basic idea of location to a message.
128 Mail::Message::Body
130 This is the base class for all message bodies. It describes what
131 you can do with any kind of body. The body types differ on the way
132 how the keep the body content during the run of your program.
133 One special case of the body types is the
135 Mail::Message::Body::Multipart, which contains a set of
136 Mail::Message::Part objects. These are just like normal messages,
137 except that they are contained in an other message. The
138 Mail::Message::Body::Nested body type is comparible, but contains
139 only one message: they are used for "message/rfc822" message
140 encodings.
141 When needed, the functionality of the body objects is extended with
143 Mail::Message::Body::Construct and Mail::Message::Body::Encode.
144 The former package implements things like concatenation, the later
145 controls message encoding and decoding. In the current
146 implementation this is limited to transfer encodings (implemented
147 in the Mail::Message::TransferEnc packages). Automatic character
148 and mime recodings are on the wish-list.
149 Mail::Message::Head
151 The header for a single message. Maintains a set of
152 Mail::Message::Field objects, each containing one header line.
153 Fields are the only objects which have no logging and tracing
154 facilities, purely for reasons of performance.
155 The header object has three sub-classes: the
157 Mail::Message::Head::Complete version knows all lines for sure,
158 Mail::Message::Head::Subset maintains an unknown subset of lines,
159 and the Mail::Message::Head::Delayed has no lines yet but knows
160 where to get them.
161 The latter two will automatically get the missing header lines from
163 the mailbox files when needed, and so transform into a "::Complete"
164 header. It is fully transparent to the user of MailBox in which
165 shape the header really is on the moment.
166 The Folder types
168 Mail::Box
169 A base class that defines a standard interface for mail boxes which
170 is independent of mailbox type. Objects of this class contain a
171 Mail::Box::Locker and a list of Mail::Box::Message objects.
172 Mail::Box::Dir
174 The base class for all folders which use a directory organization:
175 each message is a separate entity (file) grouped in a directory.
176 Each Mail::Box::Dir::Message represents one message, one such
177 entity.
178 Mail::Box::Net
180 The base class for all folders which have the messages outside
181 direct reach of the MailBox library, for instance on a remote
182 system, or in a database.
183 Mail::Box::Mbox
185 This class derives from Mail::Box, and implements its interface for
186 mbox-style folders. It maintains a set of Mail::Box::Mbox::Message
187 objects, which are derived from a Mail::Box::Message.
188 Mbox-style folders have one file containing multiple messages per
190 folder. When folders get large, access tends to get slow.
191 Mail::Box::MH
193 This class derives from Mail::Box::Dir, and implements its
194 interface for MH-style folders. It maintains a set of
195 Mail::Box::MH::Message objects, which are derived from a
196 Mail::Box::Dir::Message.
197 MH-style folders are represented by a directory, where each message
199 is stored in a separate file. The message files are sequentially
200 numbered. It is fast to open one single message, but hard to get
201 an overview.
202 Mail::Box::MH::Index
204 The base class for MH mailbox indexes which provides methods for
205 reading, writing, and managing message indexes. These indexes are
206 used to speed-up access to directory based folders.
207 Mail::Box::MH::Labels
209 Also for efficiency reasons, a separate file is maintained which
210 contains flags about the messages. This file for instance lists
211 new files. This way, the MH message files do not have to be opened
212 to find that out.
213 Mail::Box::Maildir
215 Like the MH folder type, this class derives from Mail::Box::Dir.
216 It implements its interface for Maildir-style folders. It maintains
217 a set of Mail::Box::Maildir::Message objects, which are derived
218 from a Mail::Box::Dir::Message.
219 Mail::Box::POP3
221 Implements the POP3 protocol based on Mail::Box::Net. The
222 Mail::Transport::POP3 implementation handles the protocol details.
223 In this kind of folders, you can only read and delete messages.
224 Various Other Classes
226 Mail::Box::Thread::Manager
227 Maintains a set of message-threads over one or more folders. A
228 message-thread is a start message with all the replies on it. And
229 the replies on replies, and so on. This object is used to
230 construct the thread for a set of open folders.
231 This object maintains linked lists of Mail::Box::Thread::Node
233 objects. Mail::Message::Dummy's fill-up some holes.
234 Mail::Box::Locker
236 Provides a folder locking interface which is inherited by the
237 Mail::Box class. Currently it supports dot-file locking
238 ("filename.lock"), flock filehandle locking, and locking over NFS.
239 Each is implemented in a separate class. A multi-locker, using a
240 set of lock-methods at the same time is also available.
241 Mail::Box::Search
243 The set of search packages implement various search techniques in
244 an uniformal way. Although implementing your own search algorithm
245 is simple in general, in practice multiparts, encodings, and mime-
246 types complicate things.
247 Mail::Box::Parser
249 The parser reads messages, and transforms them into data-structures
250 such that the content of header and body can be used within the
251 program. The first parser is implemented in pure Perl. A second
252 parser is under development, and will written in C, to gain speed.
253 Mail::Box::Tie
255 Provides hash (Mail::Box::Tie::HASH) or array tied
256 (Mail::Box::Tie::ARRAY) access to any mail folder derived from
257 Mail::Box. This beautifies your code in some applications.
258 Mail::Transport
260 Various ways of sending and receiving messages are implemented.
261 Sending is possible via external programs, like "mail", "Mailx",
262 "sendmail", or autonomously with direct SMTP. Receiving is
263 currently only implemented via POP3.
264 Mail::Reporter
266 A debugging and logging class which is inherited by most of the
267 Mail:: modules. For each object, you can say what log and error
268 reports must be kept or directly presented to the user. This way
269 you can decide to have Mail::Box report about problems, or do it
270 all yourself.
271 All classes are written to be extensible.
273
275 This module is part of Mail-Box distribution version 2.097, built on
276 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
277
279 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
280 ChangeLog.
281 This program is free software; you can redistribute it and/or modify it
283 under the same terms as Perl itself. See
284 http://www.perl.com/perl/misc/Artistic.html
285perl v5.12.3 2011-01-26 Mail::Box-Overview(3)