1PPI::Find(3)          User Contributed Perl Documentation         PPI::Find(3)
2
3
4

NAME

6       PPI::Find - Object version of the Element->find method
7

SYNOPSIS

9         # Create the Find object
10         my $Find = PPI::Find->new( \&wanted );
11
12         # Return all matching Elements as a list
13         my @found = $Find->in( $Document );
14
15         # Can we find any matching Elements
16         if ( $Find->any_matches($Document) ) {
17               print "Found at least one matching Element";
18         }
19
20         # 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

DESCRIPTION

27       PPI::Find is the primary PDOM searching class in the core PPI package.
28
29   History
30       It became quite obvious during the development of PPI that many of the
31       modules that would be built on top of it were going to need large
32       numbers of saved, storable or easily creatable search objects that
33       could be reused a number of times.
34
35       Although the internal ->find method provides a basic ability to search,
36       it is by no means thorough. PPI::Find attempts to resolve this problem.
37
38   Structure and Style
39       PPI::Find provides a similar API to the popular File::Find::Rule module
40       for file searching, but without the ability to assemble queries.
41
42       The implementation of a separate PPI::Find::Rule sub-class that does
43       provide this ability is left as an exercise for the reader.
44
45   The &wanted function
46       At the core of each PPI::Find object is a "wanted" function that is
47       passed a number of arguments and returns a value which controls the
48       flow of the search.
49
50       As the search executes, each Element will be passed to the wanted
51       function in depth-first order.
52
53       It will be provided with two arguments. The current Element to test as
54       $_[0], and the top-level Element of the search as $_[1].
55
56       The &wanted function is expected to return 1 (positive) if the Element
57       matches the condition, 0 (false) if it does not, and undef (undefined)
58       if the condition does not match, and the Find search should not descend
59       to any of the current Element's children.
60
61       Errors should be reported from the &wanted function via die, which will
62       be caught by the Find object and returned as an error.
63

METHODS

65   new &wanted
66       The "new" constructor takes a single argument of the &wanted function,
67       as described above and creates a new search.
68
69       Returns a new PPI::Find object, or "undef" if not passed a CODE
70       reference.
71
72   clone
73       The "clone" method creates another instance of the same Find object.
74
75       The cloning is done safely, so if your existing Find object is in the
76       middle of an iteration, the cloned Find object will not also be in the
77       iteration and can be safely used independently.
78
79       Returns a duplicate PPI::Find object.
80
81   in $Document [, array_ref => 1 ]
82       The "in" method starts and completes a full run of the search.
83
84       It takes as argument a single PPI::Element object which will serve as
85       the top of the search process.
86
87       Returns a list of PPI::Element objects that match the condition
88       described by the &wanted function, or the null list on error.
89
90       You should check the ->errstr method for any errors if you are returned
91       the null list, which may also mean simply that no Elements were found
92       that matched the condition.
93
94       Because of this need to explicitly check for errors, an alternative
95       return value mechanism is provide. If you pass the "array_ref =" 1>
96       parameter to the method, it will return the list of matched Elements as
97       a reference to an ARRAY. The method will return false if no elements
98       were matched, or "undef" on error.
99
100       The ->errstr method can still be used to get the error message as
101       normal.
102
103   start $Element
104       The "start" method lets the Find object act as an iterator. The method
105       is passed the parent PPI::Element object as for the "in" method, but
106       does not accept any parameters.
107
108       To simplify error handling, the entire search is done at once, with the
109       results cached and provided as-requested.
110
111       Returns true if the search completes, and false on error.
112
113   match
114       The "match" method returns the next matching Element in the iteration.
115
116       Returns a PPI::Element object, or "undef" if there are no remaining
117       Elements to be returned.
118
119   finish
120       The "finish" method provides a mechanism to end iteration if you wish
121       to stop the iteration prematurely. It resets the Find object and allows
122       it to be safely reused.
123
124       A Find object will be automatically finished when "match" returns
125       false.  This means you should only need to call "finnish" when you stop
126       iterating early.
127
128       You may safely call this method even when not iterating and it will
129       return without failure.
130
131       Always returns true
132
133   errstr
134       The "errstr" method returns the error messages when a given PPI::Find
135       object fails any action.
136
137       Returns a string, or "undef" if there is no error.
138

TO DO

140       - Implement the PPI::Find::Rule class
141

SUPPORT

143       See the support section in the main module.
144

AUTHOR

146       Adam Kennedy <adamk@cpan.org>
147

149       Copyright 2001 - 2009 Adam Kennedy.
150
151       This program is free software; you can redistribute it and/or modify it
152       under the same terms as Perl itself.
153
154       The full text of the license can be found in the LICENSE file included
155       with this module.
156
157
158
159perl v5.10.1                      2009-08-08                      PPI::Find(3)
Impressum