NAME

Pod::Abstract::Path - Search for POD nodes matching a path within a document tree.

SYNOPSIS

 /head1(1)/head2          # All head2 elements under the 2nd head1 element
 //item                   # All items anywhere
 //item[@label =~ {^\*$}] # All items with '*' labels.
 //head2[/hilight]        # All head2 elements containing "hilight" elements

 # Top level head1s containing head2s that have headings matching
 # "NAME", and also have at least one list somewhere in their
 # contents.
 /head1[/head2[@heading =~ {NAME}]][//over]

DESCRIPTION

Pod::Abstract::Path is a path selection syntax that allows fast and easy traversal of Pod::Abstract documents. While it has a simple syntax, there is significant complexity in the queries that you can create.

Not all of the designed features have yet been implemented, but it is currently quite useful, and all of the filters in paf make use of Pod Paths.

SYMBOLS:

/

Selects children of the left hand side.

//

Selects all descendants of the left hand side.

.

Selects the current node - this is a NOP that can be used in expressions.

..

Selects the parrent node. If there are multiple nodes selected, all of their parents will be included.

name, #cut, :text, :verbatim, :paragraph

Any element name, or symbolic type name, will restrict the selection to only elements matching that type. e.g, "//:paragraph" will select all descendants, anywhere, but then restrict that set to only :paragraph type nodes.

@attrname

The named attribute of the nodes on the left hand side. Current attributes are @heading for head1 through head4, and @label for list items.

[ expression ]

Select only the left hand elements that match the expression in the brackets. The expression will be evaluated from the point of view of each node in the current result set.

Expressions can be:

simple: [/head2]

Any regular path will be true if there are any nodes matched. The above example will be true if there are any head2 nodes as direct children of the selected node.

regex match: [@heading =~ {FOO}]

A regex match will be true if the left hand expression has nodes that match the regular expression between the braces on the right hand side. The above example will match anything with a heading containing "FOO".

complement: [! /head2 ]

Reverses the remainder of the expression. The above example will match anything without a child head2 node.

parse_path

Parse a list of lexemes and generate a driver tree for the process method. This is a simple recursive descent parser with one element of lookahead.

AUTHOR

Ben Lilburne <bnej@mac.com>

COPYRIGHT AND LICENSE

Copyright (C) 2009 Ben Lilburne

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