/ 
Class-XPath-1.4
River stage one • 1 direct dependent • 1 total dependent
/ Class::XPath

NAME

Class::XPath - adds xpath matching to object trees

SYNOPSIS

In your node class, use Class::XPath:

# generate xpath() and match() using Class::XPath
use Class::XPath

   get_name => 'name',        # get the node name with the 'name' method

   get_parent => 'parent',    # get parent with the 'parent' method

   get_root   => \&get_root,  # call get_root($node) to get the root

   get_children => 'kids',    # get children with the 'kids' method

   get_attr_names => 'param', # get names and values of attributes
   get_attr_value => 'param', # from param
   
   get_content    => 'data',  # get content from the 'data' method
   
   ;

Now your objects support XPath-esque matching:

# find all pages, anywhere in the tree
@nodes = $node->match('//page');

# returns an XPath like "/page[1]/paragraph[2]"
$xpath = $node->xpath();

DESCRIPTION

This module adds XPath-style matching to your object trees. This means that you can find nodes using an XPath-esque query with match() from anywhere in the tree. Also, the xpath() method returns a unique path to a given node which can be used as an identifier.

To use this module you must already have an OO implementation of a tree. The tree must be a true tree - all nodes have a single parent and the tree must have a single root node. Also, the order of children within a node must be stable.

NOTE: This module is not yet a complete XPath implementation. Over time I expect the subset of XPath supported to grow. See the SYNTAX documentation for details on the current level of support.

USAGE

This module is used by providing it with information about how your class works. Class::XPath uses this information to build the match() and xpath() methods for your class. The parameters passed to 'use Class::XPath' may be set with strings, indicating method names, or subroutine references. They are:

get_name (required)

Returns the name of this node. This will be used as the element name when evaluating an XPath match. The value returned must matches /^[\w:]+$/.

get_parent (required)

Returns the parent of this node. The root node must return undef from the get_parent method.

get_children (required)

Returns a list of child nodes, in order.

get_attr_names (required)

Returns a list of available attribute names. The values returned must match /^[\w:]+$/).

get_attr_value (required)

Called with a single parameter, the name of the attribute. Returns the value associated with that attribute. The value returned must be undef if no value exists for the attribute.

get_content (required)

Returns the contents of the node. In XML this is text between start and end tags.

get_root (required)

Returns the root node of this tree.

call_match (optional)

Set this to the name of the match() method to generate. Defaults to 'match'.

call_xpath (optional)

Set this to the name of the xpath() method to generate. Defaults to 'xpath'.

ALTERNATE USAGE

If you're using someone else's OO tree module, and you don't want to subclass it, you can still use Class::XPath to add XPath matching to it. This is done by calling Class::XPath-add_methods()> with all the options usually passed to use and one extra one, target. For example, to add xpath() and match() to HTML::Element (the node class for HTML::TreeBuilder):

# add Class::XPath routines to HTML::Element
Class::XPath->add_methods(target         => 'HTML::Element',
                          get_parent     => 'parent',
                          get_name       => 'tag',
                          get_attr_names => 
                            sub { my %attr = shift->all_external_attr;
                                  return keys %attr; },
                          get_attr_value => 
                            sub { my %attr = shift->all_external_attr;
                                  return $attr{$_[0]}; },
                          get_children   =>
                            sub { grep { ref $_ } shift->content_list },
                          get_content    =>
                            sub { grep { not ref $_ } shift->content_list },
                          get_root       => 
                            sub { local $_=shift; 
                                  while($_->parent) { $_ = $_->parent }
                                  return $_; });

Now you can load up an HTML file and do XPath matching on it:

my $root = HTML::TreeBuilder->new;
$root->parse_file("foo.html");1

# get a list of all paragraphs
my @paragraphs = $root->match('//p');

# get the title element
my ($title) = $root->match('/head/title');

GENERATED METHODS

This module generates two public methods for your class:

@results = $node->match('/xpath/expression')

This method performs an XPath match against the tree to which this node belongs. See the SYNTAX documentation for the range of supported expressions. The return value is either a list of node objects, a list of values (when retrieving specific attributes) or an empty list if no matches could be found. If your XPath expression cannot be parsed then the method will die.

You can change the name of this method with the 'call_match' option described above.

$xpath = $node->xpath()

Get an xpath to uniquely identify this node. Can be used with match() to find the element later. The xpath returned is guaranteed to be unqiue within the element tree. For example, the third node named "paragraph" inside node named "page" has the xpath "/page[1]/paragraph[2]".

You can change the name of this method with the 'call_xpath' option described above.

SYNTAX

This module supports a small subset of XPath at the moment. Here is a list of the type of expressions it knows about:

.

Selects and returns the current node.

name
./name

Selects a list of nodes called 'name' in the tree below the current node.

/name

Selects a list of nodes called 'name' directly below the root of the tree.

//name

Selects all nodes with a matching name, anywhere in the tree.

parent/child/grandchild

Selects a list of grandchildren for all children of all parents.

parent[1]/child[2]

Selects a single child by indexing into the children lists.

parent[-1]/child[0]

Selects the first child of the last parent. In the real XPath they spell this 'parent[last()]/child[0]' but supporting the Perl syntax is practically free here. Eventually I'll support the XPath style too.

../child[2]

Selects the second child from the parent of the current node. Currently .. only works at the start of an XPath, mostly because I can't imagine using it anywhere else.

child[@id=10]

Selects the child node with an 'id' attribute of 10.

child[@id>10]

Selects all the child nodes with an 'id' attribute greater than 10. Other supported operators are '<', '<=', '>=' and '!='.

child[@category="sports"]

Selects the child with an 'category' attribute of "sports". The value must be a quoted string (single or double) and no escaping is allowed.

child[title="Hello World"]

Selects the child with a 'title' child element whose content is "Hello World". The value must be a quoted string (single or double) and no escaping is allowed. e.g.

<child>
  <title>Hello World</title>
</child>
//title[.="Hello World"]

Selects all 'title' elements whose content is "Hello World".

child/@attr

Returns the list of values for all attributes "attr" within each child.

//@attr

Returns the list of values for all attributes "attr" within each node.

NOTE: this module has no support for Unicode. If this is a problem for you please consider sending me a patch. I'm certain that I don't know enough about Unicode to do it right myself.

BUGS

I know of no bugs in this module. If you find one, please file a bug report at:

http://rt.cpan.org

Alternately you can email me directly at sam@tregar.com. Please include the version of the module and a complete test case that demonstrates the bug.

TODO

Planned future work:

  • Support more of XPath!

  • Do more to detect broken get_* functions. Maybe use Carp::Assert and a special mode for use during development?

ACKNOWLEDGMENTS

I would like to thank the creators of XPath for their fine work and the W3C for supporting them in their efforts.

The following people have sent me patches and/or suggestions:

Tim Peoples
Mark Addison
Timothy Appnel

COPYRIGHT AND LICENSE

Copyright (C) 2002 Sam Tregar

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

AUTHOR

Sam Tregar <sam@tregar.com>

SEE ALSO

The XPath W3C Recommendation:

http://www.w3.org/TR/xpath