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

NAME

6       Mail::Box::Manager - manage a set of folders
7

INHERITANCE

9        Mail::Box::Manager
10          is a Mail::Reporter
11
12        Mail::Box::Manager is extended by
13          Mail::Box::Manage::User
14

SYNOPSIS

16        use Mail::Box::Manager;
17        my $mgr     = new Mail::Box::Manager;
18
19        # Create folder objects.
20        my $folder   = $mgr->open(folder => $ENV{MAIL});
21        my $message1 = $folder->message(0);
22        $mgr->copyMessage('Draft', $message);
23
24        my @messages = $folder->message(0,3);
25        $mgr->moveMessage('Outbox', @messages, create => 1 );
26        $mgr->close($folder);
27
28        # Create thread-detectors (see Mail::Box::Thread::Manager)
29        my $t       = $mgr->threads($inbox, $outbox);
30
31        my $threads = $mgr->threads(folder => $folder);
32        foreach my $thread ($threads->all)
33        {   $thread->print;
34        }
35
36        $mgr->registerType(mbox => 'Mail::Box::MyType');
37

DESCRIPTION

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
44       Extends "DESCRIPTION" in Mail::Reporter.
45

METHODS

47       Extends "METHODS" in Mail::Reporter.
48
49   Constructors
50       Extends "Constructors" in Mail::Reporter.
51
52       Mail::Box::Manager->new($args)
53            -Option             --Defined in     --Default
54             autodetect                            undef
55             default_folder_type                   'mbox'
56             folder_types                          <all standard types>
57             folderdir                             [ '.' ]
58             folderdirs                            <synonym for C<folderdir>>
59             log                  Mail::Reporter   'WARNINGS'
60             trace                Mail::Reporter   'WARNINGS'
61
62           autodetect => TYPE|ARRAY-OF-TYPES
63             Select only a subset of the folder types which are implemented by
64             MailBox to be detected automatically.  This may improve the auto-
65             detection of folder types.  Normally, all folder types will be
66             tried when a folder's name is incorrect, but this option limits
67             the types which are checked and therefore may respond faster.
68
69           default_folder_type => NAME|CLASS
70             Specifies the default folder type for newly created folders.  If
71             this option is not specified, the most recently registered type
72             is used (see registerType() and the new(folder_types) option.
73
74           folder_types => NEW-TYPE | ARRAY-OF-NEW-TYPES
75             Add one or more new folder types to the list of known types.  The
76             order is important: when you open a file without specifying its
77             type, the manager will start trying the last added list of types,
78             in order.
79
80             Each TYPE is specified as an array which contains name, class,
81             and defaults for options which overrule the usual defaults.  You
82             may specify folder-specific defaults as OPTIONS.  They override
83             the settings of the manager.
84
85           folderdir => DIRECTORY
86             The default directory, or directories, where folders are located.
87             The "Mail::Box::Manager" can autodetect the existing folder-
88             types.  There may be different kinds of folders opened at the
89             same time, and messages can be moved between those types,
90             although that may result in a loss of information depending on
91             the folder types.
92
93           folderdirs => [DIRECTORIES]
94           log => LEVEL
95           trace => LEVEL
96
97   Attributes
98       $obj->defaultFolderType()
99           Returns the default folder type, some class name.
100
101       $obj->folderTypes()
102           Returns the list of currently defined folder types.
103
104           example:
105
106            print join("\n", $manager->folderTypes), "\n";
107
108       $obj->folderdir()
109           In list context, this returns all folderdirs specified.  In SCALAR
110           context only the first.
111
112       $obj->registerType($type, $class, %options)
113           With "registerType" you can register one $type of folders.  The
114           $class is compiled automatically, so you do not need to "use" them
115           in your own modules.  The $type is just an arbitrary name.
116
117           The added types are prepended to the list of known types, so they
118           are checked first when a folder is opened in autodetect mode.
119
120           example:
121
122            $manager->registerType(mbox => 'Mail::Box::Mbox',
123                save_on_exit => 0, folderdir => '/tmp');
124
125   Manage open folders
126       $obj->close($folder, %options)
127           "close" removes the specified folder from the list of open folders.
128           Indirectly it will update the files on disk if needed (depends on
129           the Mail::Box::new(save_on_exit) flag for each folder). %options
130           are passed to Mail::Box::close() of the folder.
131
132           The folder's messages will also be withdrawn from the known message
133           threads.  You may also close the folder directly. The manager will
134           be informed about this event and take appropriate actions.
135
136            -Option       --Default
137             close_by_self  <false>
138
139           close_by_self => BOOLEAN
140             Used internally to avoid confusion about how the close was
141             started.  Do not change this.
142
143           example:
144
145            my $inbox = $mgr->open('inbox');
146            $mgr->close($inbox);
147            $inbox->close;        # alternative
148
149       $obj->closeAllFolders(, %options)
150           "closeAllFolders" calls close() for each folder managed by this
151           object.  It is called just before the program stops (before global
152           cleanup).
153
154       $obj->isOpenFolder($folder)
155           Returns true if the $folder is currently open.
156
157           example:
158
159            print "Yes\n" if $mgr->isOpenFolder('Inbox');
160
161       $obj->open( [$foldername], %options )
162           Open a folder which name is specified as first parameter or with
163           the option flag "folder".  The folder type is autodetected unless
164           the "type" is specified.
165
166           "open" carries options for the manager which are described here,
167           but may also have additional options for the folder type.  For a
168           description of the folder options, see the options to the
169           constructor Mail::Box::new() for each type of mail box.
170
171            -Option      --Default
172             authenticate  'AUTO'
173             create        <false>
174             folder        $ENV{MAIL}
175             folderdir     '.'
176             type          <first, usually C<mbox>>
177
178           authenticate => TYPE|ARRAY-OF-TYPES|'AUTO'
179             The TYPE of authentication to be used, or a list of TYPES which
180             the client prefers.  The server may provide preferences as well,
181             and that order will be kept.  This option is only supported by a
182             small subset of folder types, especially by POP and IMAP.
183
184           create => BOOLEAN
185             Create the folder if it does not exist. By default, this is not
186             done.  The "type" option specifies which type of folder is
187             created.
188
189           folder => NAME|URL
190             Which folder to open, specified by NAME or special URL.  The URL
191             format is composed as
192
193              type://username:password@hostname:port/foldername
194
195             Like real URLs, all fields are optional and have smart defaults,
196             as long as the string starts with a known folder type.  Far from
197             all folder types support all these options, but at least they are
198             always split-out.  Be warned that special characters in the
199             password should be properly url-encoded.
200
201             When you specify anything which does not match the URL format, it
202             is passed directly to the "new" method of the folder which is
203             opened.
204
205           folderdir => DIRECTORY
206             The directory where the folders are usually stored.
207
208           type => FOLDERTYPENAME|FOLDERTYPE
209             Specify the type of the folder.  If you do not specify this
210             option while opening a folder for reading, the manager checks all
211             registered folder types in order for the ability to open the
212             folder. If you open a new folder for writing, then the default
213             will be the most recently registered type. (If you add more than
214             one type at once, the first of the list is used.)
215
216             Currently, the types are "mbox", "mh", "maildir", "pop3",
217             "pop3s", "imap4", and "imap4s".  You may also use names "pop",
218             "pops", "imap", and "imaps".
219
220           example: opening folders via the manager
221
222            my $jack  = $manager->open(folder => '=jack',
223               type => 'mbox');
224
225            my $rcvd  = $manager->open('myMail',
226               type => 'Mail::Box::Mbox', access => 'rw');
227
228            my $inbox = $manager->open('Inbox')
229               or die "Cannot open Inbox.\n";
230
231            my $pop   = 'pop3://myself:secret@pop3.server.com:120/x';
232            my $send  = $manager->open($url);
233
234            my $send  = $manager->open(folder => '/x',
235              type => 'pop3', username => 'myself', password => 'secret'
236              server_name => 'pop3.server.com', server_port => '120');
237
238       $obj->openFolders()
239           Returns a list of all open folders.
240
241   Manage existing folders
242       $obj->delete($foldername, %options)
243           Remove the named folder.  The %options are the same as those for
244           open().
245
246           The deletion of a folder can take some time.  Dependent on the type
247           of folder, the folder must be read first.  For some folder-types
248           this will be fast.
249
250            -Option   --Default
251             recursive  <folder's default>
252
253           recursive => BOOLEAN
254             Some folder can only be recursively deleted, other have more
255             flexibility.
256
257   Move messages to folders
258       $obj->appendMessage( [$folder|$foldername], $messages, %options )
259           Append one or more messages to a folder (therefore, an
260           appendMessages() is defined as well). You may specify a $foldername
261           or an opened folder as the first argument. When the name is that of
262           an open folder, it is treated as if the folder-object was
263           specified, and not directly access the folder-files.  You may also
264           specify the foldername as part of the options list.
265
266           If a message is added to an already opened folder, it is only added
267           to the structure internally in the program.  The data will not be
268           written to disk until a write of that folder takes place.  When the
269           name of an unopened folder is given, the folder is opened, the
270           messages stored on disk, and then the folder is closed.
271
272           A message must be an instance of a Mail::Message.  The actual
273           message type does not have to match the folder type--the folder
274           will try to resolve the differences with minimal loss of
275           information.  The coerced messages (how the were actually written)
276           are returned as list.
277
278           The %options is a list of key/values, which are added to
279           (overriding) the default options for the detected folder type.
280
281           example:
282
283            $mgr->appendMessage('=send', $message, folderdir => '/');
284            $mgr->appendMessage($received, $inbox->messages);
285
286            my @appended = $mgr->appendMessages($inbox->messages,
287               folder => 'Drafts');
288            $_->label(seen => 1) foreach @appended;
289
290       $obj->copyMessage( [$folder|$foldername], $messages, %options )
291           Copy a message from one folder into another folder.  If the
292           destination folder is already opened, Mail::Box::copyTo() is used.
293           Otherwise, Mail::Box::appendMessages() is called.
294
295           You need to specify a folder's name or folder object as the first
296           argument, or in the options list.  The options are the same as
297           those which can be specified when opening a folder.
298
299            -Option--Default
300             share   <false>
301
302           share => BOOLEAN
303             Try to share the physical storage of the messages.  The folder
304             types may be different, but it all depends on the actual folder
305             where the message is copied to.  Silently ignored when not
306             possible to share.
307
308           example:
309
310            my $drafts = $mgr->open(folder => 'Drafts');
311            my $outbox = $mgr->open(folder => 'Outbox');
312            $mgr->copyMessage($outbox, $drafts->message(0));
313
314            my @messages = $drafts->message(1,2);
315            $mgr->copyMessage('=Trash', @messages,
316               folderdir => '/tmp', create => 1);
317
318            $mgr->copyMessage($drafts->message(1),
319               folder => '=Drafts' folderdir => '/tmp',
320               create => 1);
321
322       $obj->moveMessage( [$folder|$foldername], $messages, %options )
323           Move a message from one folder to another.
324
325           BE WARNED that removals from a folder only take place when the
326           folder is closed, so the message is only flagged to be deleted in
327           the opened source folder.
328
329           BE WARNED that message labels may get lost when a message is moved
330           from one folder type to an other.  An attempt is made to translate
331           labels, but there are many differences in interpretation by
332           applications.
333
334            $mgr->moveMessage($received, $inbox->message(1))
335
336           is equivalent to
337
338            $mgr->copyMessage($received, $inbox->message(1), share => 1);
339            $inbox->message(1)->delete;
340
341            -Option--Default
342             share   <true>
343
344           share => BOOLEAN
345
346   Manage message threads
347       $obj->threads( [$folders], %options )
348           Create a new object which keeps track of message threads.  You can
349           read about the possible options in Mail::Box::Thread::Manager.  As
350           %options specify one folder or an array of $folders.  It is also
351           permitted to specify folders before the options.
352
353           example:
354
355            my $t1 = $mgr->threads(folders => [ $inbox, $send ]);
356            my $t2 = $mgr->threads($inbox);
357            my $t3 = $mgr->threads($inbox, $send);
358
359   Internals
360       $obj->decodeFolderURL($url)
361           Try to decompose a folder name which is specified as $url (see
362           open()) into separate options.  Special characters like @-sign,
363           colon, and slash used in the user or password parts must be passed
364           $url-encoded.
365
366       $obj->toBeThreaded($folder, $messages)
367           Signal to the manager that all thread managers which are using the
368           specified folder must be informed that new messages are coming in.
369
370       $obj->toBeUnthreaded($folder, $messages)
371           Signal to the manager that all thread managers which are using the
372           specified folder must be informed that new messages are or going
373           out.
374
375   Error handling
376       Extends "Error handling" in Mail::Reporter.
377
378       $obj->AUTOLOAD()
379           Inherited, see "Error handling" in Mail::Reporter
380
381       $obj->addReport($object)
382           Inherited, see "Error handling" in Mail::Reporter
383
384       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
385       $callback] )
386       Mail::Box::Manager->defaultTrace( [$level]|[$loglevel,
387       $tracelevel]|[$level, $callback] )
388           Inherited, see "Error handling" in Mail::Reporter
389
390       $obj->errors()
391           Inherited, see "Error handling" in Mail::Reporter
392
393       $obj->log( [$level, [$strings]] )
394       Mail::Box::Manager->log( [$level, [$strings]] )
395           Inherited, see "Error handling" in Mail::Reporter
396
397       $obj->logPriority($level)
398       Mail::Box::Manager->logPriority($level)
399           Inherited, see "Error handling" in Mail::Reporter
400
401       $obj->logSettings()
402           Inherited, see "Error handling" in Mail::Reporter
403
404       $obj->notImplemented()
405           Inherited, see "Error handling" in Mail::Reporter
406
407       $obj->report( [$level] )
408           Inherited, see "Error handling" in Mail::Reporter
409
410       $obj->reportAll( [$level] )
411           Inherited, see "Error handling" in Mail::Reporter
412
413       $obj->trace( [$level] )
414           Inherited, see "Error handling" in Mail::Reporter
415
416       $obj->warnings()
417           Inherited, see "Error handling" in Mail::Reporter
418
419   Cleanup
420       Extends "Cleanup" in Mail::Reporter.
421
422       $obj->DESTROY()
423           Inherited, see "Cleanup" in Mail::Reporter
424

