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 cre‐
42 ate more portable and safer code if you do use it.
43
45 Constructors
46 Mail::Box::Manager->new(ARGS)
48 Option --Defined in --Default
50 autodetect undef
51 default_folder_type 'mbox'
52 folder_types <all standard types>
53 folderdir [ '.' ]
54 folderdirs <synonym for C<folderdir>>
55 log Mail::Reporter 'WARNINGS'
56 trace Mail::Reporter 'WARNINGS'
57 . autodetect TYPE⎪ARRAY-OF-TYPES
59 Select only a subset of the folder types which are implemented
61 by MailBox to be detected automatically. This may improve the
62 auto-detection of folder types. Normally, all folder types
63 will be tried when a folder's name is incorrect, but this
64 option limits the types which are checked and therefore may
65 respond faster.
66 . default_folder_type NAME⎪CLASS
68 Specifies the default folder type for newly created folders.
70 If this option is not specified, the most recently registered
71 type is used (see registerType() and the new(folder_types)
72 option.
73 . folder_types NEW-TYPE ⎪ ARRAY-OF-NEW-TYPES
75 Add one or more new folder types to the list of known types.
77 The order is important: when you open a file without specifying
78 its type, the manager will start trying the last added list of
79 types, in order.
80 Each TYPE is specified as an array which contains name, class,
82 and defaults for options which overrule the usual defaults.
83 You may specify folder-specific defaults as OPTIONS. They
84 override the settings of the manager.
85 . folderdir DIRECTORY
87 The default directory, or directories, where folders are
89 located. The "Mail::Box::Manager" can autodetect the existing
90 folder-types. There may be different kinds of folders opened
91 at the same time, and messages can be moved between those
92 types, although that may result in a loss of information
93 depending on the folder types.
94 . folderdirs [DIRECTORIES]
96 . log LEVEL
98 . trace LEVEL
100 Attributes
102 $obj->defaultFolderType
104 Returns the default folder type, some class name.
106 $obj->folderTypes
108 Returns the list of currently defined folder types.
110 Example:
112 print join("\n", $manager->folderTypes), "\n";
114 $obj->folderdir
116 In list context, this returns all folderdirs specified. In SCALAR
118 context only the first.
119 $obj->registerType(TYPE, CLASS [,OPTIONS])
121 With "registerType" you can register one TYPE of folders. The
123 CLASS is compiled automatically, so you do not need to "use" them
124 in your own modules. The TYPE is just an arbitrary name.
125 The added types are prepended to the list of known types, so they
127 are checked first when a folder is opened in autodetect mode.
128 Example:
130 $manager->registerType(mbox => 'Mail::Box::Mbox',
132 save_on_exit => 0, folderdir => '/tmp');
133 Manage open folders
135 $obj->close(FOLDER, OPTIONS)
137 "close" removes the specified folder from the list of open folders.
139 Indirectly it will update the files on disk if needed (depends on
140 the Mail::Box::new(save_on_exit) flag for each folder). OPTIONS are
141 passed to Mail::Box::close() of the folder.
142 The folder's messages will also be withdrawn from the known message
144 threads. You may also close the folder directly. The manager will
145 be informed about this event and take appropriate actions.
146 Option --Default
148 close_by_self <false>
149 . close_by_self BOOLEAN
151 Used internally to avoid confusion about how the close was
153 started. Do not change this.
154 Example:
156 my $inbox = $mgr->open('inbox');
158 $mgr->close($inbox);
159 $inbox->close; # alternative
160 $obj->closeAllFolders(, OPTIONS)
162 "closeAllFolders" calls close() for each folder managed by this
164 object. It is called just before the program stops (before global
165 cleanup).
166 $obj->isOpenFolder(FOLDER)
168 Returns true if the FOLDER is currently open.
170 Example:
172 print "Yes\n" if $mgr->isOpenFolder('Inbox');
174 $obj->open([FOLDERNAME], OPTIONS)
176 Open a folder which name is specified as first parameter or with
178 the option flag "folder". The folder type is autodetected unless
179 the "type" is specified.
180 "open" carries options for the manager which are described here,
182 but may also have additional options for the folder type. For a
183 description of the folder options, see the options to the construc‐
184 tor Mail::Box::new() for each type of mail box.
185 Option --Default
187 authenticate 'AUTO'
188 create <false>
189 folder $ENV{MAIL}
190 folderdir '.'
191 type <first, usually C<mbox>>
192 . authenticate TYPE⎪ARRAY-OF-TYPES⎪'AUTO'
194 The TYPE of authentication to be used, or a list of TYPES which
196 the client prefers. The server may provide preferences as
197 well, and that order will be kept. This option is only sup‐
198 ported by a small subset of folder types, especially by POP and
199 IMAP.
200 . create BOOLEAN
202 Create the folder if it does not exist. By default, this is not
204 done. The "type" option specifies which type of folder is cre‐
205 ated.
206 . folder NAME⎪URL
208 Which folder to open, specified by NAME or special URL. The
210 URL format is composed as
211 type://username:password@hostname:port/foldername
213 Like real URLs, all fields are optional and have smart
215 defaults, as long as the string starts with a known folder
216 type. Far from all folder types support all these options, but
217 at least they are always split-out. Be warned that special
218 characters in the password should be properly url-encoded.
219 When you specify anything which does not match the URL format,
221 it is passed directly to the "new" method of the folder which
222 is opened.
223 . folderdir DIRECTORY
225 The directory where the folders are usually stored.
227 . type FOLDERTYPENAME⎪FOLDERTYPE
229 Specify the type of the folder. If you do not specify this
231 option while opening a folder for reading, the manager checks
232 all registered folder types in order for the ability to open
233 the folder. If you open a new folder for writing, then the
234 default will be the most recently registered type. (If you add
235 more than one type at once, the first of the list is used.)
236 Example: opening folders via the manager
238 my $jack = $manager->open(folder => '=jack',
240 type => 'mbox');
241 my $rcvd = $manager->open('myMail',
243 type => 'Mail::Box::Mbox', access => 'rw');
244 my $inbox = $manager->open('Inbox')
246 or die "Cannot open Inbox.\n";
247 my $pop = 'pop3://myself:secret@pop3.server.com:120/x';
249 my $send = $manager->open($url);
250 my $send = $manager->open(folder => '/x',
252 type => 'pop3', username => 'myself', password => 'secret'
253 server_name => 'pop3.server.com', server_port => '120');
254 $obj->openFolders
256 Returns a list of all open folders.
258 Manage existing folders
260 $obj->delete(FOLDERNAME, OPTIONS)
262 Remove the named folder. The OPTIONS are the same as those for
264 open().
265 The deletion of a folder can take some time. Dependent on the type
267 of folder, the folder must be read first. For some folder-types
268 this will be fast.
269 Option --Default
271 recursive <folder's default>
272 . recursive BOOLEAN
274 Some folder can only be recursively deleted, other have more
276 flexibility.
277 Move messages to folders
279 $obj->appendMessage([FOLDER⎪FOLDERNAME,] MESSAGES, OPTIONS)
281 Append one or more messages to a folder (therefore, an "appendMes‐
283 sages()" is defined as well). You may specify a FOLDERNAME or an
284 opened folder as the first argument. When the name is that of an
285 open folder, it is treated as if the folder-object was specified,
286 and not directly access the folder-files. You may also specify the
287 foldername as part of the options list.
288 If a message is added to an already opened folder, it is only added
290 to the structure internally in the program. The data will not be
291 written to disk until a write of that folder takes place. When the
292 name of an unopened folder is given, the folder is opened, the mes‐
293 sages stored on disk, and then the folder is closed.
294 A message must be an instance of a Mail::Message. The actual mes‐
296 sage type does not have to match the folder type--the folder will
297 try to resolve the differences with minimal loss of information.
298 The coerced messages (how the were actually written) are returned
299 as list.
300 The OPTIONS is a list of key/values, which are added to (overrid‐
302 ing) the default options for the detected folder type.
303 Example:
305 $mgr->appendMessage('=send', $message, folderdir => '/');
307 $mgr->appendMessage($received, $inbox->messages);
308 my @appended = $mgr->appendMessages($inbox->messages,
310 folder => 'Drafts');
311 $_->label(seen => 1) foreach @appended;
312 $obj->copyMessage([FOLDER⎪FOLDERNAME,] MESSAGES, OPTIONS)
314 Copy a message from one folder into another folder. If the desti‐
316 nation folder is already opened, Mail::Box::copyTo() is used. Oth‐
317 erwise, Mail::Box::appendMessages() is called.
318 You need to specify a folder's name or folder object as the first
320 argument, or in the options list. The options are the same as
321 those which can be specified when opening a folder.
322 Option--Default
324 share <false>
325 . share BOOLEAN
327 Try to share the physical storage of the messages. The folder
329 types may be different, but it all depends on the actual folder
330 where the message is copied to. Silently ignored when not pos‐
331 sible to share.
332 Example:
334 my $drafts = $mgr->open(folder => 'Drafts');
336 my $outbox = $mgr->open(folder => 'Outbox');
337 $mgr->copyMessage($outbox, $drafts->message(0));
338 my @messages = $drafts->message(1,2);
340 $mgr->copyMessage('=Trash', @messages,
341 folderdir => '/tmp', create => 1);
342 $mgr->copyMessage($drafts->message(1),
344 folder => '=Drafts' folderdir => '/tmp',
345 create => 1);
346 $obj->moveMessage([FOLDER⎪FOLDERNAME,] MESSAGES, OPTIONS)
348 Move a message from one folder to another. Be warned that removals
350 from a folder only take place when the folder is closed, so the
351 message is only flagged to be deleted in the opened source folder.
352 $mgr->moveMessage($received, $inbox->message(1))
354 is equivalent to
356 $mgr->copyMessage($received, $inbox->message(1), share => 1);
358 $inbox->message(1)->delete;
359 Option--Default
361 share <true>
362 . share BOOLEAN
364 Manage message threads
366 $obj->threads([FOLDERS], OPTIONS)
368 Create a new object which keeps track of message threads. You can
370 read about the possible options in Mail::Box::Thread::Manager. As
371 OPTIONS specify one folder or an array of FOLDERS. It is also per‐
372 mitted to specify folders before the options.
373 Example:
375 my $t1 = $mgr->threads(folders => [ $inbox, $send ]);
377 my $t2 = $mgr->threads($inbox);
378 my $t3 = $mgr->threads($inbox, $send);
379 Internals
381 $obj->decodeFolderURL(URL)
383 Try to decompose a folder name which is specified as URL (see
385 open()) into separate options.
386 $obj->toBeThreaded(FOLDER, MESSAGES)
388 Signal to the manager that all thread managers which are using the
390 specified folder must be informed that new messages are coming in.
391 $obj->toBeUnthreaded(FOLDER, MESSAGES)
393 Signal to the manager that all thread managers which are using the
395 specified folder must be informed that new messages are or going
396 out.
397 Error handling
399 $obj->AUTOLOAD
401 See "Error handling" in Mail::Reporter
403 $obj->addReport(OBJECT)
405 See "Error handling" in Mail::Reporter
407 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
409 Mail::Box::Manager->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL,
411 CALLBACK])
412 See "Error handling" in Mail::Reporter
414 $obj->errors
416 See "Error handling" in Mail::Reporter
418 $obj->log([LEVEL [,STRINGS]])
420 Mail::Box::Manager->log([LEVEL [,STRINGS]])
422 See "Error handling" in Mail::Reporter
424 $obj->logPriority(LEVEL)
426 Mail::Box::Manager->logPriority(LEVEL)
428 See "Error handling" in Mail::Reporter
430 $obj->logSettings
432 See "Error handling" in Mail::Reporter
434 $obj->notImplemented
436 See "Error handling" in Mail::Reporter
438 $obj->report([LEVEL])
440 See "Error handling" in Mail::Reporter
442 $obj->reportAll([LEVEL])
444 See "Error handling" in Mail::Reporter
446 $obj->trace([LEVEL])
448 See "Error handling" in Mail::Reporter
450 $obj->warnings
452 See "Error handling" in Mail::Reporter
454 Cleanup
456 $obj->DESTROY
458 See "Cleanup" in Mail::Reporter
460 $obj->inGlobalDestruction
462 See "Cleanup" in Mail::Reporter
464
466 On many places in the documentation you can read that it is useful to
467 have a manager object. There are two of them: the Mail::Box::Manager,
468 which maintains a set of open folders, and an extension of it: the
469 Mail::Box::Manage::User.
470 Managing open folders
472 It is useful to start your program by creating a folder manager object,
474 an Mail::Box::Manager. The object takes a few burdons from your neck:
475 * autodetect the type of folder which is used.
477 This means that your application can be fully folder type indepen‐
478 dent.
479 * autoload the required modules
481 There are so many modules involved in MailBox, that it is useful to
482 have some lazy autoloading of code. The manager knows which mod‐
483 ules belong to which type of folder.
484 * avoid double openings
486 Your programming mistakes may cause the same folder to be opened
487 twice. The result of that could be very destructive. Therefore,
488 the manager keeps track on all open folders and avoids the same
489 folder to be opened for the second time.
490 * close folders at clean-up
492 When the program is ending, the manager will cleanly close all
493 folders which are still open. This is required, because the
494 autodestruct sequence of Perl works in an unpredicatable order.
495 * message thread detection
497 MailBox can discover message threads which span multiple folders.
498 Any set of open folders may be grouped in a tree of replies on
499 replies on replies. When a folder is closed, it will automatically
500 be removed from the threads, and a new folder can dynamically be
501 added to the structure.
502 The manager is really simplifying things, and should therefore be the
504 base of all programs. However, it is possible to write useful programs
505 without it.
506 Managing a user
508 One step further is the Mail::Box::Manage::User object (since MailBox
510 v2.057), which not only keeps track on open folders, but also collects
511 information about not-open folders.
512 The user class is, as the name says, targeted on managing one single
514 user. Where the Mail::Box::Manager will open any set of folder files,
515 probably from multiple users, the user class want one root folder
516 directory.
517 In many aspects, the user manager simplifies the task for user-based
519 servers and other user-centric applications by setting smart defaults.
520
522 Error: Folder $name is already open.
523 You cannot ask the manager for a folder which is already open. In some
525 older releases (before MailBox 2.049), this was permitted, but then be‐
526 haviour changed, because many nasty side-effects are to be expected.
527 For instance, an Mail::Box::update() on one folder handle would influ‐
528 ence the second, probably unexpectedly.
529 Error: Folder $name is not a Mail::Box; cannot add a message.
531 The folder where the message should be appended to is an object which
533 is not a folder type which extends Mail::Box. Probably, it is not a
534 folder at all.
535 Warning: Folder does not exist, failed opening $type folder $name.
537 The folder does not exist and creating is not permitted (see open(cre‐
539 ate)) or did not succeed. When you do not have sufficient access
540 rights to the folder (for instance wrong password for POP3), this warn‐
541 ing will be produced as well.
542 The manager tried to open a folder of the specified type. It may help
544 to explicitly state the type of your folder with the "type" option.
545 There will probably be another warning or error message which is
546 related to this report and provides more details about its cause. You
547 may also have a look at new(autodetect) and new(folder_types).
548 Warning: Folder type $type is unknown, using autodetect.
550 The specified folder type (see open(type), possibly derived from the
552 folder name when specified as url) is not known to the manager. This
553 may mean that you forgot to require the Mail::Box extension which
554 implements this folder type, but probably it is a typo. Usually, the
555 manager is able to figure-out which type to use by itself.
556 Error: Illegal folder URL '$url'.
558 The folder name was specified as URL, but not according to the syntax.
560 See decodeFolderURL() for an description of the syntax.
561 Error: No foldername specified to open.
563 "open()" needs a folder name as first argument (before the list of
565 options), or with the "folder" option within the list. If no name was
566 found, the MAIL environment variable is checked. When even that does
567 not result in a usable folder, then this error is produced. The error
568 may be caused by an accidental odd-length option list.
569 Error: Package $package does not implement $method.
571 Fatal error: the specific package (or one of its superclasses) does not
573 implement this method where it should. This message means that some
574 other related classes do implement this method however the class at
575 hand does not. Probably you should investigate this and probably
576 inform the author of the package.
577 Error: Use appendMessage() to add messages which are not in a folder.
579 You do not need to copy this message into the folder, because you do
581 not share the message between folders.
582 Warning: Use moveMessage() or copyMessage() to move between open fold‐
584 ers.
585 The message is already part of a folder, and now it should be appended
587 to a different folder. You need to decide between copy or move, which
588 both will clone the message (not the body, because they are immutable).
589 Warning: Will never create a folder $name without having write access.
591 You have set open(create), but only want to read the folder. Create is
593 only useful for folders which have write or append access modes (see
594 Mail::Box::new(access)).
595
597 This module is part of Mail-Box distribution version 2.070, built on
598 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
599
601 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
602 ChangeLog.
603 This program is free software; you can redistribute it and/or modify it
605 under the same terms as Perl itself. See
606 http://www.perl.com/perl/misc/Artistic.html
607perl v5.8.8 2007-03-25 Mail::Box::Manager(3)