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
47 boundary, or false if it does not.
48 add_element $Element
50 The "add_element" method adds a PPI::Element object to the end of a
51 "PPI::Node". Because Elements maintain links to their parent, an
52 Element can only be added to a single Node.
53 Returns true if the PPI::Element was added. Returns "undef" if the
55 Element was already within another Node, or the method is not passed a
56 PPI::Element object.
57 elements
59 The "elements" method accesses all child elements structurally within
60 the "PPI::Node" object. Note that in the base of the PPI::Structure
61 classes, this "DOES" include the brace tokens at either end of the
62 structure.
63 Returns a list of zero or more PPI::Element objects.
65 Alternatively, if called in the scalar context, the "elements" method
67 returns a count of the number of elements.
68 first_element
70 The "first_element" method accesses the first element structurally
71 within the "PPI::Node" object. As for the "elements" method, this does
72 include the brace tokens for PPI::Structure objects.
73 Returns a PPI::Element object, or "undef" if for some reason the
75 "PPI::Node" object does not contain any elements.
76 last_element
78 The "last_element" method accesses the last element structurally within
79 the "PPI::Node" object. As for the "elements" method, this does include
80 the brace tokens for PPI::Structure objects.
81 Returns a PPI::Element object, or "undef" if for some reason the
83 "PPI::Node" object does not contain any elements.
84 children
86 The "children" method accesses all child elements lexically within the
87 "PPI::Node" object. Note that in the case of the PPI::Structure
88 classes, this does NOT include the brace tokens at either end of the
89 structure.
90 Returns a list of zero of more PPI::Element objects.
92 Alternatively, if called in the scalar context, the "children" method
94 returns a count of the number of lexical children.
95 schildren
97 The "schildren" method is really just a convenience, the significant-
98 only variation of the normal "children" method.
99 In list context, returns a list of significant children. In scalar
101 context, returns the number of significant children.
102 child $index
104 The "child" method accesses a child PPI::Element object by its position
105 within the Node.
106 Returns a PPI::Element object, or "undef" if there is no child element
108 at that node.
109 schild $index
111 The lexical structure of the Perl language ignores 'insignificant'
112 items, such as whitespace and comments, while PPI treats these items as
113 valid tokens so that it can reassemble the file at any time. Because of
114 this, in many situations there is a need to find an Element within a
115 Node by index, only counting lexically significant Elements.
116 The "schild" method returns a child Element by index, ignoring
118 insignificant Elements. The index of a child Element is specified in
119 the same way as for a normal array, with the first Element at index 0,
120 and negative indexes used to identify a "from the end" position.
121 contains $Element
123 The "contains" method is used to determine if another PPI::Element
124 object is logically "within" a "PPI::Node". For the special case of the
125 brace tokens at either side of a PPI::Structure object, they are
126 generally considered "within" a PPI::Structure object, even if they are
127 not actually in the elements for the PPI::Structure.
128 Returns true if the PPI::Element is within us, false if not, or "undef"
130 on error.
131 find $class | \&wanted
133 The "find" method is used to search within a code tree for PPI::Element
134 objects that meet a particular condition.
135 To specify the condition, the method can be provided with either a
137 simple class name (full or shortened), or a "CODE"/function reference.
138 # Find all single quotes in a Document (which is a Node)
140 $Document->find('PPI::Quote::Single');
141 # The same thing with a shortened class name
143 $Document->find('Quote::Single');
144 # Anything more elaborate, we go with the sub
146 $Document->find( sub {
147 # At the top level of the file...
148 $_[1]->parent == $_[0]
149 and (
150 # ...find all comments and POD
151 $_[1]->isa('PPI::Token::Pod')
152 or
153 $_[1]->isa('PPI::Token::Comment')
154 )
155 } );
156 The function will be passed two arguments, the top-level "PPI::Node"
158 you are searching in and the current PPI::Element that the condition is
159 testing.
160 The anonymous function should return one of three values. Returning
162 true indicates a condition match, defined-false (0 or '') indicates no-
163 match, and "undef" indicates no-match and no-descend.
164 In the last case, the tree walker will skip over anything below the
166 "undef"-returning element and move on to the next element at the same
167 level.
168 To halt the entire search and return "undef" immediately, a condition
170 function should throw an exception (i.e. "die").
171 Note that this same wanted logic is used for all methods documented to
173 have a "\&wanted" parameter, as this one does.
174 The "find" method returns a reference to an array of PPI::Element
176 objects that match the condition, false (but defined) if no Elements
177 match the condition, or "undef" if you provide a bad condition, or an
178 error occurs during the search process.
179 In the case of a bad condition, a warning will be emitted as well.
181 find_first $class | \&wanted
183 If the normal "find" method is like a grep, then "find_first" is
184 equivalent to the List::Util "first" function.
185 Given an element class or a wanted function, it will search depth-first
187 through a tree until it finds something that matches the condition,
188 returning the first Element that it encounters.
189 See the "find" method for details on the format of the search
191 condition.
192 Returns the first PPI::Element object that matches the condition, false
194 if nothing matches the condition, or "undef" if given an invalid
195 condition, or an error occurs.
196 find_any $class | \&wanted
198 The "find_any" method is a short-circuiting true/false method that
199 behaves like the normal "find" method, but returns true as soon as it
200 finds any Elements that match the search condition.
201 See the "find" method for details on the format of the search
203 condition.
204 Returns true if any Elements that match the condition can be found,
206 false if not, or "undef" if given an invalid condition, or an error
207 occurs.
208 remove_child $Element
210 If passed a PPI::Element object that is a direct child of the Node, the
211 "remove_element" method will remove the "Element" intact, along with
212 any of its children. As such, this method acts essentially as a 'cut'
213 function.
214 If successful, returns the removed element. Otherwise, returns
216 "undef".
217 replace_child $Element, $Replacement
219 If successful, returns the replace element. Otherwise, returns
220 "undef".
221 prune $class | \&wanted
223 The "prune" method is used to strip PPI::Element objects out of a code
224 tree. The argument is the same as for the "find" method, either a class
225 name, or an anonymous subroutine which returns true/false. Any Element
226 that matches the class|wanted will be deleted from the code tree, along
227 with any of its children.
228 The "prune" method returns the number of "Element" objects that matched
230 and were removed, non-recursively. This might also be zero, so avoid a
231 simple true/false test on the return false of the "prune" method. It
232 returns "undef" on error, which you probably should test for.
233
235 - Move as much as possible to PPI::XS
236
238 See the support section in the main module.
239
241 Adam Kennedy <adamk@cpan.org>
242
244 Copyright 2001 - 2011 Adam Kennedy.
245 This program is free software; you can redistribute it and/or modify it
247 under the same terms as Perl itself.
248 The full text of the license can be found in the LICENSE file included
250 with this module.
251perl v5.38.0 2023-09-22 PPI::Node(3)