1Mail::Box::Thread::ManaUgseerr(3C)ontributed Perl DocumeMnatialt:i:oBnox::Thread::Manager(3)
2
6 Mail::Box::Thread::Manager - maintain threads within a set of folders
7
9 Mail::Box::Thread::Manager
10 is a Mail::Reporter
11
13 my $mgr = Mail::Box::Thread::Manager->new;
14 my $folder = $mgr->open(folder => '/tmp/inbox');
15 my $threads = $mgr->threads(folder => $folder);
16 my $threads = $mgr->threads($folder); # same
17 foreach my $thread ($threads->all) {
19 $thread->print;
20 }
21 $threads->includeFolder($folder);
23 $threads->removeFolder($folder);
24
26 A (message-)thread is a message with links to messages which followed
27 in reply of that message. And then the messages with replied to the
28 messages, which replied the original message. And so on. Some threads
29 are only one message long (never replied to), some threads are very
30 long.
31 The "Mail::Box::Thread::Manager" is very powerful. Not only is it able
33 to do a descent job on MH-like folders (makes a trade-off between per‐
34 fection and speed), it also can maintain threads from messages residing
35 in different opened folders. Both facilities are rare for mail-agents.
36 The manager creates flexible trees with Mail::Box::Thread::Node
37 objects.
38
40 Constructors
41 Mail::Box::Thread::Manager->new(OPTIONS)
43 A "Mail::Box::Thread::Manager" object is usually created by a
45 Mail::Box::Manager. One manager can produce more than one of these
46 objects. One thread manager can combine messages from a set of
47 folders, which may be partially overlapping with other objects of
48 the same type.
49 Option --Defined in --Default
51 dummy_type Mail::Message::Dummy
52 folder [ ]
53 folders [ ]
54 log Mail::Reporter 'WARNINGS'
55 thread_body <false>
56 thread_type Mail::Box::Thread::Node
57 timespan '3 days'
58 trace Mail::Reporter 'WARNINGS'
59 window 10
60 . dummy_type CLASS
62 The type of dummy messages. Dummy messages are used to fill
64 holes in detected threads: referred to by messages found in the
65 folder, but itself not in the folder.
66 . folder FOLDER ⎪ REF-ARRAY-FOLDERS
68 Specifies which folders are to be covered by the threads. You
70 can specify one or more open folders. When you close a folder,
71 the manager will automatically remove the messages of that
72 folder from your threads.
73 . folders FOLDER ⎪ REF-ARRAY-FOLDERS
75 Equivalent to the "folder" option.
77 . log LEVEL
79 . thread_body BOOLEAN
81 May thread-detection be based on the content of a message?
83 This has a serious performance implication when there are many
84 messages without "In-Reply-To" and "References" headers in the
85 folder, because it will cause many messages to be parsed. NOT
86 IMPLEMENTED YET.
87 . thread_type CLASS
89 Type of the thread nodes.
91 . timespan TIME ⎪ 'EVER'
93 Specify how fast threads usually work: the amount of time
95 between an answer and a reply. This is used in combination
96 with the "window" option to determine when to give-up filling
97 the holes in threads.
98 See Mail::Box::timespan2seconds() for the possibilities for
100 TIME. With 'EVER', the search for messages in a thread will
101 only be limited by the window-size.
102 . trace LEVEL
104 . window INTEGER⎪'ALL'
106 The thread-window describes how many messages should be checked
108 at maximum to fill `holes' in threads for folder which use
109 delay-loading of message headers.
110 The constant 'ALL' will cause thread-detection not to stop try‐
112 ing to fill holes, but continue looking until the first message
113 of the folder is reached. Gives the best quality results, but
114 may perform bad.
115 Example:
117 use Mail::Box::Manager;
119 my $mgr = new Mail::Box::Manager;
120 my $inbox = $mgr->open(folder => $ENV{MAIL});
121 my $read = $mgr->open(folder => 'Mail/read');
122 my $threads = $mgr->threads(folders => [$inbox, $read]);
123 # longer alternative for last line:
125 my $threads = $mgr->threads;
126 $threads->includeFolder($inbox);
127 $threads->includeFolder($read);
128 Grouping Folders
130 $obj->folders
132 Returns the folders as managed by this threader.
134 $obj->includeFolder(FOLDERS)
136 Add one or more folders to the list of folders whose messages are
138 organized in the threads maintained by this object. Duplicated
139 inclusions will not cause any problems.
140 From the folders, the messages which have their header lines parsed
142 (see Mail::Box about lazy extracting) will be immediately scanned.
143 Messages of which the header is known only later will have to
144 report this (see toBeThreaded()).
145 Example:
147 $threads->includeFolder($inbox, $draft);
149 $obj->removeFolder(FOLDERS)
151 Remove one or more folders from the list of folders whose messages
153 are organized in the threads maintained by this object.
154 Example:
156 $threads->removeFolder($draft);
158 The Threads
160 $obj->all
162 Returns all messages which start a thread. The list may contain
164 dummy messages and messages which are scheduled for deletion.
165 To be able to return all threads, thread construction on each mes‐
167 sage is performed first, which may be slow for some folder-types
168 because is will enforce parsing of message-bodies.
169 $obj->known
171 Returns the list of all messages which are known to be the start of
173 a thread. Threads containing messages which where not read from
174 their folder (like often happens MH-folder messages) are not yet
175 known, and hence will not be returned.
176 The list may contain dummy messages, and messages which are sched‐
178 uled for deletion. Threads are detected based on explicitly call‐
179 ing inThread() and thread() with a messages from the folder.
180 Be warned that, each time a message's header is read from the
182 folder, the return of the method can change.
183 $obj->sortedAll([PREPARE [COMPARE]])
185 Returns all() the threads by default, but sorted on timestamp.
187 $obj->sortedKnown([PREPARE [,COMPARE]])
189 Returns all known() threads, in sorted order. By default, the
191 threads will be sorted on timestamp, But a different COMPARE method
192 can be specified.
193 $obj->thread(MESSAGE)
195 Returns the thread where this MESSAGE is the start of. However,
197 there is a possibility that this message is a reply itself.
198 Usually, all messages which are in reply of this message are dated
200 later than the specified one. All headers of messages later than
201 this one are getting parsed first, for each folder in this
202 threads-object.
203 Example:
205 my $threads = $mgr->threads(folder => $inbox);
207 my $thread = $threads->thread($inbox->message(3));
208 print $thread->string;
209 $obj->threadStart(MESSAGE)
211 Based on a message, and facts from previously detected threads, try
213 to build solid knowledge about the thread where this message is in.
214 Internals
216 $obj->createDummy(MESSAGE-ID)
218 Get a replacement message to be used in threads. Be warned that a
220 dummy is not a member of any folder, so the program working with
221 threads must test with Mail::Message::isDummy() before trying
222 things only available to real messages.
223 $obj->inThread(MESSAGE)
225 Collect the thread-information of one message. The `In-Reply-To'
227 and `Reference' header-fields are processed. If this method is
228 called on a message whose header was not read yet (as usual for
229 MH-folders, for instance) the reading of that header will be trig‐
230 gered here.
231 $obj->outThread(MESSAGE)
233 Remove the message from the thread-infrastructure. A message is
235 replaced by a dummy.
236 $obj->toBeThreaded(FOLDER, MESSAGES)
238 Include the specified messages in/from the threads managed by this
240 object, if this folder is maintained by this thread-manager.
241 $obj->toBeUnthreaded(FOLDER, MESSAGES)
243 Remove the specified messages in/from the threads managed by this
245 object, if this folder is maintained by this thread-manager.
246 Error handling
248 $obj->AUTOLOAD
250 See "Error handling" in Mail::Reporter
252 $obj->addReport(OBJECT)
254 See "Error handling" in Mail::Reporter
256 $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
258 Mail::Box::Thread::Manager->defaultTrace([LEVEL]⎪[LOGLEVEL,
260 TRACELEVEL]⎪[LEVEL, CALLBACK])
261 See "Error handling" in Mail::Reporter
263 $obj->errors
265 See "Error handling" in Mail::Reporter
267 $obj->log([LEVEL [,STRINGS]])
269 Mail::Box::Thread::Manager->log([LEVEL [,STRINGS]])
271 See "Error handling" in Mail::Reporter
273 $obj->logPriority(LEVEL)
275 Mail::Box::Thread::Manager->logPriority(LEVEL)
277 See "Error handling" in Mail::Reporter
279 $obj->logSettings
281 See "Error handling" in Mail::Reporter
283 $obj->notImplemented
285 See "Error handling" in Mail::Reporter
287 $obj->report([LEVEL])
289 See "Error handling" in Mail::Reporter
291 $obj->reportAll([LEVEL])
293 See "Error handling" in Mail::Reporter
295 $obj->trace([LEVEL])
297 See "Error handling" in Mail::Reporter
299 $obj->warnings
301 See "Error handling" in Mail::Reporter
303 Cleanup
305 $obj->DESTROY
307 See "Cleanup" in Mail::Reporter
309 $obj->inGlobalDestruction
311 See "Cleanup" in Mail::Reporter
313
315 This module implements thread-detection on a folder. Messages created
316 by the better mailers will include "In-Reply-To" and "References"
317 lines, which are used to figure out how messages are related. If you
318 prefer a better thread detection, they are implementable, but there may
319 be a serious performance hit (depends on the type of folder used).
320 Maintaining threads
322 A "Mail::Box::Thread::Manager" object is created by the Mail::Box::Man‐
324 ager, using Mail::Box::Manager::threads(). Each object can monitor the
325 thread-relations between messages in one or more folders. When more
326 than one folder is specified, the messages are merged while reading the
327 threads, although nothing changes in the folder-structure. Adding and
328 removing folders which have to be maintained is permitted at any
329 moment, although may be quite costly in performance.
330 An example of the maintained structure is shown below. The
332 Mail::Box::Manager has two open folders, and a thread-builder which
333 monitors them both. The combined folders have two threads, the second
334 is two long (msg3 is a reply on msg2). Msg2 is in two folders at once.
335 manager
337 ⎪ \
338 ⎪ `----------- threads
339 ⎪ ⎪ ⎪
340 ⎪ thread thread---thread
341 ⎪ ⎪ /⎪ /
342 ⎪ ⎪ // /
343 +---- folder1 ⎪ // /
344 ⎪ ⎪ / // /
345 ⎪ `-----msg1 // /
346 ⎪ `-----msg2-'/ /
347 ⎪ / /
348 `-----folder2 / /
349 ⎪ / /
350 `-----msg2 /
351 `-----msg3------'
352 Delayed thread detection
354 With all() you get the start-messages of each thread of this folder.
356 When that message was not found in the folder (not saved or already
357 removed), you get a message of the dummy-type. These thread descrip‐
358 tions are in perfect state: all messages of the folder are included
359 somewhere, and each missing message of the threads (holes) are filled
360 by dummies.
361 However, to be able to detect all threads it is required to have the
363 headers of all messages, which is very slow for some types of folders,
364 especially MH and IMAP folders.
365 For interactive mail-readers, it is preferred to detect threads only on
367 messages which are in the viewport of the user. This may be sloppy in
368 some situations, but everything is preferable over reading an MH mail‐
369 box with 10k e-mails to read only the see most recent messages.
370 In this object, we take special care not to cause unnecessary parsing
372 (loading) of messages. Threads will only be detected on command, and
373 by default only the message headers are used.
374 The following reports the Mail::Box::Thread::Node which is related to a
376 message:
377 my $thread = $message->thread;
379 When the message was not put in a thread yet, it is done now. But,
381 more work is done to return the best thread. Based on various parame‐
382 ters, which where specified when the folder was created, the method
383 walks through the folder to fill the holes which are in this thread.
384 Walking from back to front (recently arrived messages are usually in
386 the back of the folder), message after message are triggered to be
387 included in their thread. At a certain moment, the whole thread of the
388 requested method is found, a certain maximum number of messages was
389 tried, but that didn't help (search window bound reached), or the mes‐
390 sages within the folder are getting too old. Then the search to com‐
391 plete the thread will end, although more messages of them might have
392 been in the folder: we don't scan the whole folder for performance rea‐
393 sons.
394 Finally, for each message where the head is known, for instance for all
396 messages in mbox-folders, the correct thread is determined immediately.
397 Also, all messages where the head get loaded later, are automatically
398 included.
399
401 Error: Package $package does not implement $method.
402 Fatal error: the specific package (or one of its superclasses) does not
404 implement this method where it should. This message means that some
405 other related classes do implement this method however the class at
406 hand does not. Probably you should investigate this and probably
407 inform the author of the package.
408
410 This module is part of Mail-Box distribution version 2.070, built on
411 March 25, 2007. Website: http://perl.overmeer.net/mailbox/
412
414 Copyrights 2001-2007 by Mark Overmeer.For other contributors see
415 ChangeLog.
416 This program is free software; you can redistribute it and/or modify it
418 under the same terms as Perl itself. See
419 http://www.perl.com/perl/misc/Artistic.html
420perl v5.8.8 2007-03-25 Mail::Box::Thread::Manager(3)