1Mail::Box::Manager(3) User Contributed Perl DocumentationMail::Box::Manager(3)
2
6 Mail::Box::Manager - manage a set of folders
7
9 Mail::Box::Manager
10 is a Mail::Reporter
11 Mail::Box::Manager is extended by
13 Mail::Box::Manage::User
14
16 use Mail::Box::Manager;
17 my $mgr = new Mail::Box::Manager;
18 # Create folder objects.
20 my $folder = $mgr->open(folder => $ENV{MAIL});
21 my $message1 = $folder->message(0);
22 $mgr->copyMessage('Draft', $message);
23 my @messages = $folder->message(0,3);
25 $mgr->moveMessage('Outbox', @messages, create => 1 );
26 $mgr->close($folder);
27 # Create thread-detectors (see Mail::Box::Thread::Manager)
29 my $t = $mgr->threads($inbox, $outbox);
30 my $threads = $mgr->threads(folder => $folder);
32 foreach my $thread ($threads->all)
33 { $thread->print;
34 }
35 $mgr->registerType(mbox => 'Mail::Box::MyType');
37
39 The manager keeps track on a set of open folders and a set of message-
40 thread supporting objects. You are not obliged to use this object (you
41 can directly create a Mail::Box::Mbox if you prefer), but you will
42 create more portable and safer code if you do use it.
43
45 Constructors
46 Mail::Box::Manager->new(ARGS)
47 -Option --Defined in --Default
48 autodetect undef
49 default_folder_type 'mbox'
50 folder_types <all standard types>
51 folderdir [ '.' ]
52 folderdirs <synonym for C<folderdir>>
53 log Mail::Reporter 'WARNINGS'
54 trace Mail::Reporter 'WARNINGS'
55 autodetect => TYPE|ARRAY-OF-TYPES
57 Select only a subset of the folder types which are implemented by
58 MailBox to be detected automatically. This may improve the auto-
59 detection of folder types. Normally, all folder types will be
60 tried when a folder's name is incorrect, but this option limits
61 the types which are checked and therefore may respond faster.
62 default_folder_type => NAME|CLASS
64 Specifies the default folder type for newly created folders. If
65 this option is not specified, the most recently registered type
66 is used (see registerType() and the new(folder_types) option.
67 folder_types => NEW-TYPE | ARRAY-OF-NEW-TYPES
69 Add one or more new folder types to the list of known types. The
70 order is important: when you open a file without specifying its
71 type, the manager will start trying the last added list of types,
72 in order.
73 Each TYPE is specified as an array which contains name, class,
75 and defaults for options which overrule the usual defaults. You
76 may specify folder-specific defaults as OPTIONS. They override
77 the settings of the manager.
78 folderdir => DIRECTORY
80 The default directory, or directories, where folders are located.
81 The "Mail::Box::Manager" can autodetect the existing folder-
82 types. There may be different kinds of folders opened at the
83 same time, and messages can be moved between those types,
84 although that may result in a loss of information depending on
85 the folder types.
86 folderdirs => [DIRECTORIES]
88 log => LEVEL
89 trace => LEVEL
90 Attributes
92 $obj->defaultFolderType
93 Returns the default folder type, some class name.
94 $obj->folderTypes
96 Returns the list of currently defined folder types.
97 example:
99 print join("\n", $manager->folderTypes), "\n";
101 $obj->folderdir
103 In list context, this returns all folderdirs specified. In SCALAR
104 context only the first.
105 $obj->registerType(TYPE, CLASS [,OPTIONS])
107 With "registerType" you can register one TYPE of folders. The
108 CLASS is compiled automatically, so you do not need to "use" them
109 in your own modules. The TYPE is just an arbitrary name.
110 The added types are prepended to the list of known types, so they
112 are checked first when a folder is opened in autodetect mode.
113 example:
115 $manager->registerType(mbox => 'Mail::Box::Mbox',
117 save_on_exit => 0, folderdir => '/tmp');
118 Manage open folders
120 $obj->close(FOLDER, OPTIONS)
121 "close" removes the specified folder from the list of open folders.
122 Indirectly it will update the files on disk if needed (depends on
123 the Mail::Box::new(save_on_exit) flag for each folder). OPTIONS are
124 passed to Mail::Box::close() of the folder.
125 The folder's messages will also be withdrawn from the known message
127 threads. You may also close the folder directly. The manager will
128 be informed about this event and take appropriate actions.
129 -Option --Default
131 close_by_self <false>
132 close_by_self => BOOLEAN
134 Used internally to avoid confusion about how the close was
135 started. Do not change this.
136 example:
138 my $inbox = $mgr->open('inbox');
140 $mgr->close($inbox);
141 $inbox->close; # alternative
142 $obj->closeAllFolders(, OPTIONS)
144 "closeAllFolders" calls close() for each folder managed by this
145 object. It is called just before the program stops (before global
146 cleanup).
147 $obj->isOpenFolder(FOLDER)
149 Returns true if the FOLDER is currently open.
150 example:
152 print "Yes\n" if $mgr->isOpenFolder('Inbox');
154 $obj->open([FOLDERNAME], OPTIONS)
156 Open a folder which name is specified as first parameter or with
157 the option flag "folder". The folder type is autodetected unless
158 the "type" is specified.
159 "open" carries options for the manager which are described here,
161 but may also have additional options for the folder type. For a
162 description of the folder options, see the options to the
163 constructor Mail::Box::new() for each type of mail box.
164 -Option --Default
166 authenticate 'AUTO'
167 create <false>
168 folder $ENV{MAIL}
169 folderdir '.'
170 type <first, usually C<mbox>>
171 authenticate => TYPE|ARRAY-OF-TYPES|'AUTO'
173 The TYPE of authentication to be used, or a list of TYPES which
174 the client prefers. The server may provide preferences as well,
175 and that order will be kept. This option is only supported by a
176 small subset of folder types, especially by POP and IMAP.
177 create => BOOLEAN
179 Create the folder if it does not exist. By default, this is not
180 done. The "type" option specifies which type of folder is
181 created.
182 folder => NAME|URL
184 Which folder to open, specified by NAME or special URL. The URL
185 format is composed as
186 type://username:password@hostname:port/foldername
188 Like real URLs, all fields are optional and have smart defaults,
190 as long as the string starts with a known folder type. Far from
191 all folder types support all these options, but at least they are
192 always split-out. Be warned that special characters in the
193 password should be properly url-encoded.
194 When you specify anything which does not match the URL format, it
196 is passed directly to the "new" method of the folder which is
197 opened.
198 folderdir => DIRECTORY
200 The directory where the folders are usually stored.
201 type => FOLDERTYPENAME|FOLDERTYPE
203 Specify the type of the folder. If you do not specify this
204 option while opening a folder for reading, the manager checks all
205 registered folder types in order for the ability to open the
206 folder. If you open a new folder for writing, then the default
207 will be the most recently registered type. (If you add more than
208 one type at once, the first of the list is used.)
209 example: opening folders via the manager
211 my $jack = $manager->open(folder => '=jack',
213 type => 'mbox');
214 my $rcvd = $manager->open('myMail',
216 type => 'Mail::Box::Mbox', access => 'rw');
217 my $inbox = $manager->open('Inbox')
219 or die "Cannot open Inbox.\n";
220 my $pop = 'pop3://myself:secret@pop3.server.com:120/x';
222 my $send = $manager->open($url);
223 my $send = $manager->open(folder => '/x',
225 type => 'pop3', username => 'myself', password => 'secret'
226 server_name => 'pop3.server.com', server_port => '120');
227 $obj->openFolders
229 Returns a list of all open folders.
230 Manage existing folders
232 $obj->delete(FOLDERNAME, OPTIONS)
233 Remove the named folder. The OPTIONS are the same as those for
234 open().
235 The deletion of a folder can take some time. Dependent on the type
237 of folder, the folder must be read first. For some folder-types
238 this will be fast.
239 -Option --Default
241 recursive <folder's default>
242 recursive => BOOLEAN
244 Some folder can only be recursively deleted, other have more
245 flexibility.
246 Move messages to folders
248 $obj->appendMessage([FOLDER|FOLDERNAME,] MESSAGES, OPTIONS)
249 Append one or more messages to a folder (therefore, an
250 "appendMessages()" is defined as well). You may specify a
251 FOLDERNAME or an opened folder as the first argument. When the name
252 is that of an open folder, it is treated as if the folder-object
253 was specified, and not directly access the folder-files. You may
254 also specify the foldername as part of the options list.
255 If a message is added to an already opened folder, it is only added
257 to the structure internally in the program. The data will not be
258 written to disk until a write of that folder takes place. When the
259 name of an unopened folder is given, the folder is opened, the
260 messages stored on disk, and then the folder is closed.
261 A message must be an instance of a Mail::Message. The actual
263 message type does not have to match the folder type--the folder
264 will try to resolve the differences with minimal loss of
265 information. The coerced messages (how the were actually written)
266 are returned as list.
267 The OPTIONS is a list of key/values, which are added to
269 (overriding) the default options for the detected folder type.
270 example:
272 $mgr->appendMessage('=send', $message, folderdir => '/');
274 $mgr->appendMessage($received, $inbox->messages);
275 my @appended = $mgr->appendMessages($inbox->messages,
277 folder => 'Drafts');
278 $_->label(seen => 1) foreach @appended;
279 $obj->copyMessage([FOLDER|FOLDERNAME,] MESSAGES, OPTIONS)
281 Copy a message from one folder into another folder. If the
282 destination folder is already opened, Mail::Box::copyTo() is used.
283 Otherwise, Mail::Box::appendMessages() is called.
284 You need to specify a folder's name or folder object as the first
286 argument, or in the options list. The options are the same as
287 those which can be specified when opening a folder.
288 -Option--Default
290 share <false>
291 share => BOOLEAN
293 Try to share the physical storage of the messages. The folder
294 types may be different, but it all depends on the actual folder
295 where the message is copied to. Silently ignored when not
296 possible to share.
297 example:
299 my $drafts = $mgr->open(folder => 'Drafts');
301 my $outbox = $mgr->open(folder => 'Outbox');
302 $mgr->copyMessage($outbox, $drafts->message(0));
303 my @messages = $drafts->message(1,2);
305 $mgr->copyMessage('=Trash', @messages,
306 folderdir => '/tmp', create => 1);
307 $mgr->copyMessage($drafts->message(1),
309 folder => '=Drafts' folderdir => '/tmp',
310 create => 1);
311 $obj->moveMessage([FOLDER|FOLDERNAME,] MESSAGES, OPTIONS)
313 Move a message from one folder to another.
314 BE WARNED that removals from a folder only take place when the
316 folder is closed, so the message is only flagged to be deleted in
317 the opened source folder.
318 BE WARNED that message labels may get lost when a message is moved
320 from one folder type to an other. An attempt is made to translate
321 labels, but there are many differences in interpretation by
322 applications.
323 $mgr->moveMessage($received, $inbox->message(1))
325 is equivalent to
327 $mgr->copyMessage($received, $inbox->message(1), share => 1);
329 $inbox->message(1)->delete;
330 -Option--Default
332 share <true>
333 share => BOOLEAN
335 Manage message threads
337 $obj->threads([FOLDERS], OPTIONS)
338 Create a new object which keeps track of message threads. You can
339 read about the possible options in Mail::Box::Thread::Manager. As
340 OPTIONS specify one folder or an array of FOLDERS. It is also
341 permitted to specify folders before the options.
342 example:
344 my $t1 = $mgr->threads(folders => [ $inbox, $send ]);
346 my $t2 = $mgr->threads($inbox);
347 my $t3 = $mgr->threads($inbox, $send);
348 Internals
350 $obj->decodeFolderURL(URL)
351 Try to decompose a folder name which is specified as URL (see
352 open()) into separate options. Special characters like @-sign,
353 colon, and slash used in the user or password parts must be passed
354 URL-encoded.
355 $obj->toBeThreaded(FOLDER, MESSAGES)
357 Signal to the manager that all thread managers which are using the
358 specified folder must be informed that new messages are coming in.
359 $obj->toBeUnthreaded(FOLDER, MESSAGES)
361 Signal to the manager that all thread managers which are using the
362 specified folder must be informed that new messages are or going
363 out.
364 Error handling
366 $obj->AUTOLOAD
367 See "Error handling" in Mail::Reporter
368 $obj->addReport(OBJECT)
370 See "Error handling" in Mail::Reporter
371 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
373 Mail::Box::Manager->defaultTrace([LEVEL]|[LOGLEVEL,
374 TRACELEVEL]|[LEVEL, CALLBACK])
375 See "Error handling" in Mail::Reporter
377 $obj->errors
379 See "Error handling" in Mail::Reporter
380 $obj->log([LEVEL [,STRINGS]])
382 Mail::Box::Manager->log([LEVEL [,STRINGS]])
383 See "Error handling" in Mail::Reporter
385 $obj->logPriority(LEVEL)
387 Mail::Box::Manager->logPriority(LEVEL)
388 See "Error handling" in Mail::Reporter
390 $obj->logSettings
392 See "Error handling" in Mail::Reporter
393 $obj->notImplemented
395 See "Error handling" in Mail::Reporter
396 $obj->report([LEVEL])
398 See "Error handling" in Mail::Reporter
399 $obj->reportAll([LEVEL])
401 See "Error handling" in Mail::Reporter
402 $obj->trace([LEVEL])
404 See "Error handling" in Mail::Reporter
405 $obj->warnings
407 See "Error handling" in Mail::Reporter
408 Cleanup
410 $obj->DESTROY
411 See "Cleanup" in Mail::Reporter
412 $obj->inGlobalDestruction
414 See "Cleanup" in Mail::Reporter
415
417 Managing open folders
418 It is useful to start your program by creating a folder manager object,
419 an Mail::Box::Manager. The object takes a few burdons from your neck:
420 · autodetect the type of folder which is used.
422 This means that your application can be fully folder type
424 independent.
425 · autoload the required modules
427 There are so many modules involved in MailBox, that it is useful to
429 have some lazy autoloading of code. The manager knows which
430 modules belong to which type of folder.
431 · avoid double openings
433 Your programming mistakes may cause the same folder to be opened
435 twice. The result of that could be very destructive. Therefore,
436 the manager keeps track on all open folders and avoids the same
437 folder to be opened for the second time.
438 · close folders at clean-up
440 When the program is ending, the manager will cleanly close all
442 folders which are still open. This is required, because the
443 autodestruct sequence of Perl works in an unpredicatable order.
444 · message thread detection
446 MailBox can discover message threads which span multiple folders.
448 Any set of open folders may be grouped in a tree of replies on
449 replies on replies. When a folder is closed, it will automatically
450 be removed from the threads, and a new folder can dynamically be
451 added to the structure.
452 The manager is really simplifying things, and should therefore be the
454 base of all programs. However, it is possible to write useful programs
455 without it.
456 Managing a user
458 One step further is the Mail::Box::Manage::User object (since MailBox
459 v2.057), which not only keeps track on open folders, but also collects
460 information about not-open folders.
461 The user class is, as the name says, targeted on managing one single
463 user. Where the Mail::Box::Manager will open any set of folder files,
464 probably from multiple users, the user class want one root folder
465 directory.
466 In many aspects, the user manager simplifies the task for user-based
468 servers and other user-centric applications by setting smart defaults.
469 On many places in the documentation you can read that it is useful to
471 have a manager object. There are two of them: the Mail::Box::Manager,
472 which maintains a set of open folders, and an extension of it: the
473 Mail::Box::Manage::User.
474
476 Error: Folder $name is already open.
477 You cannot ask the manager for a folder which is already open. In
478 some older releases (before MailBox 2.049), this was permitted, but
479 then behaviour changed, because many nasty side-effects are to be
480 expected. For instance, an Mail::Box::update() on one folder
481 handle would influence the second, probably unexpectedly.
482 Error: Folder $name is not a Mail::Box; cannot add a message.
484 The folder where the message should be appended to is an object
485 which is not a folder type which extends Mail::Box. Probably, it
486 is not a folder at all.
487 Warning: Folder does not exist, failed opening $type folder $name.
489 The folder does not exist and creating is not permitted (see
490 open(create)) or did not succeed. When you do not have sufficient
491 access rights to the folder (for instance wrong password for POP3),
492 this warning will be produced as well.
493 The manager tried to open a folder of the specified type. It may
495 help to explicitly state the type of your folder with the "type"
496 option. There will probably be another warning or error message
497 which is related to this report and provides more details about its
498 cause. You may also have a look at new(autodetect) and
499 new(folder_types).
500 Warning: Folder type $type is unknown, using autodetect.
502 The specified folder type (see open(type), possibly derived from
503 the folder name when specified as url) is not known to the manager.
504 This may mean that you forgot to require the Mail::Box extension
505 which implements this folder type, but probably it is a typo.
506 Usually, the manager is able to figure-out which type to use by
507 itself.
508 Error: Illegal folder URL '$url'.
510 The folder name was specified as URL, but not according to the
511 syntax. See decodeFolderURL() for an description of the syntax.
512 Error: No foldername specified to open.
514 "open()" needs a folder name as first argument (before the list of
515 options), or with the "folder" option within the list. If no name
516 was found, the MAIL environment variable is checked. When even
517 that does not result in a usable folder, then this error is
518 produced. The error may be caused by an accidental odd-length
519 option list.
520 Error: Package $package does not implement $method.
522 Fatal error: the specific package (or one of its superclasses) does
523 not implement this method where it should. This message means that
524 some other related classes do implement this method however the
525 class at hand does not. Probably you should investigate this and
526 probably inform the author of the package.
527 Error: Use appendMessage() to add messages which are not in a folder.
529 You do not need to copy this message into the folder, because you
530 do not share the message between folders.
531 Warning: Use moveMessage() or copyMessage() to move between open
533 folders.
534 The message is already part of a folder, and now it should be
535 appended to a different folder. You need to decide between copy or
536 move, which both will clone the message (not the body, because they
537 are immutable).
538 Warning: Will never create a folder $name without having write access.
540 You have set open(create), but only want to read the folder.
541 Create is only useful for folders which have write or append access
542 modes (see Mail::Box::new(access)).
543
545 This module is part of Mail-Box distribution version 2.097, built on
546 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
547
549 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
550 ChangeLog.
551 This program is free software; you can redistribute it and/or modify it
553 under the same terms as Perl itself. See
554 http://www.perl.com/perl/misc/Artistic.html
555perl v5.12.3 2011-01-26 Mail::Box::Manager(3)