Thread(3pm)						User Contributed Perl Documentation					       Thread(3pm)

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") , "
";
	       } else {
		   print "[ Message $self not available ]
";
	       }
	       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.

   header( $name )
       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.

perl v5.10.0							    2006-10-30							       Thread(3pm)