NAME
TPath::Forester - a generator of TPath expressions for a particular class of nodes
VERSION
version 0.003
SYNOPSIS
# we apply the TPath::Forester role to a class
{
package MyForester;
use Moose; # for simplicity we omit removing Moose droppings, etc.
use MooseX::MethodAttributes; # needed if you're going to add some attributes
with 'TPath::Forester'; # compose in the TPath::Forester methods and attributes
# define abstract methods
sub children { $_[1]->children } # our nodes know their children
sub parent { $_[1]->parent } # our nodes know their parent
sub has_tag { # our nodes have a tag attribute which is
my ($self, $node, $tag) = @_; # their only tag
$node->tag eq $tag;
}
sub matches_tag {
my ($self, $node, $re) = @_;
$node->tag =~ $re;
}
# define an attribute
sub baz :Attr {
# the canonical order of arguments, none of which we need
# my ($self, $node, $collection, $index, @args) = @_;
'baz';
}
}
# now select some nodes from a tree
my $f = MyForester->new; # make a forester
my $path = $f->path('//foo/>bar[@depth = 4]'); # compile a path
my $root = fetch_tree(); # get a tree of interest
my @nodes = $path->select($root); # find the nodes of interest
# say our nodes have a text method that returns a string
$f->add_test( sub { shift->text =~ /^\s+$/ } ); # ignore whitespace nodes
$f->add_test( sub { shift->text =~ /^-?\d+$/ } ); # ignore integers
$f->add_test( sub { ! length shift->text } ); # ignore empty nodes
# reset to ignoring nothing
$f->clear_tests;DESCRIPTION
A TPath::Forester understands your trees and hence can translate TPath expressions into objects that will select the appropriate nodes from your trees. It can also generate an index appropriate to your trees if you're doing multiple selects on a particular tree.
TPath::Forester is a role. It provides most, but not all, methods and attributes required to construct TPath::Expression objects. You must specify how to find a node's children and its parent (you may have to rely on a TPath::Index for this), and you must define how a tag string or regex may match a node, if at all.
ATTRIBUTES
log_stream
A TPath::LogStream required by the @log attribute. By default it is TPath::StderrLog. This attribute is required by the @log attribute from TPath::Attributes::Standard.
METHODS
add_test, has_tests, clear_tests
Add a code ref that will be used to test whether a node is ignorable. The return value of this code will be treated as a boolean value. If it is true, the node, and all its children, will be passed over as possible items to return from a select.
Example test:
$f->add_test(sub {
my ($forester, $node, $index) = @_;
return $forester->has_tag('foo');
});Every test will receive the forester itself, the node, and the index as arguments. This example test will cause the forester $f to ignore foo nodes.
This method has the companion methods has_tests and clear_tests. The former says whether the list is empty and the latter clears it.
add_attribute
Expects a name, a code reference, and possibly options. Adds the attribute to the forester.
If the attribute name is already in use, the method will croak unless you specify that this attribute should override the already named attribute. E.g.,
$f->add_attribute( 'foo', sub { ... }, -override => 1 );If you specify the attribute as overriding and the name is *not* already in use, the method will carp. You can use the -force option to skip all this checking and just add the attribute.
Note that the code reference will receive the forester, a node, a collection of nodes, an index, and optionally any additional arguments. If you want the attribute to evaluate as undefined for a particular node, it must return undef for this node.
attribute
Expects a node, an attribute name, a collection, an index, and a parameter list. Returns the value of the attribute in that context. If undef is provided for the collection and index, default values are created -- a single element collection containing the node and a new index.
path
Takes a TPath expression and returns a TPath::Expression.
index
Takes a tree node and returns a TPath::Index object that TPath::Expression objects can use to cache information about the tree rooted at the given node.
parent
Expects a node and an index and returns the parent of the given node according to the index. If your nodes know their own parents, you probably want to override this method. See also TPath::Index.
id
Expects a node. Returns id of node, if any. By default this method always returns undef. Override if your node has some defined notion of id.
is_leaf
Expects a node, a collection, and an index.
Returns whether the context node is a leaf. Override this with something more efficient where available. E.g., where the node provides an is_leaf method,
sub is_leaf { $_[1]->is_leaf }is_root
Expects a node, a collection, and an index.
Returns whether the context node is the root. Delegates to index.
Override this with something more efficient where available. E.g., where the node provides an is_root method,
sub is_root { $_[1]->is_root }ROLES
TPath::Attributes::Standard, TPath::TypeCheck
REQUIRED METHODS
children
Expects a node and an index. Returns the children of the node as a list.
has_tag
Expects a node and a string. Returns whether the node, in whatever sense is appropriate to this sort of node, "has" the string as a tag.
matches_tag
Expects a node and a compiled regex. Returns whether the node, in whatever sense is appropriate to this sort of node, has a tag that matches the regex.
AUTHOR
David F. Houghton <dfhoughton@gmail.com>
COPYRIGHT AND LICENSE
This software is copyright (c) 2013 by David F. Houghton.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.