Mail::Box::Thread::Node(3pm)

1Mail::Box::Thread::NodeU(s3e)r Contributed Perl DocumentaMtaiioln::Box::Thread::Node(3)
2
3
4

NAME

6       Mail::Box::Thread::Node - one node in a message thread
7

INHERITANCE

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

SYNOPSIS

13        my $node = Mail::Box::Thread::Node->new;
14        $node->addMessage($message);
15        ...
16

DESCRIPTION

18       The "Mail::Box::Thread::Node" maintains one node in the linked list of
19       threads.  Each node contains one message, and a list of its follow-ups.
20       Next to that, it refers to its own ancestor and contains information
21       about the trustworthiness of that relationship.
22
23       To complicate things a little, because the thread-manager can maintain
24       multiple folders, and merge there content, you may find the same mes‐
25       sage in more folders.  All versions of the same message (based on mes‐
26       sage-id) are stored in the same node.
27

METHODS

29       Constructors
30
31       Mail::Box::Thread::Node->new(OPTIONS)
32
33           You will not call this method yourself. The Mail::Box::Thread::Man‐
34           ager object will call it to construct "Mail::Box::Thread::Node"
35           objects.  Either a "message" or a "messageId" must be supplied.
36
37            Option    --Defined in     --Default
38            dummy_type                   undef
39            log         Mail::Reporter   'WARNINGS'
40            message                      undef
41            messageId                    undef
42            trace       Mail::Reporter   'WARNINGS'
43
44           . dummy_type CLASS
45
46               Indicates the class name of dummy messages. Dummy messages are
47               placeholders in a Mail::Box::Thread::Manager data structure.
48
49           . log LEVEL
50
51           . message MESSAGE
52
53               The MESSAGE which is stored in this node.  The message must be
54               a Mail::Box::Message.
55
56           . messageId MESSAGE-ID
57
58               The MESSAGE-ID for the message which is stored in this node.
59               Only specify it when you don't have the message yet.
60
61           . trace LEVEL
62
63       The thread node
64
65       $obj->addMessage(MESSAGE)
66
67           Add one message to the thread node.  If the node contains a dummy,
68           then the dummy is replaced. Otherwise, the messages is added to the
69           end of the list.
70
71       $obj->expand([BOOLEAN])
72
73           Returns whether this (part of the) folder has to be shown expanded
74           or not.  This is simply done by a label, which means that most
75           folder types can store this.
76
77       $obj->isDummy
78
79           Returns true if the message is a dummy. A dummy is a "hole" in a
80           thread which has follow-ups but does not have a message.
81
82       $obj->message
83
84           Get the message which is stored in this thread node.  NOTE: the
85           same message may be located in many folders at the same time, and
86           these folders may be controlled by the same thread manager.
87
88           In scalar context, this method returns the first instance of the
89           message that is not deleted. If all instances are flagged for dele‐
90           tion, then you get the first deleted message. When the open folders
91           only contain references to the message, but no instance, you get a
92           dummy message (see Mail::Message::Dummy).
93
94           In list context, all instances of the message which have been found
95           are returned.
96
97           Example:
98
99            my $threads = $mgr->threads(folders => [$draft, $sent]);
100            my $node    = $draft->message(1)->thread;
101
102            foreach my $instance ($node->message) {
103               print "Found in ", $instance->folder, ".\n";
104            }
105
106            print "Subject is ", $node->message->subject, ".\n";
107
108       $obj->messageId
109
110           Return the message-id related to this thread node.  Each of the
111           messages listed in this node will have the same ID.
112
113       The thread order
114
115       $obj->followUps
116
117           Returns the list of follow-ups to this thread node.  This list may
118           contain parsed, not-parsed, and dummy messages.
119
120       $obj->followedBy(THREADS)
121
122           Register that the THREADS are follow-ups to this message. These
123           follow-ups need not be related to each other in any way other than
124           sharing the same parent.
125
126           Defining the same relation more than once will not cause informa‐
127           tion to be duplicated.
128
129       $obj->follows(THREAD, QUALITY)
130
131           Register that the current thread is a reply to the specified
132           THREAD. The QUALITY of the relation is specified by the second
133           argument.  The method returns "undef" if the link is not accepted
134           in order to avoid circular references.
135
136           The relation may be specified more than once, but only the most
137           confident relation is used. For example, if a reply (QUALITY equals
138           "REPLY") is specified, later calls to the follow method will have
139           no effect. If "follows" is called with a QUALITY that matches the
140           current quality, the new thread overrides the previous.
141
142       $obj->repliedTo
143
144           Returns the message(s) to which the message in this node replies.
145           In scalar context, this method will return the message to which the
146           message in this node replies. This message object may be a dummy
147           message.
148
149           If the message seems to be the first message of a thread, the value
150           "undef" is returned.  (Remember that some MUA are not adding refer‐
151           ence information to the message's header, so you can never be sure
152           a message is the start of a thread)
153
154           In list context, this method returns a second string value indicat‐
155           ing the confidence that the messages are related.  When extended
156           thread discovery is enabled, then some heuristics are applied to
157           determine if messages are related. Values for the STRING may be:
158
159           * 'REPLY'
160               This relation was directly derived from an `in-reply-to' mes‐
161               sage header field. The relation has a high confidence.
162
163           * 'REFERENCE'
164               This relation is based on information found in a `Reference'
165               message header field.  One message may reference a list of mes‐
166               sages which precede it in the thread. The heuristic attempts to
167               determine relationships between messages assuming that the ref‐
168               erences are in order.  This relation has a lower confidence.
169
170           * 'GUESS'
171               The relation is a big guess, with low confidence.  It may be
172               based on a subject which seems to be related, or commonalities
173               in the message's body.
174
175           More constants may be added later.
176
177           Example:
178
179            my $question = $answer->repliedTo;
180            my ($question, $quality) = $answer->repliedTo;
181            if($question && $quality eq 'REPLY') { ... };
182
183       $obj->sortedFollowUps([PREPARE [,COMPARE]])
184
185           Returns the list of followUps(), but sorted.  By default sorting is
186           based on the estimated time of the reply. See startTimeEstimate().
187
188       On the whole thread
189
190       Some convenience methods are added to threads, to simplify retrieving
191       information from it.
192
193       $obj->endTimeEstimate
194
195           Returns a guess as to when the thread has ended (although you never
196           know for sure whether there fill follow messages in the future).
197
198       $obj->ids
199
200           Returns all the ids in the thread starting at the current thread
201           node.
202
203           Example:
204
205            $newfolder->addMessages($folder->ids($thread->ids));
206            $folder->delete($thread->ids);
207
208       $obj->numberOfMessages
209
210           Number of messages in the thread starting at the current thread
211           node, but not counting the dummies.
212
213       $obj->recurse(CODE-REF)
214
215           Execute a function for all sub-threads.  If the subroutine returns
216           true, sub-threads are visited recursively. Otherwise, the current
217           branch traversal is aborted. The routine is called with the thread-
218           node as the only argument.
219
220       $obj->startTimeEstimate
221
222           Returns a guess as to when the thread was started.  Each message
223           contains various date specifications (each with various uncertain‐
224           ties resulting from timezones and out-of-sync clocks). One of these
225           date specifications is used as the timestamp for the message. If
226           the node contains a dummy message the lowest timestamp of the
227           replies is returned. Otherwise the estimated timestamp of the
228           node's message is returned.
229
230       $obj->threadMessages
231
232           Returns all the messages in the thread starting at the current
233           thread node.  This list will not include dummies.
234
235           Example:
236
237            my @t = $folder->message(3)
238                           ->threadStart
239                           ->threadMessages;
240
241       $obj->threadToString([CODE])
242
243           Translate a thread into a string. The string will contain at least
244           one line for each message which was found, but tries to fold dum‐
245           mies.  This is useful for debugging, but most message readers will
246           prefer to implement their own thread printer.
247
248           The optional CODE argument is a reference to a routine which will
249           be called for each message in the thread.  The routine will be
250           called with the message as the first argument.  The default shows
251           the subject of the message.  In the first example below, this rou‐
252           tine is called seven times.
253
254           Example:
255
256            print $node->threadToString;
257
258           may result in
259
260            Subject of this message
261            ⎪- Re: Subject of this message
262            ⎪-*- Re: Re: Subject of this message
263            ⎪ ⎪- Re(2) Subject of this message
264            ⎪ ⎪- [3] Re(2) Subject of this message
265            ⎪ `- Re: Subject of this message (reply)
266            `- Re: Subject of this message
267
268           The `*' represents a missing message (a "dummy" message).  The
269           `[3]' presents a folded thread with three messages.
270
271            print $node->threadToString(\&show);
272
273            sub show($) {
274               my $message = shift;
275               my $subject = $message->head->get('subject');
276               length $subject ? $subject : '<no subject>';
277            }
278
279       $obj->totalSize
280
281           Returns the sum of the size of all the messages in the thread.
282
283       Error handling
284
285       $obj->AUTOLOAD
286
287           See "Error handling" in Mail::Reporter
288
289       $obj->addReport(OBJECT)
290
291           See "Error handling" in Mail::Reporter
292
293       $obj->defaultTrace([LEVEL]⎪[LOGLEVEL, TRACELEVEL]⎪[LEVEL, CALLBACK])
294
295       Mail::Box::Thread::Node->defaultTrace([LEVEL]⎪[LOGLEVEL,
296       TRACELEVEL]⎪[LEVEL, CALLBACK])
297
298           See "Error handling" in Mail::Reporter
299
300       $obj->errors
301
302           See "Error handling" in Mail::Reporter
303
304       $obj->log([LEVEL [,STRINGS]])
305
306       Mail::Box::Thread::Node->log([LEVEL [,STRINGS]])
307
308           See "Error handling" in Mail::Reporter
309
310       $obj->logPriority(LEVEL)
311
312       Mail::Box::Thread::Node->logPriority(LEVEL)
313
314           See "Error handling" in Mail::Reporter
315
316       $obj->logSettings
317
318           See "Error handling" in Mail::Reporter
319
320       $obj->notImplemented
321
322           See "Error handling" in Mail::Reporter
323
324       $obj->report([LEVEL])
325
326           See "Error handling" in Mail::Reporter
327
328       $obj->reportAll([LEVEL])
329
330           See "Error handling" in Mail::Reporter
331
332       $obj->trace([LEVEL])
333
334           See "Error handling" in Mail::Reporter
335
336       $obj->warnings
337
338           See "Error handling" in Mail::Reporter
339
340       Cleanup
341
342       $obj->DESTROY
343
344           See "Cleanup" in Mail::Reporter
345
346       $obj->inGlobalDestruction
347
348           See "Cleanup" in Mail::Reporter
349

DIAGNOSTICS

351       Error: Package $package does not implement $method.
352
353       Fatal error: the specific package (or one of its superclasses) does not
354       implement this method where it should. This message means that some
355       other related classes do implement this method however the class at
356       hand does not.  Probably you should investigate this and probably
357       inform the author of the package.
358

LICENSE

364       Copyrights 2001-2007 by Mark Overmeer.For other contributors see
365       ChangeLog.
366
367       This program is free software; you can redistribute it and/or modify it
368       under the same terms as Perl itself.  See
369       http://www.perl.com/perl/misc/Artistic.html
370
371
372
373perl v5.8.8                       2007-03-25        Mail::Box::Thread::Node(3)