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
25       message in more folders.  All versions of the same message (based on
26       message-id) are stored in the same node.
27

METHODS

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

DIAGNOSTICS

313       Error: Package $package does not implement $method.
314           Fatal error: the specific package (or one of its superclasses) does
315           not implement this method where it should. This message means that
316           some other related classes do implement this method however the
317           class at hand does not.  Probably you should investigate this and
318           probably inform the author of the package.
319

LICENSE

325       Copyrights 2001-2011 by Mark Overmeer. For other contributors see
326       ChangeLog.
327
328       This program is free software; you can redistribute it and/or modify it
329       under the same terms as Perl itself.  See
330       http://www.perl.com/perl/misc/Artistic.html
331
332
333
334perl v5.12.3                      2011-01-26        Mail::Box::Thread::Node(3)