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 Distributions
34 Up to MailBox v2, all "Mail::*" modules were released as a single
35 distribution. From v3, there are a few separate distributions in an
36 attempt to reduce the dependencies:
37 • Mail::Message
39 • Mail::Transfer
41 • Mail::Box
43 • Mail::Box::IMAP4
45 • Mail::Box::POP3
47 • Mail::Box::Parser::C
49 The names of the classes are not always ideal: the 'Mail' namespace on
51 CPAN is quite full.
52 The class relations
54 Mail::Box::Manager objects play a central role in any program which is
55 built with MailBox. Each program will create one manager, and then
56 open folders via that manager. Besides folders, the manager can also
57 be used to discover message threads: sequences of messages with their
58 follow-ups.
59 <has-a> Mail::Box::Mbox
61 Mail::Box::Manager <---------* (Mail::Box::MH)
62 ^ : (Mail::Box::Maildir)
63 | (maintains) (Mail::Box::POP3)
64 | :
65 | :
66 `---------------------* Mail::Box::Thread::Manager
67 (<has-a>)
68 Each folder maintains a list of messages. Much effort is made to hide
70 differences between folder types and kinds of messages. Your program
71 can be used for MBOX, MH, Maildir, and POP3 folders with no change at
72 all (as long as you stick to the rules).
73 Mail::Box::Mbox <-----------* Mail::Box::Mbox::Message
75 ^ <has-a> ^
76 | <isa> | <isa>
77 | |
78 Mail::Box ............. Mail::Box::Message
79 ^
80 | <isa>
81 |
82 Mail::Message
83 / \
84 <has-a>
85 / \
86 Mail::Message Mail::Message
87 ::Body ::Head
88 The situation for MH and Maildir folders is a little more complicated,
90 because they have an extra intermediate level of abstraction:
91 Mail::Box::Dir. The POP3 folder has an intermediate Mail::Box::Net.
92 In the future, when more Mbox-like folder types get implemented, there
94 may be a Mail::Box::File level too. The following is also true for the
95 mail boxes
96 MB::MH::Message MB::POP3::Message
98 \ MB::Maildir::Message /
99 \ / /
100 \ / MB::Mbox::Message /
101 \ / | /
102 MB::Dir::Message | MB::Net::Message
103 \ | /
104 \ | /
105 MB::Message
106 |
107 |
108 Mail::Message
109 The Manager
111 The mailbox manager Mail::Box::Manager encapsulates folder management
112 issues. It maintains a set of open mail folders (mailboxes), and
113 provides methods for opening and closing them, efficiently moving
114 messages between folders, and efficiently appending messages to
115 folders. It contains Mail::Box objects which may be of different
116 types. Most folder types can be detected automatically.
117 The main manager also manages message-thread detector objects, and
119 informs them when the contents of a folder have changed. This manager
120 class is the only one you instantiate yourself: objects of all other
121 classes will be provided by your folder manager.
122 You are strongly advised to use this object, but you can often do
124 without it and open a specific folder-type directly.
125 The Messages
127 Mail::Message
128 A base class that defines an interface for manipulating the head
129 and body of a message. There are various header object types
130 (Mail::Message::Head's) and a bunch of body object types
131 (Mail::Message::Body's).
132 The Mail::Message::Construct package is loaded when more complex
134 tasks have to be performed on messages, like creating replies,
135 bounces, or a forward message. These functionalities are described
136 and implemented in the ::Construct file, but are automatically
137 added to the Mail::Message namespace when used.
138 Message types which are foreign to MailBox can be used in the
140 MailBox environment: there are some converters implemented via
141 Mail::Message::Convert. Particularly the popular Mail::Internet
142 and MIME::Entity are supported.
143 Mail::Box::Message
145 An abstract base class which defines an interface for mail messages
146 which are stored in any folder. It inherits from Mail::Message,
147 and adds the basic idea of location to a message.
148 Mail::Message::Body
150 This is the base class for all message bodies. It describes what
151 you can do with any kind of body. The body types differ on the way
152 how the keep the body content during the run of your program.
153 One special case of the body types is the
155 Mail::Message::Body::Multipart, which contains a set of
156 Mail::Message::Part objects. These are just like normal messages,
157 except that they are contained in an other message. The
158 Mail::Message::Body::Nested body type is comparible, but contains
159 only one message: they are used for "message/rfc822" message
160 encodings.
161 When needed, the functionality of the body objects is extended with
163 Mail::Message::Body::Construct and Mail::Message::Body::Encode.
164 The former package implements things like concatenation, the later
165 controls message encoding and decoding. In the current
166 implementation this is limited to transfer encodings (implemented
167 in the Mail::Message::TransferEnc packages). Automatic character
168 and mime recodings are on the wish-list.
169 Mail::Message::Head
171 The header for a single message. Maintains a set of
172 Mail::Message::Field objects, each containing one header line.
173 Fields are the only objects which have no logging and tracing
174 facilities, purely for reasons of performance.
175 The header object has three sub-classes: the
177 Mail::Message::Head::Complete version knows all lines for sure,
178 Mail::Message::Head::Subset maintains an unknown subset of lines,
179 and the Mail::Message::Head::Delayed has no lines yet but knows
180 where to get them.
181 The latter two will automatically get the missing header lines from
183 the mailbox files when needed, and so transform into a "::Complete"
184 header. It is fully transparent to the user of MailBox in which
185 shape the header really is on the moment.
186 The Folder types
188 Mail::Box
189 A base class that defines a standard interface for mail boxes which
190 is independent of mailbox type. Objects of this class contain a
191 Mail::Box::Locker and a list of Mail::Box::Message objects.
192 Mail::Box::Dir
194 The base class for all folders which use a directory organization:
195 each message is a separate entity (file) grouped in a directory.
196 Each Mail::Box::Dir::Message represents one message, one such
197 entity.
198 Mail::Box::Net
200 The base class for all folders which have the messages outside
201 direct reach of the MailBox library, for instance on a remote
202 system, or in a database.
203 Mail::Box::Mbox
205 This class derives from Mail::Box, and implements its interface for
206 mbox-style folders. It maintains a set of Mail::Box::Mbox::Message
207 objects, which are derived from a Mail::Box::Message.
208 Mbox-style folders have one file containing multiple messages per
210 folder. When folders get large, access tends to get slow.
211 Mail::Box::MH
213 This class derives from Mail::Box::Dir, and implements its
214 interface for MH-style folders. It maintains a set of
215 Mail::Box::MH::Message objects, which are derived from a
216 Mail::Box::Dir::Message.
217 MH-style folders are represented by a directory, where each message
219 is stored in a separate file. The message files are sequentially
220 numbered. It is fast to open one single message, but hard to get
221 an overview.
222 Mail::Box::MH::Index
224 The base class for MH mailbox indexes which provides methods for
225 reading, writing, and managing message indexes. These indexes are
226 used to speed-up access to directory based folders.
227 Mail::Box::MH::Labels
229 Also for efficiency reasons, a separate file is maintained which
230 contains flags about the messages. This file for instance lists
231 new files. This way, the MH message files do not have to be opened
232 to find that out.
233 Mail::Box::Maildir
235 Like the MH folder type, this class derives from Mail::Box::Dir.
236 It implements its interface for Maildir-style folders. It maintains
237 a set of Mail::Box::Maildir::Message objects, which are derived
238 from a Mail::Box::Dir::Message.
239 Mail::Box::POP3
241 Implements the POP3 protocol based on Mail::Box::Net. The
242 Mail::Transport::POP3 implementation handles the protocol details.
243 In this kind of folders, you can only read and delete messages.
244 Various Other Classes
246 Mail::Box::Thread::Manager
247 Maintains a set of message-threads over one or more folders. A
248 message-thread is a start message with all the replies on it. And
249 the replies on replies, and so on. This object is used to
250 construct the thread for a set of open folders.
251 This object maintains linked lists of Mail::Box::Thread::Node
253 objects. Mail::Message::Dummy's fill-up some holes.
254 Mail::Box::Locker
256 Provides a folder locking interface which is inherited by the
257 Mail::Box class. Currently it supports dot-file locking
258 ("filename.lock"), flock filehandle locking, and locking over NFS.
259 Each is implemented in a separate class. A multi-locker, using a
260 set of lock-methods at the same time is also available.
261 Mail::Box::Search
263 The set of search packages implement various search techniques in
264 an uniformal way. Although implementing your own search algorithm
265 is simple in general, in practice multiparts, encodings, and mime-
266 types complicate things.
267 Mail::Box::Parser
269 The parser reads messages, and transforms them into data-structures
270 such that the content of header and body can be used within the
271 program. The first parser is implemented in pure Perl. A second
272 parser is under development, and will written in C, to gain speed.
273 Mail::Box::Tie
275 Provides hash (Mail::Box::Tie::HASH) or array tied
276 (Mail::Box::Tie::ARRAY) access to any mail folder derived from
277 Mail::Box. This beautifies your code in some applications.
278 Mail::Transport
280 Various ways of sending and receiving messages are implemented.
281 Sending is possible via external programs, like "mail", "Mailx",
282 "sendmail", or autonomously with direct SMTP. Receiving is
283 currently only implemented via POP3.
284 Mail::Reporter
286 A debugging and logging class which is inherited by most of the
287 Mail:: modules. For each object, you can say what log and error
288 reports must be kept or directly presented to the user. This way
289 you can decide to have Mail::Box report about problems, or do it
290 all yourself.
291 All classes are written to be extensible.
293
295 This module is part of Mail-Box distribution version 3.009, built on
296 August 18, 2020. Website: http://perl.overmeer.net/CPAN/
297
299 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
300 ChangeLog.
301 This program is free software; you can redistribute it and/or modify it
303 under the same terms as Perl itself. See http://dev.perl.org/licenses/
304perl v5.36.0 2023-01-20 Mail::Box-Overview(3)