/ 
B-XPath-0.01
River stage zero No dependents
/ B::XPath

NAME

B::XPath - search Perl optrees with XPath syntax

SYNOPSIS

Perl represents programs internally as a tree of opcodes. To execute a program, it walks this tree, performing each operation as it encounters it. The B family of modules allows you to examine (and in some cases, manipulate) this optree on programs even as they run.

B::XPath allows you to use XPath syntax to select ops in the optree.

    use B::XPath;

    my $node    = B::XPath->fetch_root( \&some_function );
	my $root    = B::XPath->fetch_main_root();

	# find all global scalar accesses
	my @globals = $root->match( '//gvsv' );

	# find all global scalar accesses within some_function() named $bob
	my @bobs    = $node->match( '//gvsv[@NAME="bob"]' );

Class Methods

There are two methods to use to start your match; both set the root of the tree to search. There's also a nice helper method you'll probably never use unless you find a bug.

fetch_root( $subref )

This method returns the B::XPath::Node object at the root of the optree for the subroutine reference. All matches performed on this node will search this branch of the optree for matching nodes.

fetch_main_root()

This method returns the B::XPath::Node object at the root of the program. Use this to search your entire program (at least, the part of it outside of any given subroutine).

find_op_class( $op )

Given a B::OP or descendent object, returns the name of the appropriate B::XPath::Node subclass to use to wrap that op so that B::XPath can manipulate it appropriately.

Node Methods

There are several methods available on the nodes returned from find or match requests.

match( $xpath_expression )

Given an XPath expression, searches the tree with this node at the root to find all nodes matching the expression. Returns a list of all found nodes.

Note that this does not return the nodes in depth-first order. I think.

create( op = $op, root => $root )>

Creates a new B::XPath::Node object (of the appropriate subclass), setting the op and root parameters. This will descend into all of the op's children, calling create() appropriately.

You probably don't need to know this exists unless you want to fix a bug in the module

get_root()

Returns the root node of the tree from which you searched for this node.

get_parent()

Returns the parent node of this node, if it exists. If this is a root node, it will return nothing.

get_children()

Returns a list of all of the child nodes of this node, if there are any. Otherwise it returns nothing.

get_name()

Returns the name of the op that this node represents.

get_file()

Returns the name of the file containing the node this op represents. This may not always be completely accurate, depending on certain optimizations -- but it tries really hard.

get_line()

Returns the number of the line of course code in which the node this op represents appears. This may not always be completely accurate, depending on certain optimizations -- but it tries really hard.

There are a few other methods available, but I don't want to make them public just yet.

AUTHOR

chromatic, <chromatic at wgz.org>

BUGS

There aren't any, to my knowledge, except that this doesn't support all of XPath. See Class::XPath for more information.

Of course, there's no guarantee that future versions of Perl will create the same optrees ... so there's a chance that this isn't as robust as you might like.

Please report any bugs or feature requests to bug-b-xpath at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=B-XPath. This will notify me and the system will automatically notify you of progress on your bug as I make changes.

SUPPORT

You may be able to find more information at:

COPYRIGHT & LICENSE

Copyright 2006 chromatic, all rights reserved.

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

See also Perl Hacks, copyright 2006 O'Reilly Media, Inc., which explains more about how to use this module.