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
34 perfection and speed), it also can maintain threads from messages
35 residing in different opened folders. Both facilities are rare for
36 mail-agents. The manager creates flexible trees with
37 Mail::Box::Thread::Node objects.
38
40 Constructors
41 Mail::Box::Thread::Manager->new(OPTIONS)
42 A "Mail::Box::Thread::Manager" object is usually created by a
43 Mail::Box::Manager. One manager can produce more than one of these
44 objects. One thread manager can combine messages from a set of
45 folders, which may be partially overlapping with other objects of
46 the same type.
47 -Option --Defined in --Default
49 dummy_type Mail::Message::Dummy
50 folder [ ]
51 folders [ ]
52 log Mail::Reporter 'WARNINGS'
53 thread_body <false>
54 thread_type Mail::Box::Thread::Node
55 timespan '3 days'
56 trace Mail::Reporter 'WARNINGS'
57 window 10
58 dummy_type => CLASS
60 The type of dummy messages. Dummy messages are used to fill
61 holes in detected threads: referred to by messages found in the
62 folder, but itself not in the folder.
63 folder => FOLDER | REF-ARRAY-FOLDERS
65 Specifies which folders are to be covered by the threads. You
66 can specify one or more open folders. When you close a folder,
67 the manager will automatically remove the messages of that folder
68 from your threads.
69 folders => FOLDER | REF-ARRAY-FOLDERS
71 Equivalent to the "folder" option.
72 log => LEVEL
74 thread_body => BOOLEAN
75 May thread-detection be based on the content of a message? This
76 has a serious performance implication when there are many
77 messages without "In-Reply-To" and "References" headers in the
78 folder, because it will cause many messages to be parsed. NOT
79 IMPLEMENTED YET.
80 thread_type => CLASS
82 Type of the thread nodes.
83 timespan => TIME | 'EVER'
85 Specify how fast threads usually work: the amount of time between
86 an answer and a reply. This is used in combination with the
87 "window" option to determine when to give-up filling the holes in
88 threads.
89 See Mail::Box::timespan2seconds() for the possibilities for TIME.
91 With 'EVER', the search for messages in a thread will only be
92 limited by the window-size.
93 trace => LEVEL
95 window => INTEGER|'ALL'
96 The thread-window describes how many messages should be checked
97 at maximum to fill `holes' in threads for folder which use delay-
98 loading of message headers.
99 The constant 'ALL' will cause thread-detection not to stop trying
101 to fill holes, but continue looking until the first message of
102 the folder is reached. Gives the best quality results, but may
103 perform bad.
104 example:
106 use Mail::Box::Manager;
108 my $mgr = new Mail::Box::Manager;
109 my $inbox = $mgr->open(folder => $ENV{MAIL});
110 my $read = $mgr->open(folder => 'Mail/read');
111 my $threads = $mgr->threads(folders => [$inbox, $read]);
112 # longer alternative for last line:
114 my $threads = $mgr->threads;
115 $threads->includeFolder($inbox);
116 $threads->includeFolder($read);
117 Grouping Folders
119 $obj->folders
120 Returns the folders as managed by this threader.
121 $obj->includeFolder(FOLDERS)
123 Add one or more folders to the list of folders whose messages are
124 organized in the threads maintained by this object. Duplicated
125 inclusions will not cause any problems.
126 From the folders, the messages which have their header lines parsed
128 (see Mail::Box about lazy extracting) will be immediately scanned.
129 Messages of which the header is known only later will have to
130 report this (see toBeThreaded()).
131 example:
133 $threads->includeFolder($inbox, $draft);
135 $obj->removeFolder(FOLDERS)
137 Remove one or more folders from the list of folders whose messages
138 are organized in the threads maintained by this object.
139 example:
141 $threads->removeFolder($draft);
143 The Threads
145 $obj->all
146 Returns all messages which start a thread. The list may contain
147 dummy messages and messages which are scheduled for deletion.
148 To be able to return all threads, thread construction on each
150 message is performed first, which may be slow for some folder-types
151 because is will enforce parsing of message-bodies.
152 $obj->known
154 Returns the list of all messages which are known to be the start of
155 a thread. Threads containing messages which where not read from
156 their folder (like often happens MH-folder messages) are not yet
157 known, and hence will not be returned.
158 The list may contain dummy messages, and messages which are
160 scheduled for deletion. Threads are detected based on explicitly
161 calling inThread() and thread() with a messages from the folder.
162 Be warned that, each time a message's header is read from the
164 folder, the return of the method can change.
165 $obj->sortedAll([PREPARE [COMPARE]])
167 Returns all() the threads by default, but sorted on timestamp.
168 $obj->sortedKnown([PREPARE [,COMPARE]])
170 Returns all known() threads, in sorted order. By default, the
171 threads will be sorted on timestamp, But a different COMPARE method
172 can be specified.
173 $obj->thread(MESSAGE)
175 Returns the thread where this MESSAGE is the start of. However,
176 there is a possibility that this message is a reply itself.
177 Usually, all messages which are in reply of this message are dated
179 later than the specified one. All headers of messages later than
180 this one are getting parsed first, for each folder in this threads-
181 object.
182 example:
184 my $threads = $mgr->threads(folder => $inbox);
186 my $thread = $threads->thread($inbox->message(3));
187 print $thread->string;
188 $obj->threadStart(MESSAGE)
190 Based on a message, and facts from previously detected threads, try
191 to build solid knowledge about the thread where this message is in.
192 Internals
194 $obj->createDummy(MESSAGE-ID)
195 Get a replacement message to be used in threads. Be warned that a
196 dummy is not a member of any folder, so the program working with
197 threads must test with Mail::Message::isDummy() before trying
198 things only available to real messages.
199 $obj->inThread(MESSAGE)
201 Collect the thread-information of one message. The `In-Reply-To'
202 and `Reference' header-fields are processed. If this method is
203 called on a message whose header was not read yet (as usual for MH-
204 folders, for instance) the reading of that header will be triggered
205 here.
206 $obj->outThread(MESSAGE)
208 Remove the message from the thread-infrastructure. A message is
209 replaced by a dummy.
210 $obj->toBeThreaded(FOLDER, MESSAGES)
212 Include the specified messages in/from the threads managed by this
213 object, if this folder is maintained by this thread-manager.
214 $obj->toBeUnthreaded(FOLDER, MESSAGES)
216 Remove the specified messages in/from the threads managed by this
217 object, if this folder is maintained by this thread-manager.
218 Error handling
220 $obj->AUTOLOAD
221 See "Error handling" in Mail::Reporter
222 $obj->addReport(OBJECT)
224 See "Error handling" in Mail::Reporter
225 $obj->defaultTrace([LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK])
227 Mail::Box::Thread::Manager->defaultTrace([LEVEL]|[LOGLEVEL,
228 TRACELEVEL]|[LEVEL, CALLBACK])
229 See "Error handling" in Mail::Reporter
231 $obj->errors
233 See "Error handling" in Mail::Reporter
234 $obj->log([LEVEL [,STRINGS]])
236 Mail::Box::Thread::Manager->log([LEVEL [,STRINGS]])
237 See "Error handling" in Mail::Reporter
239 $obj->logPriority(LEVEL)
241 Mail::Box::Thread::Manager->logPriority(LEVEL)
242 See "Error handling" in Mail::Reporter
244 $obj->logSettings
246 See "Error handling" in Mail::Reporter
247 $obj->notImplemented
249 See "Error handling" in Mail::Reporter
250 $obj->report([LEVEL])
252 See "Error handling" in Mail::Reporter
253 $obj->reportAll([LEVEL])
255 See "Error handling" in Mail::Reporter
256 $obj->trace([LEVEL])
258 See "Error handling" in Mail::Reporter
259 $obj->warnings
261 See "Error handling" in Mail::Reporter
262 Cleanup
264 $obj->DESTROY
265 See "Cleanup" in Mail::Reporter
266 $obj->inGlobalDestruction
268 See "Cleanup" in Mail::Reporter
269
271 Maintaining threads
272 A "Mail::Box::Thread::Manager" object is created by the
273 Mail::Box::Manager, using Mail::Box::Manager::threads(). Each object
274 can monitor the thread-relations between messages in one or more
275 folders. When more than one folder is specified, the messages are
276 merged while reading the threads, although nothing changes in the
277 folder-structure. Adding and removing folders which have to be
278 maintained is permitted at any moment, although may be quite costly in
279 performance.
280 An example of the maintained structure is shown below. The
282 Mail::Box::Manager has two open folders, and a thread-builder which
283 monitors them both. The combined folders have two threads, the second
284 is two long (msg3 is a reply on msg2). Msg2 is in two folders at once.
285 manager
287 | \
288 | `----------- threads
289 | | |
290 | thread thread---thread
291 | | /| /
292 | | // /
293 +---- folder1 | // /
294 | | / // /
295 | `-----msg1 // /
296 | `-----msg2-'/ /
297 | / /
298 `-----folder2 / /
299 | / /
300 `-----msg2 /
301 `-----msg3------'
302 Delayed thread detection
304 With all() you get the start-messages of each thread of this folder.
305 When that message was not found in the folder (not saved or already
306 removed), you get a message of the dummy-type. These thread
307 descriptions are in perfect state: all messages of the folder are
308 included somewhere, and each missing message of the threads (holes) are
309 filled by dummies.
310 However, to be able to detect all threads it is required to have the
312 headers of all messages, which is very slow for some types of folders,
313 especially MH and IMAP folders.
314 For interactive mail-readers, it is preferred to detect threads only on
316 messages which are in the viewport of the user. This may be sloppy in
317 some situations, but everything is preferable over reading an MH
318 mailbox with 10k e-mails to read only the see most recent messages.
319 In this object, we take special care not to cause unnecessary parsing
321 (loading) of messages. Threads will only be detected on command, and
322 by default only the message headers are used.
323 The following reports the Mail::Box::Thread::Node which is related to a
325 message:
326 my $thread = $message->thread;
328 When the message was not put in a thread yet, it is done now. But,
330 more work is done to return the best thread. Based on various
331 parameters, which where specified when the folder was created, the
332 method walks through the folder to fill the holes which are in this
333 thread.
334 Walking from back to front (recently arrived messages are usually in
336 the back of the folder), message after message are triggered to be
337 included in their thread. At a certain moment, the whole thread of the
338 requested method is found, a certain maximum number of messages was
339 tried, but that didn't help (search window bound reached), or the
340 messages within the folder are getting too old. Then the search to
341 complete the thread will end, although more messages of them might have
342 been in the folder: we don't scan the whole folder for performance
343 reasons.
344 Finally, for each message where the head is known, for instance for all
346 messages in mbox-folders, the correct thread is determined immediately.
347 Also, all messages where the head get loaded later, are automatically
348 included.
349 This module implements thread-detection on a folder. Messages created
351 by the better mailers will include "In-Reply-To" and "References"
352 lines, which are used to figure out how messages are related. If you
353 prefer a better thread detection, they are implementable, but there may
354 be a serious performance hit (depends on the type of folder used).
355
357 Error: Package $package does not implement $method.
358 Fatal error: the specific package (or one of its superclasses) does
359 not implement this method where it should. This message means that
360 some other related classes do implement this method however the
361 class at hand does not. Probably you should investigate this and
362 probably inform the author of the package.
363
365 This module is part of Mail-Box distribution version 2.097, built on
366 January 26, 2011. Website: http://perl.overmeer.net/mailbox/
367
369 Copyrights 2001-2011 by Mark Overmeer. For other contributors see
370 ChangeLog.
371 This program is free software; you can redistribute it and/or modify it
373 under the same terms as Perl itself. See
374 http://www.perl.com/perl/misc/Artistic.html
375perl v5.12.3 2011-01-26 Mail::Box::Thread::Manager(3)