1Mail::Box::Thread::ManaUgseerr(3C)ontributed Perl DocumeMnatialt:i:oBnox::Thread::Manager(3)
2
3
4

NAME

6       Mail::Box::Thread::Manager - maintain threads within a set of folders
7

INHERITANCE

9        Mail::Box::Thread::Manager
10          is a Mail::Reporter
11

SYNOPSIS

13        my $mgr     = Mail::Box::Manager->new;
14        my $folder  = $mgr->open(folder => '/tmp/inbox');
15
16        my $threads = $mgr->threads();
17        $threads->includeFolder($folder);
18
19        my $threads = $msg->threads(folder => $folder);
20
21        foreach my $thread ($threads->all) {
22            $thread->print;
23        }
24
25        $threads->removeFolder($folder);
26

DESCRIPTION

28       A (message-)thread is a message with links to messages which followed
29       in reply of that message.  And then the messages with replied to the
30       messages, which replied the original message.  And so on.  Some threads
31       are only one message long (never replied to), some threads are very
32       long.
33
34       The "Mail::Box::Thread::Manager" is very powerful.  Not only is it able
35       to do a descent job on MH-like folders (makes a trade-off between
36       perfection and speed), it also can maintain threads from messages
37       residing in different opened folders.  Both facilities are rare for
38       mail-agents.  The manager creates flexible trees with
39       Mail::Box::Thread::Node objects.
40
41       Extends "DESCRIPTION" in Mail::Reporter.
42

METHODS

