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
28       Extends "DESCRIPTION" in Mail::Reporter.
29

METHODS

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

DIAGNOSTICS

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

LICENSE

330       Copyrights 2001-2018 by [Mark Overmeer]. For other contributors see
331       ChangeLog.
332
333       This program is free software; you can redistribute it and/or modify it
334       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
335
336
337
338perl v5.28.0                      2018-03-04        Mail::Box::Thread::Node(3)