METHODS

See METHODS in Mail::Reporter

Constructors

$class->new( OPTIONS )

A Mail::Box::Thread::Manager object is usually created by a Mail::Box::Manager. One manager can produce more than one of these objects. One thread manager can combine messages from a set of folders, which may be partially overlapping with other objects of the same type.

Option Defined in Default

dummy_type

Mail::Message::Dummy

folder

[ ]

folders

[ ]

log

Mail::Reporter

'WARNINGS'

thread_body

<false>

thread_type

Mail::Box::Thread::Node

timespan

'3 days'

trace

Mail::Reporter

'WARNINGS'

window

10

dummy_type => CLASS
The type of dummy messages. Dummy messages are used to fill holes in detected threads: referred to by messages found in the folder, but itself not in the folder.
folder => FOLDER | REF-ARRAY-FOLDERS
Specifies which folders are to be covered by the threads. You can specify one or more open folders. When you close a folder, the manager will automatically remove the messages of that folder from your threads.
folders => FOLDER | REF-ARRAY-FOLDERS
Equivalent to the folder option.
log => LEVEL
thread_body => BOOLEAN
May thread-detection be based on the content of a message? This has a serious performance implication when there are many messages without In-Reply-To and References headers in the folder, because it will cause many messages to be parsed. NOT IMPLEMENTED YET.
thread_type => CLASS
Type of the thread nodes.
timespan => TIME | 'EVER'
Specify how fast threads usually work: the amount of time between an answer and a reply. This is used in combination with the window option to determine when to give-up filling the holes in threads.
See Mail::Box::timespan2seconds() for the possibilities for TIME. With 'EVER', the search for messages in a thread will only be limited by the window-size.
trace => LEVEL
window => INTEGER|'ALL'
The thread-window describes how many messages should be checked at maximum to fill `holes' in threads for folder which use delay-loading of message headers.
The constant 'ALL' will cause thread-detection not to stop trying to fill holes, but continue looking until the first message of the folder is reached. Gives the best quality results, but may perform bad.
» Example:
 use Mail::Box::Manager;
 my $mgr     = new Mail::Box::Manager;
 my $inbox   = $mgr->open(folder => $ENV{MAIL});
 my $read    = $mgr->open(folder => 'Mail/read');
 my $threads = $mgr->threads(folders => [$inbox, $read]);

 # longer alternative for last line:
 my $threads = $mgr->threads;
 $threads->includeFolder($inbox);
 $threads->includeFolder($read);

Grouping Folders

$obj->folders

Returns the folders as managed by this threader.

$obj->includeFolder( FOLDERS )

Add one or more folders to the list of folders whose messages are organized in the threads maintained by this object. Duplicated inclusions will not cause any problems.

From the folders, the messages which have their header lines parsed (see Mail::Box about lazy extracting) will be immediately scanned. Messages of which the header is known only later will have to report this (see toBeThreaded()).

» Example:
 $threads->includeFolder($inbox, $draft);
$obj->removeFolder( FOLDERS )

Remove one or more folders from the list of folders whose messages are organized in the threads maintained by this object.

» Example:
 $threads->removeFolder($draft);

The Threads

$obj->all

Returns all messages which start a thread. The list may contain dummy messages and messages which are scheduled for deletion.

To be able to return all threads, thread construction on each message is performed first, which may be slow for some folder-types because is will enforce parsing of message-bodies.

$obj->known

Returns the list of all messages which are known to be the start of a thread. Threads containing messages which where not read from their folder (like often happens MH-folder messages) are not yet known, and hence will not be returned.

The list may contain dummy messages, and messages which are scheduled for deletion. Threads are detected based on explicitly calling inThread() and thread() with a messages from the folder.

Be warned that, each time a message's header is read from the folder, the return of the method can change.

$obj->sortedAll( [PREPARE [COMPARE]] )

Returns all() the threads by default, but sorted on timestamp.

$obj->sortedKnown( [PREPARE [,COMPARE]] )

Returns all known() threads, in sorted order. By default, the threads will be sorted on timestamp, But a different COMPARE method can be specified.

$obj->thread( MESSAGE )

Returns the thread where this MESSAGE is the start of. However, there is a possibility that this message is a reply itself.

Usually, all messages which are in reply of this message are dated later than the specified one. All headers of messages later than this one are getting parsed first, for each folder in this threads-object.

» Example:
 my $threads = $mgr->threads(folder => $inbox);
 my $thread  = $threads->thread($inbox->message(3));
 print $thread->string;
$obj->threadStart( MESSAGE )

Based on a message, and facts from previously detected threads, try to build solid knowledge about the thread where this message is in.

Internals

$obj->createDummy( MESSAGE-ID )

Get a replacement message to be used in threads. Be warned that a dummy is not a member of any folder, so the program working with threads must test with Mail::Message::isDummy() before trying things only available to real messages.

$obj->inThread( MESSAGE )

Collect the thread-information of one message. The `In-Reply-To' and `Reference' header-fields are processed. If this method is called on a message whose header was not read yet (as usual for MH-folders, for instance) the reading of that header will be triggered here.

$obj->outThread( MESSAGE )

Remove the message from the thread-infrastructure. A message is replaced by a dummy.

$obj->toBeThreaded( FOLDER, MESSAGES )

Include the specified messages in/from the threads managed by this object, if this folder is maintained by this thread-manager.

$obj->toBeUnthreaded( FOLDER, MESSAGES )

Remove the specified messages in/from the threads managed by this object, if this folder is maintained by this thread-manager.

Error handling

$obj->AUTOLOAD
See AUTOLOAD in Mail::Reporter.
$obj->addReport( OBJECT )
See addReport in Mail::Reporter.
$obj->defaultTrace( [LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK] )
$class->defaultTrace( [LEVEL]|[LOGLEVEL, TRACELEVEL]|[LEVEL, CALLBACK] )
See defaultTrace in Mail::Reporter.
$obj->errors
See errors in Mail::Reporter.
$obj->log( [LEVEL [,STRINGS]] )
$class->log( [LEVEL [,STRINGS]] )
See log in Mail::Reporter.
$obj->logPriority( LEVEL )
$class->logPriority( LEVEL )
See logPriority in Mail::Reporter.
$obj->logSettings
See logSettings in Mail::Reporter.
$obj->notImplemented
See notImplemented in Mail::Reporter.
$obj->report( [LEVEL] )
See report in Mail::Reporter.
$obj->reportAll( [LEVEL] )
See reportAll in Mail::Reporter.
$obj->trace( [LEVEL] )
See trace in Mail::Reporter.
$obj->warnings
See warnings in Mail::Reporter.

Cleanup

$obj->DESTROY
See DESTROY in Mail::Reporter.
$obj->inGlobalDestruction
See inGlobalDestruction in Mail::Reporter.