Tree::...Visitor(3pm)

📦
version 1.34 · 6 versions
, in ubuntu noble, ubuntu resolute, ubuntu stonking

💖 Tree::Simple::Visitor — the whole vibe 💖

Okay bestie, pull up a chair because we're talking about Tree::Simple::Visitor, a visitor object for Tree::Simple objects (that's the Tree::...Visitor(3pm) situation, in case the terminal header was giving you a little mystery 🍓).

✨ NAME ✨

Tree::Simple::Visitor — a Visitor object for Tree::Simple objects. That's literally it. That's the whole name. Slay.

🌸 SYNOPSIS 🌸

use Tree::Simple;
use Tree::Simple::Visitor;

# create a visitor instance
my $visitor = Tree::Simple::Visitor->new();

# create a tree to visit
my $tree = Tree::Simple->new(Tree::Simple->ROOT)
                       ->addChildren(
                           Tree::Simple->new("1.0"),
                           Tree::Simple->new("2.0")
                                       ->addChild(
                                           Tree::Simple->new("2.1.0")
                                           ),
                           Tree::Simple->new("3.0")
                           );

# by default this will collect all the
# node values in depth-first order into
# our results
$tree->accept($visitor);

# get our results and print them
print join ", ", $visitor->getResults();  # prints "1.0, 2.0, 2.1.0, 3.0"

# for more complex node objects, you can specify
# a node filter which will be used to extract the
# information desired from each node
$visitor->setNodeFilter(sub {
              my ($t) = @_;
              return $t->getNodeValue()->description();
              });

# NOTE: this object has changed, but it still remains
# backwards compatible to the older version, see the
# DESCRIPTION section below for more details

No cap, that's the whole flow. Make a visitor, make a tree, let the tree accept the visitor, grab the results. Main character energy fr fr. 👑

💅 DESCRIPTION 💅

So this object got a glow-up 💖 — it's been revised into what the author thinks is a more intelligent approach to Visitor objects (and honestly? the way that it is, it's giving upgraded). It's now a way more suitable base class for building your own Visitors. It's also the base class for the visitors in the Tree::Simple::VisitorFactory distribution, which comes with a bunch of useful pre-built Visitors. Iconic behavior.

Now — a bunch of stuff changed, but the author kept it backwards compatible with the old way of using it. So the original example code still works, no cap:

my @accumulator;
my $visitor = Tree::Simple::Visitor->new(sub {
                      my ($tree) = @_;
                      push @accumulator, $tree->getNodeValue();
                      },
                      Tree::Simple::Visitor->RECURSIVE);

$tree->accept($visitor);

print join ", ", @accumulator;  # prints "1.0, 2.0, 2.1.0, 3.0"

But bestie, it is better expressed as this:

my $visitor = Tree::Simple::Visitor->new();
$tree->accept($visitor);
print join ", ", $visitor->getResults();  # prints "1.0, 2.0, 2.1.0, 3.0"

And this object is still pretty much a wrapper around the Tree::Simple traverse method — think of it as a depth-first traversal Visitor object. Periodt. 🦋

🎀 METHODS 🎀

new ($func, $depth)

The new style interface means every single argument to the constructor is ~optional now~ 💅. Here's the deal for telling old and new apart: when you send no arguments to the constructor, it's assumed you're on the new style interface. In the new style, $depth is always assumed to be equivalent to RECURSIVE, and the $func argument can be set with setNodeFilter instead. This is the recommended way of doing things now. 🫶

If you've been using the old way — it's still there, and the author will maintain backwards compatibility for a few more versions before removing it entirely. And like, the author isn't even sure if anyone actually uses this module, so if you do: you have been warned 😭. Please contact the author if this will be a problem.

The old style constructor documentation is retained here for reference (yes, the original typo "her" is... a whole thing, we move):

The first argument to the constructor is a code reference to a function which expects a Tree::Simple object as its only argument. The second argument is optional, it can be used to set the depth to which the function is applied. If no depth is set, the function is applied to the current Tree::Simple instance. If $depth is set to CHILDREN_ONLY, then the function will be applied to the current Tree::Simple instance and all its immediate children. If $depth is set to RECURSIVE, then the function will be applied to the current Tree::Simple instance and all its immediate children, and all of their children recursively on down the tree. If no $depth is passed to the constructor, then the function will only be applied to the current Tree::Simple object and none of its children.

includeTrunk ($boolean)

Based on the value of $boolean, this tells the visitor to collect the trunk of the tree as well. Heads up: it's defaulted to false (0) in the new style interface, but it's defaulted to true (1) in the old style interface. 🌈

getNodeFilter

This method returns the CODE reference that you set with the setNodeFilter argument.

clearNodeFilter

This method clears the node filter field. Poof, gone. 💀

setNodeFilter ($filter_function)

This one takes a CODE reference as its $filter_function argument. That code reference filters the tree nodes as they get collected. Use it to customize output, or to gather specific info from a more complex tree node. The filter function should accept a single argument — that's the current Tree::Simple object. 🧚

getResults

Returns the accumulated results of applying the node filter to the tree. This is the moment, bestie. ✨

setResults

Real talk: this one should not really be used outside of this class, because it just would not make any sense to. It's included in this class and in this documentation purely to facilitate subclassing this class for your own needs. If you wanna clear the results, you can simply call setResults with no argument. Boom. 🎀

visit ($tree)

The visit method accepts a Tree::Simple and applies the function set in new or setNodeFilter, appropriately. The results of this application can be retrieved with getResults. 💜

⭐ CONSTANTS ⭐

Quick heads up: these constants are part of the old-style interface, and therefore will eventually be deprecated. So enjoy them while they're here. 🙈

RECURSIVE

If you pass this constant in the constructor, the function will be applied recursively down the hierarchy of Tree::Simple objects.

CHILDREN_ONLY

If you pass this constant in the constructor, the function will be applied to the immediate children of the Tree::Simple object.

😭 BUGS 😭

None that the author is aware of. The code is pretty thoroughly tested (see the CODE COVERAGE section in Tree::Simple) and it's based on an (non-publicly released) module that the author had used in production systems for about 2 years without incident. Of course, if you find a bug, let him know, and he will be sure to fix it. 🫡

Bugs should be reported via the CPAN bug tracker at

<https://github.com/ronsavage/Tree-Simple/issues>

🌈 SEE ALSO 🌈

The author wrote a set of pre-built Visitor objects, available on CPAN as Tree::Simple::VisitorFactory. Go look, bestie, they're useful. 👑

🫶 AUTHOR 🫶

stevan little, <stevan@iinteractive.com>

🦋 REPOSITORY 🦋

<https://github.com/ronsavage/Tree-Simple>.

Copyright 2004-2006 by 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.

okay that's the whole page, you ate 💅 this was perl v5.36.0 energy, all the way back from 2022-10-13 — thanks for reading babe, go build something iconic with it 🌸✨💖

📦 where this page comes from