/ 
Mail-Box-1.112
River stage one • 8 direct dependents • 8 total dependents
/ Mail::Box::Thread

NAME

Mail::Box::Thread - one discussion thread in a folder

SYNOPSIS

my $thread = $message->thread;
$thread->printThread;

DESCRIPTION

Read Mail::Box::Manager and Mail::Box::Threads 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.

Mail::Box::Thread

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.

Actions on whole threads

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.

AUTHOR

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.

VERSION

This code is beta, version 1.112