NAME

Mail::Box::Threads - maintain threads within a folder

SYNOPSIS

   my Mail::Box $folder = ...;
   foreach my $thread ($folder->threads)
   {   $thread->print;
   }

DESCRIPTION

Read Mail::Box::Manager and Mail::Box first. The manual also describes package Mail::Box::Thread, which is one thread.

This module maintains an easily accessable structure containing information about threads. Each thread is maintained while a folder is open. The structure consists of message, and a list of replies. A reply can be a single message or a thread by itself.

PUBLIC INTERFACE

new ARGS

The construction of a Mail::Box::Threads accepts the following options:

• dummy_type => CLASS

  Of which class are dummy messages? Usually, this needs to be the message_type of the folder prepended with ::Dummy. This will also be the default.

messageWithId MESSAGE-ID [MESSAGE]

Returns (and first sets) the message which has a certain id.

allMessageIDs

Returns a list of all messages/message-ids in the folder, including those which are to be deleted.

Example: my @ids = grep {not $_->deleted} $folder->allMessageIDs;

addToThread MESSAGE

Add a message to a discussion-thread. It does not matter whether you have done this before (although this information should not conflict with the thread-information found till now).

follows MESSAGE, MESSAGE

Register a follow-up from message to the other.

Example: $folder->follows($question, $answer);

registerThread MESSAGE|MESSAGE-ID

unregisterThread MESSAGE|MESSAGE-ID

Register/Unregister a message or message-id to be (not to be) the start of a thread. This does not mean that the message is the top of a thread for sure, because not all mail-packages are careful in handling references. Call lintThreads to reduce the discrepancies in threads further.

lintThreads

Improve the quality of thread discovery. Running lint-ing might be time-consuming, so is only run on explicit request. You do not have to re-run lint once you have read the file: all further modifications to the folder will maintain correct threads.

Example: my $folder = Mail::Box::File->new->lintThreads;

isThreadStart MESSAGE|MESSAGE-ID

Check whether the message is registered as being a start for threads.

Example: if($folder->isThreadStart($folder->message(3)) {...};

threads

Returns a list of all threads discovered so far.

Example: print $_->nrMessages foreach $folder->threads;

Mail::Box::Thread

A thread implements a linked list of messages which are a logical sequence. There are two sides to threads: primarly the relations between messages, and secondary the way they are presented on the screen.

addFollowUp MESSAGE | MESSAGE-ID

addFollowUps [MESSAGE | MESSAGE-ID]*

Add one/multiple messages or message-ids to the list of messages which are send as follow-up on this message. This information is used to recognize descussion threads. Duplicates are ignored.

Example: $message1->addFollowUp($message2); $message1->addFollowUp($message2->messageID);

followUps

Return the whole list of follow-ups.

Examples: my @replies = $message->followUps; print scalar $message->followUps, " replies.\n";

subThreads

Return the subThreads of this thread.

recurseThread CODE-REF

Execute a function for all sub-threads.

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);

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 alpha, version 0.3