Mail::Box::Thread - one discussion thread in a folder
|
Mail::Box::Thread - one discussion thread in a folder
my $thread = $message->thread;
$thread->printThread;
Read the Mail::Box::Manager manpage and the Mail::Box::Threads manpage first.
A (message-)thread is a message, with the messages which followed in
reply on that message. And the messages with replied the messages
which replied the original message. And so on. Some threads are only
one message (never replied to), some threads are very long.
- new ARGS
-
The instatiation of a thread is done by its subclasses. You will not
call this method by yourself (it is even not implemented).
In the current implementation, there are no options added to the
Mail::Box::Message
's object creation.
- thread
-
Returns the first message in the thread where this message is part
of. This may be this message itself. This also may return any other
message in the folder. Even a dummy message can be returned, when the
first message in the thread was not stored in the folder.
Example:
my $start = $folder->message(42)->thread;
- inThread
-
Include the message in a thread. If the message was not known to the
thread-administration yet, it will be added to those structures.
- repliedTo
-
Returns the message where this one is a reply to. In SCALAR context, this
will return the MESSAGE which was replied to by this one. This message
object may be a dummy message. In case the message seems to be the
first message of a thread, the value
undef
is returned.
In LIST context, this method also returns how sure these are messages
are related. When extended thread discovery in enabled, then some
magic is applied to relate messages. In LIST context, the first
returned argment is a MESSAGE, and the second a STRING constant.
Values for the STRING may be:
- 'REPLY'
This relation was directly derived from an `in-reply-to' message header
field. The relation is very sure.
- 'REFERENCE'
This relation is based on information found in a `Reference' message
header field. One message may reference a list of messages which
precede it in the thread. Let's hope they are stored in the right
order.
- 'GUESS'
The relation is a big guess, of undetermined type.
More constants may be added later.
Examples:
my $question = $answer->repliedTo;
my ($question, $quality) = $answer->repliedTo;
if($question && $quality eq 'REPLY') { ... };
- follows MESSAGE|MESSAGE-ID, STRING
-
Register that the specified MESSAGE (or MESSAGE-ID) is a reply on this
message, where the quality of the relation is specified by the constant
STRING.
The relation may be specified more than once, but there can be only one.
Once a reply (STRING equals REPLY
) is detected, that value will be
kept.
- followedBy [MESSAGE-ID|MESSAGE, ...]
-
Register that the MESSAGEs (or MESSAGE-IDs) are follow-ups to this message.
There may be more than one of these follow-ups which are not related to
each-other in any other way than sharing the same parent.
If the same relation is defined more than ones, this will not cause
duplication of information.
- followUps
-
Returns the list of follow-ups to this message. This list
contains parsed, not-parsed, and dummy messages.
followUps
returns MESSAGE-objects, while followUpIDs
returns the IDs
only.
- threadFilled [BOOL]
-
Returns (after setting) a flag whether the thread (where this message
is the start of) is fully processed in finding holes. If this is set
on TRUE, than any dummies still in this thread could not be found
within the limits of
thread_window
and thread_timespan
.
Some conveniance methods are added to threads, to simplify retreiving
knowledge from it.
- recurseThread CODE-REF
-
Execute a function for all sub-threads. If the subroutine returns true,
sub-threads are visited, too. Otherwise, this branch is aborted.
- totalSize
-
Sum the size of all the messages in the thread.
- nrMessages
-
Number of messages in this thread.
- ids
-
Collect all the ids in this thread.
Examples:
$newfolder->addMessages($folder->ids($thread->ids));
$folder->delete($thread->ids);
- folded [BOOL]
-
Returns whether this (part of the) folder has to be shown folded or not. This
is simply done by a label, which means that most folder-types can store this.
- threadToString
-
Translate a thread into a string. The string will contain at least one
line for each message which was found, but tries to fold dummies.
This is useful for debugging, but most message-readers
will prefer to implement their own thread printer.
Example:
print $message->threadToString;
may result in
Subject of this message
|- Re: Subject of this message
|-*- Re: Re: Subject of this message
| |- Re(2) Subject of this message
| |- [3] Re(2) Subject of this message
| `- Re: Subject of this message (reply)
`- Re: Subject of this message
The `*' represents a lacking message. The `[3]' presents a folded thread with
three messages.
Mark Overmeer (Mark@Overmeer.net).
All rights reserved. This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
This code is beta, version 1.200
Mail::Box::Thread - one discussion thread in a folder
|