Tree::Simple::Visitor::FindByPath - A Visitor for finding an element in a Tree::Simple hierarchy with a path

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

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

  # set the search path for our tree  
  $visitor->setSearchPath(qw(1 1.2 1.2.2));

  # pass the visitor to a tree
  $tree->accept($visitor);

  # fetch the result, which will 
  # be the Tree::Simple object that 
  # we have found, or undefined
  my $result = $visitor->getResult() || die "No Tree found";

  # our result's node value should match 
  # the last element in our path
  print $result->getNodeValue(); # this should print 1.2.2

package Tree::Simple::Visitor::FindByPath;

use strict;
use warnings;

our $VERSION = '0.03';

use Scalar::Util qw(blessed);

use base qw(Tree::Simple::Visitor);

sub new {
    my ($_class) = @_;
    my $class = ref($_class) || $_class;
    my $visitor = {};
    bless($visitor, $class);
    $visitor->_init();
    return $visitor;
}

sub _init {
    my ($self) = @_;
    $self->{search_path} = undef;
    $self->{success} = 0;
    $self->SUPER::_init();
}

sub setSearchPath {
    my ($self, @path) = @_;
    (@path) || die "Insufficient Arguments : You must specify a path";
    $self->{search_path} = \@path;
}

sub visit {
	my ($self, $tree) = @_;
	(blessed($tree) && $tree->isa("Tree::Simple"))
		|| die "Insufficient Arguments : You must supply a valid Tree::Simple object";

    # reset our success flag
    $self->{success} = 0;
        
    # get our filter function
	my $func;
    if ($self->{_filter_function}) {
        $func = sub { 
            my ($tree, $test) = @_;
            return (($self->{_filter_function}->($tree) . "") eq $test);
            };    
    }
    else {
        $func = sub { 
            my ($tree, $test) = @_;
            return (($tree->getNodeValue() . "") eq $test);
            };  
    }

    # get ready with our results
    my @results;
    
    # get our path
    my @path = @{$self->{search_path}};    

    # get our variables ready
    my $current_path;
    my $current_tree = $tree;
    
    # check to see if we have been 
    # asked to include the trunk
    if ($self->includeTrunk()) {
        # if we dont match the root of the path
        # then we have failed already and so return
        $self->setResults(()) && return 
            unless $func->($current_tree, $path[0]);
        # if we do match, then remove it off the path
        shift @path;
    }
    
    TOP: {
        # if we have no more @path we have found it
        unless (@path) {
            # store the current tree as
            # our last result
            $self->setResults(@results, $current_tree);
            # and set the sucess flag
            $self->{success} = 1;
            return;
        }
        # otherwise we need to keep looking ...
        # get the next element in the path
        $current_path = shift @path;
        # now check all the current tree's children
        # for a match
        foreach my $child ($current_tree->getAllChildren()) {
            if ($func->($child, $current_path)) {
                # if we find a match, then
                # we store the current tree 
                # in our results, and 
                push @results => $current_tree;
                # we change our current tree
                $current_tree = $child;
                # and go back to the TOP                
                goto TOP;
            }
        }
   
        # if we do not find a match, then we can fall off 
        # this block and the whole subroutine for that matter
        # since we know the match has failed.
        push @results => $current_tree 
            if (@path || $self->{success} == 0) && $current_tree != $tree;
    }
    # we do however, store the 
    # results as far as we got,
    # so that the user can maybe 
    # do something else to recover
    $self->setResults(@results);
}

sub getResult {
    my ($self) = @_;
    # if we did not succeed, then 
    # we return undef, ...
    return undef unless $self->{success};
    # otherwise we return the 
    # last in the results
    return $self->getResults()->[-1];
}

1;

__END__