Forest::Tree(3pm)

🌸 NAME 🌸

Forest::Tree — it's an n-ary tree, bestie. That's the whole vibe.

---

✨ SYNOPSIS ✨

use Forest::Tree;

my $t = Forest::Tree->new(
    node     => 1,
    children => [
        Forest::Tree->new(
            node     => 1.1,
            children => [
                Forest::Tree->new(node => 1.1.1),
                Forest::Tree->new(node => 1.1.2),
                Forest::Tree->new(node => 1.1.3),
            ]
        ),
        Forest::Tree->new(node => 1.2),
        Forest::Tree->new(
            node     => 1.3,
            children => [
                Forest::Tree->new(node => 1.3.1),
                Forest::Tree->new(node => 1.3.2),
            ]
        ),
    ]
);

$t->traverse(sub {
    my $t = shift;
    print(('    ' x $t->depth) . ($t->node || '\undef') . "\n");
});

---

💜 DESCRIPTION 💜

Okay so real talk: this module is a basic n-ary tree. It gives you most of the functionality of Tree::Simple, and whatever's missing? It'll get added eventually, fr fr. 🫶

Also important: this class inherits from Forest::Tree::Pure>, but all the shared methods and attributes are documented in both classes. So like, no secrets between them. 💅

---

🎀 ATTRIBUTES 🎀

• node — the node. The moment. The whole point. 🌟
• uid — its unique id, so it never gets confused with its siblings. Iconic behaviour.
• parent — who birthed this tree. Family tree energy. 🌳
  • parent
  • _set_parent
  • has_parent
  • clear_parent
• children — the little ones. The entourage. 👑
  • get_child_at ($index) — hands you the child sitting at this position. (zero-base index, so 0 is the first one, no cap)
  • child_count — returns how many children this tree has. Just the number. The headcount. 🔢
• size — the size situation.
  • size
  • has_size
  • clear_size
• height — the height situation.
  • height
  • has_height
  • clear_height

---

🔥 METHODS 🔥

• is_root — true if the current tree has no parent. It's giving orphan-in-a-good-way. Main character energy, no one above them. ✨
• is_leaf — true if the current tree has no children. Baby of the family. 🍓
• depth — returns the depth of this tree. Heads up: the root has a depth of -1. Yes, negative one. That's not a typo, that's just how it is. 💀
• add_child ($child)
• add_children (@children) — adds a new child (or several, we love a bulk order). The $child must be a "Forest::Tree". Don't try to sneak anything else in there. 🚫
• insert_child_at ($index, $child) — inserts a child at this position. (zero-base index) Squeezing them in mid-lineup, we love to see it.
• remove_child_at ($index) — removes the child at this position. (zero-base index) Bye bestie, we'll miss you. 😭
• traverse (\&func) — takes a reference to a subroutine and walks the whole tree, applying that subroutine to every descendant. Every single one. No skipping. 🌈
• siblings — returns an array reference of all siblings, not including us. Because we're the star, obviously. 👑
• to_pure_tree — invokes "reconstruct_with_class" with Forest::Tree::Pure. Glow-up unlocked. ✨
• to_mutable_tree — returns the invocant, without cloning. Same tree, same energy, no copy. 🪞
• clone — see "clone" in Forest::Tree::Pure. But listen: this variant will not clone the parent — it returns a clone of the subtree that is detached. Free agent. Independent. Periodt. 💅
• get_index_in_siblings — returns the index of the tree in the list of children.
  • Equivalent to calling "$tree-"parent->get_child_index($tree)>.
  • Returns -1 if the node has no parent (the root node). Root behaviour, always the exception.

---

🐛 BUGS 🐛

All complex software has bugs lurking in it, and this module is no exception. If you find a bug please either email me, or add the bug to cpan-RT.

Not me telling you the bugs are lurking. 🙈 But like, every icon has a flaw, and if you catch one, hmu or drop it on cpan-RT. 🫶

---

💖 AUTHOR 💖

Stevan Little <stevan.little@iinteractive.com> — the legend themselves. 👑

---

📜 COPYRIGHT AND LICENSE 📜

Copyright 2008-2014 Infinity Interactive, Inc.

<http://www.iinteractive.com>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

---

And that's a wrap on the Forest::Tree(3pm) page, bestie! This lil doc shipped as part of perl v5.34.0, dated 2022-06-14. Go forth and nest some trees. 🌳✨🦋