1PPI::Node(3) User Contributed Perl Documentation PPI::Node(3)
2
6 PPI::Node - Abstract PPI Node class, an Element that can contain other
7 Elements
8
10 PPI::Node
11 isa PPI::Element
12
14 # Create a typical node (a Document in this case)
15 my $Node = PPI::Document->new;
16 # Add an element to the node( in this case, a token )
18 my $Token = PPI::Token::Word->new('my');
19 $Node->add_element( $Token );
20 # Get the elements for the Node
22 my @elements = $Node->children;
23 # Find all the barewords within a Node
25 my $barewords = $Node->find( 'PPI::Token::Word' );
26 # Find by more complex criteria
28 my $my_tokens = $Node->find( sub { $_[1]->content eq 'my' } );
29 # Remove all the whitespace
31 $Node->prune( 'PPI::Token::Whitespace' );
32 # Remove by more complex criteria
34 $Node->prune( sub { $_[1]->content eq 'my' } );
35
37 The "PPI::Node" class provides an abstract base class for the Element
38 classes that are able to contain other elements PPI::Document,
39 PPI::Statement, and PPI::Structure.
40 As well as those listed below, all of the methods that apply to
42 PPI::Element objects also apply to "PPI::Node" objects.
43
45 scope
46 The "scope" method returns true if the node represents a lexical scope
48 boundary, or false if it does not.
49 add_element $Element
51 The "add_element" method adds a PPI::Element object to the end of a
53 "PPI::Node". Because Elements maintain links to their parent, an Ele‐
54 ment can only be added to a single Node.
55 Returns true if the PPI::Element was added. Returns "undef" if the Ele‐
57 ment was already within another Node, or the method is not passed a
58 PPI::Element object.
59 elements
61 The "elements" method accesses all child elements structurally within
63 the "PPI::Node" object. Note that in the base of the PPI::Structure
64 classes, this "DOES" include the brace tokens at either end of the
65 structure.
66 Returns a list of zero or more PPI::Element objects.
68 Alternatively, if called in the scalar context, the "elements" method
70 returns a count of the number of elements.
71 first_element
73 The "first_element" method accesses the first element structurally
75 within the "PPI::Node" object. As for the "elements" method, this does
76 include the brace tokens for PPI::Structure objects.
77 Returns a PPI::Element object, or "undef" if for some reason the
79 "PPI::Node" object does not contain any elements.
80 last_element
82 The "last_element" method accesses the last element structurally within
84 the "PPI::Node" object. As for the "elements" method, this does include
85 the brace tokens for PPI::Structure objects.
86 Returns a PPI::Element object, or "undef" if for some reason the
88 "PPI::Node" object does not contain any elements.
89 children
91 The "children" method accesses all child elements lexically within the
93 "PPI::Node" object. Note that in the case of the PPI::Structure
94 classes, this does NOT include the brace tokens at either end of the
95 structure.
96 Returns a list of zero of more PPI::Element objects.
98 Alternatively, if called in the scalar context, the "children" method
100 returns a count of the number of lexical children.
101 schildren
103 The "schildren" method is really just a convenience, the significant-
105 only variation of the normal "children" method.
106 In list context, returns a list of significant children. In scalar con‐
108 text, returns the number of significant children.
109 child $index
111 The "child" method accesses a child PPI::Element object by its position
113 within the Node.
114 Returns a PPI::Element object, or "undef" if there is no child element
116 at that node.
117 schild $index
119 The lexical structure of the Perl language ignores 'insignificant'
121 items, such as whitespace and comments, while PPI treats these items as
122 valid tokens so that it can reassemble the file at any time. Because of
123 this, in many situations there is a need to find an Element within a
124 Node by index, only counting lexically significant Elements.
125 The "schild" method returns a child Element by index, ignoring
127 insignificant Elements. The index of a child Element is specified in
128 the same way as for a normal array, with the first Element at index 0,
129 and negative indexes used to identify a "from the end" position.
130 contains $Element
132 The "contains" method is used to determine if another PPI::Element
134 object is logically "within" a "PPI::Node". For the special case of the
135 brace tokens at either side of a PPI::Structure object, they are gener‐
136 ally considered "within" a PPI::Structure object, even if they are not
137 actually in the elements for the PPI::Structure.
138 Returns true if the PPI::Element is within us, false if not, or "undef"
140 on error.
141 find $class ⎪ \&wanted
143 The "find" method is used to search within a code tree for PPI::Element
145 objects that meet a particular condition.
146 To specify the condition, the method can be provided with either a sim‐
148 ple class name (full or shortened), or a "CODE"/function reference.
149 # Find all single quotes in a Document (which is a Node)
151 $Document->find('PPI::Quote::Single');
152 # The same thing with a shortened class name
154 $Document->find('Quote::Single');
155 # Anything more elaborate, we so with the sub
157 $Document->find( sub {
158 # At the top level of the file...
159 $_[1]->parent == $_[0]
160 and (
161 # ...find all comments and POD
162 $_[1]->isa('PPI::Token::Pod')
163 or
164 $_[1]->isa('PPI::Token::Comment')
165 )
166 } );
167 The function will be passed two arguments, the top-level "PPI::Node"
169 you are searching in and the current PPI::Element that the condition is
170 testing.
171 The anonymous function should return one of three values. Returning
173 true indicates a condition match, defined-false (0 or '') indicates
174 no-match, and "undef" indicates no-match and no-descend.
175 In the last case, the tree walker will skip over anything below the
177 "undef"-returning element and move on to the next element at the same
178 level.
179 To halt the entire search and return "undef" immediately, a condition
181 function should throw an exception (i.e. "die").
182 Note that this same wanted logic is used for all methods documented to
184 have a "\&wanted" parameter, as this one does.
185 The "find" method returns a reference to an array of PPI::Element
187 objects that match the condition, false (but defined) if no Elements
188 match the condition, or "undef" if you provide a bad condition, or an
189 error occurs during the search process.
190 In the case of a bad condition, a warning will be emitted as well.
192 find_first $class ⎪ \&wanted
194 If the normal "find" method is like a grep, then "find_first" is equiv‐
196 alent to the Scalar::Util "first" function.
197 Given an element class or a wanted function, it will search depth-first
199 through a tree until it finds something that matches the condition,
200 returning the first Element that it encounters.
201 See the "find" method for details on the format of the search condi‐
203 tion.
204 Returns the first PPI::Element object that matches the condition, false
206 if nothing matches the condition, or "undef" if given an invalid condi‐
207 tion, or an error occurs.
208 find_any $class ⎪ \&wanted
210 The "find_any" method is a short-circuiting true/false method that
212 behaves like the normal "find" method, but returns true as soon as it
213 finds any Elements that match the search condition.
214 See the "find" method for details on the format of the search condi‐
216 tion.
217 Returns true if any Elements that match the condition can be found,
219 false if not, or "undef" if given an invalid condition, or an error
220 occurs.
221 remove_child $Element
223 If passed a PPI::Element object that is a direct child of the Node, the
225 "remove_element" method will remove the "Element" intact, along with
226 any of its children. As such, this method acts essentially as a 'cut'
227 function.
228 prune $class ⎪ \&wanted
230 The "prune" method is used to strip PPI::Element objects out of a code
232 tree. The argument is the same as for the "find" method, either a class
233 name, or an anonymous subroutine which returns true/false. Any Element
234 that matches the class⎪wanted will be deleted from the code tree, along
235 with any of its children.
236 The "prune" method returns the number of "Element" objects that matched
238 and were removed, non-recursively. This might also be zero, so avoid a
239 simple true/false test on the return false of the "prune" method. It
240 returns "undef" on error, which you probably should test for.
241
243 - Move as much as possible to PPI::XS
244
246 See the support section in the main module.
247
249 Adam Kennedy <adamk@cpan.org>
250
252 Copyright 2001 - 2006 Adam Kennedy.
253 This program is free software; you can redistribute it and/or modify it
255 under the same terms as Perl itself.
256 The full text of the license can be found in the LICENSE file included
258 with this module.
259perl v5.8.8 2006-09-23 PPI::Node(3)