1Pod::Abstract::Path(3)User Contributed Perl DocumentationPod::Abstract::Path(3)
2
3
4

NAME

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

SYNOPSIS

10        /head1(1)/head2          # All head2 elements under
11                                 # the 2nd head1 element
12        //item                   # All items anywhere
13        //item[@label =~ {^\*$}] # All items with '*' labels.
14        //head2[/hilight]        # All head2 elements containing
15                                 # "hilight" elements
16
17        # Top level head1s containing head2s that have headings matching
18        # "NAME", and also have at least one list somewhere in their
19        # contents.
20        /head1[/head2[@heading =~ {NAME}]][//over]
21
22        # Top level headings having the same title as the following heading.
23        /head1[@heading = >>@heading]
24
25        # Top level headings containing at least one subheading with the same
26        # name.
27        /head1[@heading = ./head2@heading]
28

DESCRIPTION

30       Pod::Abstract::Path is a path selection syntax that allows fast and
31       easy traversal of Pod::Abstract documents. While it has a simple
32       syntax, there is significant complexity in the queries that you can
33       create.
34
35       Not all of the designed features have yet been implemented, but it is
36       currently quite useful, and all of the filters in "paf" make use of Pod
37       Paths.
38
39   SYMBOLS:
40       /   Selects children of the left hand side.
41
42       //  Selects all descendants of the left hand side.
43
44       .   Selects the current node - this is a NOP that can be used in
45           expressions.
46
47       ..  Selects the parrent node. If there are multiple nodes selected, all
48           of their parents will be included.
49
50       ^   Selects the root node of the tree for the current node. This allows
51           you to escape from a nested expression. Note that this is the ROOT
52           node, not the node that you started from.
53
54           If you want to evaluate an expression from a node as though it were
55           the root node, the easiest ways are to detach or dup it - otherwise
56           the root operator will find the original root node.
57
58       name, #cut, :text, :verbatim, :paragraph
59           Any element name, or symbolic type name, will restrict the
60           selection to only elements matching that type. e.g,
61           ""//:paragraph"" will select all descendants, anywhere, but then
62           restrict that set to only ":paragraph" type nodes.
63
64           Names together separated by spaces will match all of those names -
65           e.g: "//head1 over" will match all lists and all head1s.
66
67       &, | (union and intersection)
68           Union will take expressions on either side, and return all nodes
69           that are members of either set. Intersection returns nodes that are
70           members of BOTH sets. These can be used to extend expressions, and
71           within [ expressions ] where a path is supported (left side of a
72           match, left or right side of an = sign). These are NOT logical
73           and/or, though a similar effect can be induced through these
74           operators.
75
76       @attrname
77           The named attribute of the nodes on the left hand side. Current
78           attributes are @heading for head1 through head4, and @label for
79           list items.
80
81       [ expression ]
82           Select only the left hand elements that match the expression in the
83           brackets. The expression will be evaluated from the point of view
84           of each node in the current result set.
85
86           Expressions can be:
87
88           simple: "[/head2]"
89               Any regular path will be true if there are any nodes matched.
90               The above example will be true if there are any head2 nodes as
91               direct children of the selected node.
92
93           regex match: "[@heading =~ {FOO}]"
94               A regex match will be true if the left hand expression has
95               nodes that match the regular expression between the braces on
96               the right hand side. The above example will match anything with
97               a heading containing "FOO".
98
99               Optionally, the right hand closing brace may have the "i"
100               modifier to cause case-insensitive matching. i.e "[@heading =~
101               {foo}i]" will match "foo" or "fOO".
102
103           complement: "[! /head2 ]"
104               Reverses the remainder of the expression. The above example
105               will match anything without a child head2 node.
106
107           compare operators: eg. "[ /node1 eq /node2 ]"
108               Matches nodes where the operator is satistied for at least one
109               pair of nodes. The right hand expression can be a constant
110               string (single quoted: 'string', or a second expression. If two
111               expressions are used, they are matched combinationally - i.e,
112               all result nodes on the left are matched against all result
113               nodes on the right. Both sides may contain nested expressions.
114
115               The following Perl compatible operators are supported:
116
117               String: " eq gt lt le ge ne "
118
119               Numeric: "== < > <= >= !="
120

PERFORMANCE

122       Pod::Abstract::Path is not designed to be fast. It is designed to be
123       expressive and useful, but it involves sucessive
124       expand/de-duplicate/linear search operations and doing this with large
125       documents containing many nodes is not suitable for high performance
126       systems.
127
128       Simple expressions can be fast enough, but there is nothing to stop you
129       from writing "//[<condition>]" and linear-searching all 10,000 nodes of
130       your Pod document. Use with caution in interactive systems.
131

INTERFACE

133       It is recommended you use the "<Pod::Abstract::Node-"select>> method to
134       evaluate Path expressions.
135
136       If you wish to generate paths for use in other modules, use
137       "parse_path" to generate a parse tree, pass that as an argument to
138       "new", then use "process" to evaluate the expression against a list of
139       nodes. You can re-use the same parse tree to process multiple lists of
140       nodes in this fashion.
141

METHODS

143   filter_unique
144       It is possible during processing - especially using ^ or .. operators -
145       to generate many duplicate matches of the same nodes. Each pass around
146       the loop, we filter to unique nodes so that duplicates cannot inflate
147       more than one time.
148
149       This effectively means that "//^" (however awful that is) will match
150       one node only - just really inefficiently.
151
152   parse_path
153       Parse a list of lexemes and generate a driver tree for the process
154       method. This is a simple recursive descent parser with one element of
155       lookahead.
156

AUTHOR

158       Ben Lilburne <bnej@mac.com>
159
161       Copyright (C) 2009 Ben Lilburne
162
163       This program is free software; you can redistribute it and/or modify it
164       under the same terms as Perl itself.
165
166
167
168perl v5.36.0                      2023-01-20            Pod::Abstract::Path(3)
Impressum