NAME¶
Mail::Thread - Perl implementation of JWZ's mail threading algorithm
SYNOPSIS¶
use Mail::Thread;
my $threader = new Mail::Thread (@messages);
$threader->thread;
dump_em($_,0) for $threader->rootset;
sub dump_em {
my ($self, $level) = @_;
print ' \\-> ' x $level;
if ($self->message) {
print $self->message->head->get("Subject") , "\n";
} else {
print "[ Message $self not available ]\n";
}
dump_em($self->child, $level+1) if $self->child;
dump_em($self->next, $level) if $self->next;
}
DESCRIPTION¶
This module implements something relatively close to Jamie Zawinski's mail
threading algorithm, as described by
http://www.jwz.org/doc/threading.html.
Any deviations from the algorithm are accidental.
It's happy to be handed any mail object supported by
"Email::Abstract". If you need to do anything else, you'll have to
subclass and override "_get_hdr".
METHODS¶
new(@messages)¶
Creates a new threader; requires a bunch of messages to thread.
thread¶
Goes away and threads the messages together.
rootset¶
Returns a list of "Mail::Thread::Container"s which are not the parents
of any other message.
order($ordering_sub)¶
calls "order_children" over each member of the root set, from one
level higher
"Mail::Thread::Container" methods¶
"Mail::Thread::Container"s are the nodes of the thread tree. You can't
just have the ordinary messages, because we might not have the message in
question. For instance, a mailbox could contain two replies to a question that
we haven't received yet. So all "logical" messages are stuffed in
containers, whether we happen to have that container or not.
To do anything useful with the thread tree, you're going to have to recurse
around the list of "Mail::Thread::Containers". You do this with the
following methods:
parent¶
child¶
next¶
Returns the container which is the parent, child or immediate sibling of this
one, if one exists.
message¶
Returns the message held in this container, if we have one.
messageid¶
Returns the message ID for this container. This will be around whether we have
the message or not, since some other message will have referred to it by
message ID.
returns the named header of the contained message
subject¶
returns the subject line of the contained message
isreply¶
examines the results of ->subject and returns true if it looks like a reply
simple_subject¶
the simplified version of ->subject (with reply markers removed)
has_descendent($child)¶
Returns true if this container has the given container as a child somewhere
beneath it.
add_child($child)¶
Add the $child as a child of oneself.
remove_child($child)¶
Remove the $child as a child from oneself.
children¶
Returns a list of the
immediate children of this container.
set_children(@children)¶
set the children of a node. does not update the ->parents of the @children
order_children($ordering_sub)¶
Recursively reorders children according to the results of $ordering_sub
$ordering_sub is called with the containers children, and is expected to return
them in their new order.
# order by subject line
$container->order_children( sub {
sort { $a->topmost->message->subject cmp $b->topmost->message->subject } @_
} );
$ordering_sub may be omitted, in which case no ordering takes place
topmost¶
Walks the tree depth-first and returns the first message container found with a
message attached
recurse_down($callback)¶
Calls the given callback on this node and
all of its children.
DEBUGGING¶
You can set $Mail::Thread::debug=1 to watch what's going on.
MAINTAINER¶
Tony Bowden
BUGS and QUERIES¶
Please direct all correspondence regarding this module to:
bug-Mail-Thread@rt.cpan.org
ORIGINAL AUTHOR¶
Simon Cozens, <simon@cpan.org>
COPYRIGHT AND LICENSE¶
Copyright 2003 by Kasei Copyright 2004 by Simon Cozens
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.