DETAILS

426       On many places in the documentation you can read that it is useful to
427       have a manager object.  There are two of them: the Mail::Box::Manager,
428       which maintains a set of open folders, and an extension of it: the
429       Mail::Box::Manage::User.
430
431   Managing open folders
432       It is useful to start your program by creating a folder manager object,
433       an Mail::Box::Manager.  The object takes a few burdons from your neck:
434
435       •   autodetect the type of folder which is used.
436
437           This means that your application can be fully folder type
438           independent.
439
440       •   autoload the required modules
441
442           There are so many modules involved in MailBox, that it is useful to
443           have some lazy autoloading of code.  The manager knows which
444           modules belong to which type of folder.
445
446       •   avoid double openings
447
448           Your programming mistakes may cause the same folder to be opened
449           twice.  The result of that could be very destructive.  Therefore,
450           the manager keeps track on all open folders and avoids the same
451           folder to be opened for the second time.
452
453       •   close folders at clean-up
454
455           When the program is ending, the manager will cleanly close all
456           folders which are still open.  This is required, because the
457           autodestruct sequence of Perl works in an unpredicatable order.
458
459       •   message thread detection
460
461           MailBox can discover message threads which span multiple folders.
462           Any set of open folders may be grouped in a tree of replies on
463           replies on replies.  When a folder is closed, it will automatically
464           be removed from the threads, and a new folder can dynamically be
465           added to the structure.
466
467       The manager is really simplifying things, and should therefore be the
468       base of all programs. However, it is possible to write useful programs
469       without it.
470
471   Managing a user
472       One step further is the Mail::Box::Manage::User object (since MailBox
473       v2.057), which not only keeps track on open folders, but also collects
474       information about not-open folders.
475
476       The user class is, as the name says, targeted on managing one single
477       user.  Where the Mail::Box::Manager will open any set of folder files,
478       probably from multiple users, the user class want one root folder
479       directory.
480
481       In many aspects, the user manager simplifies the task for user-based
482       servers and other user-centric applications by setting smart defaults.
483

