.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Thread 3pm"
.TH Thread 3pm "2021-01-06" "perl v5.32.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Mail::Thread \- Perl implementation of JWZ's mail threading algorithm
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    use Mail::Thread;
\&    my $threader = new Mail::Thread (@messages);
\&
\&    $threader\->thread;
\&
\&    dump_em($_,0) for $threader\->rootset;
\&
\&    sub dump_em {
\&        my ($self, $level) = @_;
\&        print \*(Aq \e\e\-> \*(Aq x $level;
\&        if ($self\->message) {
\&            print $self\->message\->head\->get("Subject") , "\en";
\&        } else {
\&            print "[ Message $self not available ]\en";
\&        }
\&        dump_em($self\->child, $level+1) if $self\->child;
\&        dump_em($self\->next, $level) if $self\->next;
\&    }
.Ve
.SH "DESCRIPTION"
.IX Header "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.
.PP
It's happy to be handed any mail object supported by \f(CW\*(C`Email::Abstract\*(C'\fR.
If you need to do anything else, you'll have to subclass and override
\&\f(CW\*(C`_get_hdr\*(C'\fR.
.SH "METHODS"
.IX Header "METHODS"
.SS "new(@messages)"
.IX Subsection "new(@messages)"
Creates a new threader; requires a bunch of messages to thread.
.SS "thread"
.IX Subsection "thread"
Goes away and threads the messages together.
.SS "rootset"
.IX Subsection "rootset"
Returns a list of \f(CW\*(C`Mail::Thread::Container\*(C'\fRs which are not the parents
of any other message.
.SS "order($ordering_sub)"
.IX Subsection "order($ordering_sub)"
calls \f(CW\*(C`order_children\*(C'\fR over each member of the root set, from one level higher
.ie n .SH """Mail::Thread::Container"" methods"
.el .SH "\f(CWMail::Thread::Container\fP methods"
.IX Header "Mail::Thread::Container methods"
\&\f(CW\*(C`Mail::Thread::Container\*(C'\fRs 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 \*(L"logical\*(R" messages are stuffed in containers,
whether we happen to have that container or not.
.PP
To do anything useful with the thread tree, you're going to have to recurse
around the list of \f(CW\*(C`Mail::Thread::Containers\*(C'\fR. You do this with the following
methods:
.SS "parent"
.IX Subsection "parent"
.SS "child"
.IX Subsection "child"
.SS "next"
.IX Subsection "next"
Returns the container which is the parent, child or immediate sibling
of this one, if one exists.
.SS "message"
.IX Subsection "message"
Returns the message held in this container, if we have one.
.SS "messageid"
.IX Subsection "messageid"
Returns the message \s-1ID\s0 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 \s-1ID.\s0
.ie n .SS "header( $name )"
.el .SS "header( \f(CW$name\fP )"
.IX Subsection "header( $name )"
returns the named header of the contained message
.SS "subject"
.IX Subsection "subject"
returns the subject line of the contained message
.SS "isreply"
.IX Subsection "isreply"
examines the results of \->subject and returns true if it looks like a reply
.SS "simple_subject"
.IX Subsection "simple_subject"
the simplified version of \->subject (with reply markers removed)
.SS "has_descendent($child)"
.IX Subsection "has_descendent($child)"
Returns true if this container has the given container as a child somewhere
beneath it.
.SS "add_child($child)"
.IX Subsection "add_child($child)"
Add the \f(CW$child\fR as a child of oneself.
.SS "remove_child($child)"
.IX Subsection "remove_child($child)"
Remove the \f(CW$child\fR as a child from oneself.
.SS "children"
.IX Subsection "children"
Returns a list of the \fBimmediate\fR children of this container.
.SS "set_children(@children)"
.IX Subsection "set_children(@children)"
set the children of a node.  does not update the \->parents of the \f(CW@children\fR
.SS "order_children($ordering_sub)"
.IX Subsection "order_children($ordering_sub)"
Recursively reorders children according to the results of \f(CW$ordering_sub\fR
.PP
\&\f(CW$ordering_sub\fR is called with the containers children, and is expected to
return them in their new order.
.PP
.Vb 4
\& # order by subject line
\& $container\->order_children( sub {
\&    sort { $a\->topmost\->message\->subject cmp $b\->topmost\->message\->subject } @_
\&  } );
.Ve
.PP
\&\f(CW$ordering_sub\fR may be omitted, in which case no ordering takes place
.SS "topmost"
.IX Subsection "topmost"
Walks the tree depth-first and returns the first message container found with a message attached
.SS "recurse_down($callback)"
.IX Subsection "recurse_down($callback)"
Calls the given callback on this node and \fBall\fR of its children.
.SH "DEBUGGING"
.IX Header "DEBUGGING"
You can set \f(CW$Mail::Thread::debug\fR=1 to watch what's going on.
.SH "MAINTAINER"
.IX Header "MAINTAINER"
Tony Bowden
.SH "BUGS and QUERIES"
.IX Header "BUGS and QUERIES"
Please direct all correspondence regarding this module to:
  bug\-Mail\-Thread@rt.cpan.org
.SH "ORIGINAL AUTHOR"
.IX Header "ORIGINAL AUTHOR"
Simon Cozens, <simon@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
Copyright 2003 by Kasei
Copyright 2004 by Simon Cozens
.PP
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.