44       Extends "METHODS" in Mail::Reporter.
45
46   Constructors
47       Extends "Constructors" in Mail::Reporter.
48
49       Mail::Box::Thread::Manager->new(%options)
50           A "Mail::Box::Thread::Manager" object is usually created by a
51           Mail::Box::Manager.  One manager can produce more than one of these
52           objects.  One thread manager can combine messages from a set of
53           folders, which may be partially overlapping with other objects of
54           the same type.
55
56            -Option     --Defined in     --Default
57             dummy_type                    Mail::Message::Dummy
58             folder                        [ ]
59             folders                       [ ]
60             log          Mail::Reporter   'WARNINGS'
61             thread_body                   <false>
62             thread_type                   Mail::Box::Thread::Node
63             timespan                      '3 days'
64             trace        Mail::Reporter   'WARNINGS'
65             window                        10
66
67           dummy_type => CLASS
68             The type of dummy messages.  Dummy messages are used to fill
69             holes in detected threads: referred to by messages found in the
70             folder, but itself not in the folder.
71
72           folder => FOLDER | REF-ARRAY-FOLDERS
73             Specifies which folders are to be covered by the threads.  You
74             can specify one or more open folders.  When you close a folder,
75             the manager will automatically remove the messages of that folder
76             from your threads.
77
78           folders => FOLDER | REF-ARRAY-FOLDERS
79             Equivalent to the "folder" option.
80
81           log => LEVEL
82           thread_body => BOOLEAN
83             May thread-detection be based on the content of a message?  This
84             has a serious performance implication when there are many
85             messages without "In-Reply-To" and "References" headers in the
86             folder, because it will cause many messages to be parsed. NOT
87             IMPLEMENTED YET.
88
89           thread_type => CLASS
90             Type of the thread nodes.
91
92           timespan => TIME | 'EVER'
93             Specify how fast threads usually work: the amount of time between
94             an answer and a reply.  This is used in combination with the
95             "window" option to determine when to give-up filling the holes in
96             threads.
97
98             See Mail::Box::timespan2seconds() for the possibilities for TIME.
99             With 'EVER', the search for messages in a thread will only be
100             limited by the window-size.
101
102           trace => LEVEL
103           window => INTEGER|'ALL'
104             The thread-window describes how many messages should be checked
105             at maximum to fill `holes' in threads for folder which use delay-
106             loading of message headers.
107
108             The constant 'ALL' will cause thread-detection not to stop trying
109             to fill holes, but continue looking until the first message of
110             the folder is reached.  Gives the best quality results, but may
111             perform bad.
112
113           example:
114
115            use Mail::Box::Manager;
116            my $mgr     = Mail::Box::Manager->new;
117            my $inbox   = $mgr->open(folder => $ENV{MAIL});
118            my $read    = $mgr->open(folder => 'Mail/read');
119            my $threads = $mgr->threads(folders => [$inbox, $read]);
120
121            # longer alternative for last line:
122            my $threads = $mgr->threads;
123            $threads->includeFolder($inbox);
124            $threads->includeFolder($read);
125
126   Grouping Folders
127       $obj->folders()
128           Returns the folders as managed by this threader.
129
130       $obj->includeFolder($folders)
131           Add one or more folders to the list of folders whose messages are
132           organized in the threads maintained by this object.  Duplicated
133           inclusions will not cause any problems.
134
135           From the folders, the messages which have their header lines parsed
136           (see Mail::Box about lazy extracting) will be immediately scanned.
137           Messages of which the header is known only later will have to
138           report this (see toBeThreaded()).
139
140           example:
141
142            $threads->includeFolder($inbox, $draft);
143
144       $obj->removeFolder($folders)
145           Remove one or more folders from the list of folders whose messages
146           are organized in the threads maintained by this object.
147
148           example:
149
150            $threads->removeFolder($draft);
151
152   The Threads
153       $obj->all()
154           Returns all messages which start a thread.  The list may contain
155           dummy messages and messages which are scheduled for deletion.
156
157           To be able to return all threads, thread construction on each
158           message is performed first, which may be slow for some folder-types
159           because is will enforce parsing of message-bodies.
160
161       $obj->known()
162           Returns the list of all messages which are known to be the start of
163           a thread.  Threads containing messages which where not read from
164           their folder (like often happens MH-folder messages) are not yet
165           known, and hence will not be returned.
166
167           The list may contain dummy messages, and messages which are
168           scheduled for deletion.  Threads are detected based on explicitly
169           calling inThread() and thread() with a messages from the folder.
170
171           Be warned that, each time a message's header is read from the
172           folder, the return of the method can change.
173
174       $obj->sortedAll( [$prepare, [$compare]] )
175           Returns all() the threads by default, but sorted on timestamp.
176
177       $obj->sortedKnown( [$prepare, [$compare]] )
178           Returns all known() threads, in sorted order.  By default, the
179           threads will be sorted on timestamp, But a different $compare
180           method can be specified.
181
182       $obj->thread($message)
183           Returns the thread where this $message is the start of.  However,
184           there is a possibility that this message is a reply itself.
185
186           Usually, all messages which are in reply of this message are dated
187           later than the specified one.  All headers of messages later than
188           this one are getting parsed first, for each folder in this threads-
189           object.
190
191           example:
192
193            my $threads = $mgr->threads(folder => $inbox);
194            my $thread  = $threads->thread($inbox->message(3));
195            print $thread->string;
196
197       $obj->threadStart($message)
198           Based on a message, and facts from previously detected threads, try
199           to build solid knowledge about the thread where this message is in.
200
201   Internals
202       $obj->createDummy($message_id)
203           Get a replacement message to be used in threads.  Be warned that a
204           dummy is not a member of any folder, so the program working with
205           threads must test with Mail::Message::isDummy() before trying
206           things only available to real messages.
207
208       $obj->inThread($message)
209           Collect the thread-information of one message.  The `In-Reply-To'
210           and `Reference' header-fields are processed.  If this method is
211           called on a message whose header was not read yet (as usual for MH-
212           folders, for instance) the reading of that header will be triggered
213           here.
214
215       $obj->outThread($message)
216           Remove the message from the thread-infrastructure.  A message is
217           replaced by a dummy.
218
219       $obj->toBeThreaded($folder, @messages)
220           Include the specified messages in/from the threads managed by this
221           object, if this folder is maintained by this thread-manager.
222
223       $obj->toBeUnthreaded($folder, @messages)
224           Remove the specified @messages in/from the threads managed by this
225           object, if this folder is maintained by this thread-manager.
226
227   Error handling
228       Extends "Error handling" in Mail::Reporter.
229
230       $obj->AUTOLOAD()
231           Inherited, see "Error handling" in Mail::Reporter
232
233       $obj->addReport($object)
234           Inherited, see "Error handling" in Mail::Reporter
235
236       $obj->defaultTrace( [$level]|[$loglevel, $tracelevel]|[$level,
237       $callback] )
238       Mail::Box::Thread::Manager->defaultTrace( [$level]|[$loglevel,
239       $tracelevel]|[$level, $callback] )
240           Inherited, see "Error handling" in Mail::Reporter
241
242       $obj->errors()
243           Inherited, see "Error handling" in Mail::Reporter
244
245       $obj->log( [$level, [$strings]] )
246       Mail::Box::Thread::Manager->log( [$level, [$strings]] )
247           Inherited, see "Error handling" in Mail::Reporter
248
249       $obj->logPriority($level)
250       Mail::Box::Thread::Manager->logPriority($level)
251           Inherited, see "Error handling" in Mail::Reporter
252
253       $obj->logSettings()
254           Inherited, see "Error handling" in Mail::Reporter
255
256       $obj->notImplemented()
257           Inherited, see "Error handling" in Mail::Reporter
258
259       $obj->report( [$level] )
260           Inherited, see "Error handling" in Mail::Reporter
261
262       $obj->reportAll( [$level] )
263           Inherited, see "Error handling" in Mail::Reporter
264
265       $obj->trace( [$level] )
266           Inherited, see "Error handling" in Mail::Reporter
267
268       $obj->warnings()
269           Inherited, see "Error handling" in Mail::Reporter
270
271   Cleanup
272       Extends "Cleanup" in Mail::Reporter.
273
274       $obj->DESTROY()
275           Inherited, see "Cleanup" in Mail::Reporter
276

DETAILS

278       This module implements thread-detection on a folder.  Messages created
279       by the better mailers will include "In-Reply-To" and "References"
280       lines, which are used to figure out how messages are related.  If you
281       prefer a better thread detection, they are implementable, but there may
282       be a serious performance hit (depends on the type of folder used).
283
284   Maintaining threads
285       A "Mail::Box::Thread::Manager" object is created by the
286       Mail::Box::Manager, using Mail::Box::Manager::threads().  Each object
287       can monitor the thread-relations between messages in one or more
288       folders.  When more than one folder is specified, the messages are
289       merged while reading the threads, although nothing changes in the
290       folder-structure.  Adding and removing folders which have to be
291       maintained is permitted at any moment, although may be quite costly in
292       performance.
293
294       An example of the maintained structure is shown below.  The
295       Mail::Box::Manager has two open folders, and a thread-builder which
296       monitors them both.  The combined folders have two threads, the second
297       is two long (msg3 is a reply on msg2).  Msg2 is in two folders at once.
298
299              manager
300               |    \
301               |     `----------- threads
302               |                  |     |
303               |                thread thread---thread
304               |                  |    /|        /
305               |                  |   //        /
306               +---- folder1      |  //        /
307               |       |         /  //        /
308               |       `-----msg1  //        /
309               |       `-----msg2-'/        /
310               |                  /        /
311               `-----folder2     /        /
312                       |        /        /
313                       `-----msg2       /
314                       `-----msg3------'
315
316   Delayed thread detection
317       With all() you get the start-messages of each thread of this folder.
318       When that message was not found in the folder (not saved or already
319       removed), you get a message of the dummy-type.  These thread
320       descriptions are in perfect state: all messages of the folder are
321       included somewhere, and each missing message of the threads (holes) are
322       filled by dummies.
323
324       However, to be able to detect all threads it is required to have the
325       headers of all messages, which is very slow for some types of folders,
326       especially MH and IMAP folders.
327
328       For interactive mail-readers, it is preferred to detect threads only on
329       messages which are in the viewport of the user.  This may be sloppy in
330       some situations, but everything is preferable over reading an MH
331       mailbox with 10k e-mails to read only the see most recent messages.
332
333       In this object, we take special care not to cause unnecessary parsing
334       (loading) of messages.  Threads will only be detected on command, and
335       by default only the message headers are used.
336
337       The following reports the Mail::Box::Thread::Node which is related to a
338       message:
339
340        my $thread = $message->thread;
341
342       When the message was not put in a thread yet, it is done now.  But,
343       more work is done to return the best thread.  Based on various
344       parameters, which where specified when the folder was created, the
345       method walks through the folder to fill the holes which are in this
346       thread.
347
348       Walking from back to front (recently arrived messages are usually in
349       the back of the folder), message after message are triggered to be
350       included in their thread.  At a certain moment, the whole thread of the
351       requested method is found, a certain maximum number of messages was
352       tried, but that didn't help (search window bound reached), or the
353       messages within the folder are getting too old.  Then the search to
354       complete the thread will end, although more messages of them might have
355       been in the folder: we don't scan the whole folder for performance
356       reasons.
357
358       Finally, for each message where the head is known, for instance for all
359       messages in mbox-folders, the correct thread is determined immediately.
360       Also, all messages where the head get loaded later, are automatically
361       included.
362

DIAGNOSTICS

364       Error: Package $package does not implement $method.
365           Fatal error: the specific package (or one of its superclasses) does
366           not implement this method where it should. This message means that
367           some other related classes do implement this method however the
368           class at hand does not.  Probably you should investigate this and
369           probably inform the author of the package.
370

SEE ALSO

372       This module is part of Mail-Box distribution version 3.009, built on
373       August 18, 2020. Website: http://perl.overmeer.net/CPAN/
374

LICENSE

376       Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
377       ChangeLog.
378
379       This program is free software; you can redistribute it and/or modify it
380       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
381
382
383
384perl v5.34.0                      2021-07-22     Mail::Box::Thread::Manager(3)
Impressum