DIAGNOSTICS

485       Error: Folder $name is already open.
486           You cannot ask the manager for a folder which is already open. In
487           some older releases (before MailBox 2.049), this was permitted, but
488           then behaviour changed, because many nasty side-effects are to be
489           expected.  For instance, an Mail::Box::update() on one folder
490           handle would influence the second, probably unexpectedly.
491
492       Error: Folder $name is not a Mail::Box; cannot add a message.
493           The folder where the message should be appended to is an object
494           which is not a folder type which extends Mail::Box.  Probably, it
495           is not a folder at all.
496
497       Warning: Folder does not exist, failed opening $type folder $name.
498           The folder does not exist and creating is not permitted (see
499           open(create)) or did not succeed.  When you do not have sufficient
500           access rights to the folder (for instance wrong password for POP3),
501           this warning will be produced as well.
502
503           The manager tried to open a folder of the specified type.  It may
504           help to explicitly state the type of your folder with the "type"
505           option.  There will probably be another warning or error message
506           which is related to this report and provides more details about its
507           cause.  You may also have a look at new(autodetect) and
508           new(folder_types).
509
510       Warning: Folder type $type is unknown, using autodetect.
511           The specified folder type (see open(type), possibly derived from
512           the folder name when specified as url) is not known to the manager.
513           This may mean that you forgot to require the Mail::Box extension
514           which implements this folder type, but probably it is a typo.
515           Usually, the manager is able to figure-out which type to use by
516           itself.
517
518       Error: Illegal folder URL '$url'.
519           The folder name was specified as URL, but not according to the
520           syntax.  See decodeFolderURL() for an description of the syntax.
521
522       Error: No foldername specified to open.
523           open() needs a folder name as first argument (before the list of
524           options), or with the "folder" option within the list.  If no name
525           was found, the MAIL environment variable is checked.  When even
526           that does not result in a usable folder, then this error is
527           produced.  The error may be caused by an accidental odd-length
528           option list.
529
530       Error: Package $package does not implement $method.
531           Fatal error: the specific package (or one of its superclasses) does
532           not implement this method where it should. This message means that
533           some other related classes do implement this method however the
534           class at hand does not.  Probably you should investigate this and
535           probably inform the author of the package.
536
537       Error: Use appendMessage() to add messages which are not in a folder.
538           You do not need to copy this message into the folder, because you
539           do not share the message between folders.
540
541       Warning: Use moveMessage() or copyMessage() to move between open
542       folders.
543           The message is already part of a folder, and now it should be
544           appended to a different folder.  You need to decide between copy or
545           move, which both will clone the message (not the body, because they
546           are immutable).
547
548       Warning: Will never create a folder $name without having write access.
549           You have set open(create), but only want to read the folder.
550           Create is only useful for folders which have write or append access
551           modes (see Mail::Box::new(access)).
552

SEE ALSO

554       This module is part of Mail-Box distribution version 3.010, built on
555       July 18, 2023. Website: http://perl.overmeer.net/CPAN/
556

LICENSE

558       Copyrights 2001-2023 by [Mark Overmeer]. For other contributors see
559       ChangeLog.
560
561       This program is free software; you can redistribute it and/or modify it
562       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
563
564
565
566perl v5.38.0                      2023-07-24             Mail::Box::Manager(3)
Impressum