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::Manager->new;
14 my $folder = $mgr->open(folder => '/tmp/inbox');
15 my $threads = $mgr->threads();
17 $threads->includeFolder($folder);
18 my $threads = $msg->threads(folder => $folder);
20 foreach my $thread ($threads->all) {
22 $thread->print;
23 }
24 $threads->removeFolder($folder);
26
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 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 Extends "DESCRIPTION" in Mail::Reporter.
42
44 Extends "METHODS" in Mail::Reporter.
45 Constructors
47 Extends "Constructors" in Mail::Reporter.
48 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 -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 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 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 folders => FOLDER | REF-ARRAY-FOLDERS
79 Equivalent to the "folder" option.
80 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 thread_type => CLASS
90 Type of the thread nodes.
91 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 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 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 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 example:
114 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 # longer alternative for last line:
122 my $threads = $mgr->threads;
123 $threads->includeFolder($inbox);
124 $threads->includeFolder($read);
125 Grouping Folders
127 $obj->folders()
128 Returns the folders as managed by this threader.
129 $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 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 example:
141 $threads->includeFolder($inbox, $draft);
143 $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 example:
149 $threads->removeFolder($draft);
151 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 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 $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 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 Be warned that, each time a message's header is read from the
172 folder, the return of the method can change.
173 $obj->sortedAll( [$prepare, [$compare]] )
175 Returns all() the threads by default, but sorted on timestamp.
176 $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 $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 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 example:
192 my $threads = $mgr->threads(folder => $inbox);
194 my $thread = $threads->thread($inbox->message(3));
195 print $thread->string;
196 $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 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 $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 $obj->outThread($message)
216 Remove the message from the thread-infrastructure. A message is
217 replaced by a dummy.
218 $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 $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 Error handling
228 Extends "Error handling" in Mail::Reporter.
229 $obj->AUTOLOAD()
231 Inherited, see "Error handling" in Mail::Reporter
232 $obj->addReport($object)
234 Inherited, see "Error handling" in Mail::Reporter
235 $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 $obj->errors()
243 Inherited, see "Error handling" in Mail::Reporter
244 $obj->log( [$level, [$strings]] )
246 Mail::Box::Thread::Manager->log( [$level, [$strings]] )
247 Inherited, see "Error handling" in Mail::Reporter
248 $obj->logPriority($level)
250 Mail::Box::Thread::Manager->logPriority($level)
251 Inherited, see "Error handling" in Mail::Reporter
252 $obj->logSettings()
254 Inherited, see "Error handling" in Mail::Reporter
255 $obj->notImplemented()
257 Inherited, see "Error handling" in Mail::Reporter
258 $obj->report( [$level] )
260 Inherited, see "Error handling" in Mail::Reporter
261 $obj->reportAll( [$level] )
263 Inherited, see "Error handling" in Mail::Reporter
264 $obj->trace( [$level] )
266 Inherited, see "Error handling" in Mail::Reporter
267 $obj->warnings()
269 Inherited, see "Error handling" in Mail::Reporter
270 Cleanup
272 Extends "Cleanup" in Mail::Reporter.
273 $obj->DESTROY()
275 Inherited, see "Cleanup" in Mail::Reporter
276
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 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 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 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 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 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 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 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 The following reports the Mail::Box::Thread::Node which is related to a
338 message:
339 my $thread = $message->thread;
341 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 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 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
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
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
376 Copyrights 2001-2020 by [Mark Overmeer]. For other contributors see
377 ChangeLog.
378 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/
381perl v5.32.1 2021-01-27 Mail::Box::Thread::Manager(3)