Thread(3pm)

💖 Thread(3pm) — Mail::Thread, bestie edition 💖

okay so welcome to Thread(3pm) from the User Contributed Perl Documentation family, and no cap this is the one that does mail threading. pull up a chair, grab a strawberry 🍓, we're doing this.

---

✨ NAME ✨

Mail::Thread — Perl implementation of JWZ's mail threading algorithm. it's giving legendary, it's giving canonical, it's literally the 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. and bestie, listen — any deviations from the algorithm are accidental. not on purpose. we don't know her. 😭

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. that's the vibe, that's the deal, periodt.

---

👑 METHODS 👑

✨ new(@messages) ✨

Creates a new threader; requires a bunch of messages to thread. hand it the messages, she handles the rest 🫶

✨ thread ✨

Goes away and threads the messages together. iconic behaviour. no notes.

✨ rootset ✨

Returns a list of Mail::Thread::Containers which are not the parents of any other message. the top-level girlies of the tree 💜

✨ order($ordering_sub) ✨

calls order_children over each member of the root set, from one level higher. yeah. exactly that.

---

🌈 Mail::Thread::Container methods 🌈

Mail::Thread::Containers are the nodes of the thread tree. You can't just have the ordinary messages, because we might not have the message in question — like, 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. she's prepared either way.

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. the family reunion trio 🎀

✨ message ✨

Returns the message held in this container, if we have one. if we don't... she's not there. 💀

✨ 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. so even the ghost messages have an ID, slay.

✨ 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. vibe check on the subject line 🔥

✨ simple_subject ✨

the simplified version of ->subject (with reply markers removed). clean girl aesthetic, we stripped the "Re:"s ✨

✨ has_descendent($child) ✨

Returns true if this container has the given container as a child somewhere beneath it. somewhere. deep down. in the family tree 🌳

✨ add_child($child) ✨

Add the $child as a child of oneself. adopting, basically 🫶

✨ remove_child($child) ✨

Remove the $child as a child from oneself. okay so we're un-adopting, it happens, no drama.

✨ 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 — so heads up, that's on you, bestie. not me forgetting to mention it, that's literally in the source.

✨ 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. do nothing queen 💅

✨ topmost ✨

Walks the tree depth-first and returns the first message container found with a message attached. first one with actual mail on her wins.

✨ recurse_down($callback) ✨

Calls the given callback on this node and all of its children. every single one. no child left behind 💖

---

🔍 DEBUGGING 🔍

You can set $Mail::Thread::debug=1 to watch what's going on. yes bestie, turn on the spy cam, we're watching the threading happen live 🍿

---

💜 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> — the original main character, we thank her for her service 👑

---

🎀 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.

fr fr, same terms as Perl itself, that's the whole licence situation, go wild but respect her ✨

---

okay and that's the whole page 🦋 this was rendered from perl v5.34.0, dated 2022-06-15, and it's the Thread(3pm) page from the User Contributed Perl Documentation set. love that for us. bye bestie, go thread some mail 💖💅🌸