1Mail::Box-Overview(3) User Contributed Perl DocumentationMail::Box-Overview(3)
2
3
4

NAME

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

DESCRIPTION

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
19       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
26       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
30       You may want to have a look at the sample scripts in the "scripts"
31       directory.
32
33   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
38       •   Mail::Message
39
40       •   Mail::Transfer
41
42       •   Mail::Box
43
44       •   Mail::Box::IMAP4
45
46       •   Mail::Box::POP3
47
48       •   Mail::Box::Parser::C
49
50       The names of the classes are not always ideal: the 'Mail' namespace on
51       CPAN is quite full.
52
53   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
60                              <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
69       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
74        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
89       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
93       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
97        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
110   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
118       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
123       You are strongly advised to use this object, but you can often do
124       without it and open a specific folder-type directly.
125
126   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
133           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
139           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
144       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
149       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
154           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
162           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
170       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
176           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
182           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
187   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
193       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
199       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
204       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
209           Mbox-style folders have one file containing multiple messages per
210           folder.  When folders get large, access tends to get slow.
211
212       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
218           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
223       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
228       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
234       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
240       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
245   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
252           This object maintains linked lists of Mail::Box::Thread::Node
253           objects.  Mail::Message::Dummy's fill-up some holes.
254
255       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
262       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
268       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
274       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
279       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
285       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
292       All classes are written to be extensible.
293

SEE ALSO

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

LICENSE

299       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
300       ChangeLog.
301
302       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/
304
305
306
307perl v5.34.0                      2022-01-21             Mail::Box-Overview(3)
Impressum