1PPI::Find(3) User Contributed Perl Documentation PPI::Find(3)
2
6 PPI::Find - Object version of the Element->find method
7
9 # Create the Find object
10 my $Find = PPI::Find->new( \&wanted );
11 # Return all matching Elements as a list
13 my @found = $Find->in( $Document );
14 # Can we find any matching Elements
16 if ( $Find->any_matches($Document) ) {
17 print "Found at least one matching Element";
18 }
19 # Use the object as an iterator
21 $Find->start($Document) or die "Failed to execute search";
22 while ( my $token = $Find->match ) {
23 ...
24 }
25
27 PPI::Find is the primary PDOM searching class in the core PPI package.
28 History
30 It became quite obvious during the development of PPI that many of the
32 modules that would be built on top of it were going to need large num‐
33 bers of saved, storable or easily creatable search objects that could
34 be reused a number of times.
35 Although the internal ->find method provides a basic ability to search,
37 it is by no means thorough. PPI::Find attempts to resolve this problem.
38 Structure and Style
40 PPI::Find provides a similar API to the popular File::Find::Rule module
42 for file searching, but without the ability to assemble queries.
43 The implementation of a separate PPI::Find::Rule sub-class that does
45 provide this ability is left as an exercise for the reader.
46 The &wanted function
48 At the core of each PPI::Find object is a "wanted" function that is
50 passed a number of arguments and returns a value which controls the
51 flow of the search.
52 As the search executes, each Element will be passed to the wanted func‐
54 tion in depth-first order.
55 It will be provided with two arguments. The current Element to test as
57 $_[0], and the top-level Element of the search as $_[1].
58 The &wanted function is expected to return 1 (positive) if the Element
60 matches the condition, 0 (false) if it does not, and undef (undefined)
61 if the condition does not match, and the Find search should not descend
62 to any of the current Element's children.
63 Errors should be reported from the &wanted function via die, which will
65 be caught by the Find object and returned as an error.
66
68 new &wanted
69 The "new" constructor takes a single argument of the &wanted function,
71 as described above and creates a new search.
72 Returns a new PPI::Find object, or "undef" if not passed a CODE refer‐
74 ence.
75 clone
77 The "clone" method creates another instance of the same Find object.
79 The cloning is done safely, so if your existing Find object is in the
81 middle of an iteration, the cloned Find object will not also be in the
82 iteration and can be safely used independently.
83 Returns a duplicate PPI::Find object.
85 in $Document [, array_ref => 1 ]
87 The "in" method starts and completes a full run of the search.
89 It takes as argument a single PPI::Element object which will serve as
91 the top of the search process.
92 Returns a list of PPI::Element objects that match the condition
94 described by the &wanted function, or the null list on error.
95 You should check the ->errstr method for any errors if you are returned
97 the null list, which may also mean simply that no Elements were found
98 that matched the condition.
99 Because of this need to explicitly check for errors, an alternative
101 return value mechanism is provide. If you pass the "array_ref =" 1>
102 parameter to the method, it will return the list of matched Elements as
103 a reference to an ARRAY. The method will return false if no elements
104 were matched, or "undef" on error.
105 The ->errstr method can still be used to get the error message as nor‐
107 mal.
108 start $Element
110 The "start" method lets the Find object act as an iterator. The method
112 is passed the parent PPI::Element object as for the "in" method, but
113 does not accept any parameters.
114 To simplify error handling, the entire search is done at once, with the
116 results cached and provided as-requested.
117 Returns true if the search completes, and false on error.
119 match
121 The "match" method returns the next matching Element in the iteration.
123 Returns a PPI::Element object, or "undef" if there are no remaining
125 Elements to be returned.
126 finish
128 The "finish" method provides a mechanism to end iteration if you wish
130 to stop the iteration prematurely. It resets the Find object and allows
131 it to be safely reused.
132 A Find object will be automatically finished when "match" returns
134 false. This means you should only need to call "finnish" when you stop
135 iterating early.
136 You may safely call this method even when not iterating and it will
138 return without failure.
139 Always returns true
141 errstr
143 The "errstr" method returns the error messages when a given PPI::Find
145 object fails any action.
146 Returns a string, or "undef" if there is no error.
148
150 - Implement the PPI::Find::Rule class
151
153 See the support section in the main module.
154
156 Adam Kennedy <adamk@cpan.org>
157
159 Copyright 2001 - 2006 Adam Kennedy.
160 This program is free software; you can redistribute it and/or modify it
162 under the same terms as Perl itself.
163 The full text of the license can be found in the LICENSE file included
165 with this module.
166perl v5.8.8 2006-09-23 PPI::Find(3)