1PPI::Element(3) User Contributed Perl Documentation PPI::Element(3)
2
6 PPI::Element - The abstract Element class, a base for all source
7 objects
8
10 PPI::Element is the root of the PDOM tree
11
13 The abstract "PPI::Element" serves as a base class for all source-
14 related objects, from a single whitespace token to an entire document.
15 It provides a basic set of methods to provide a common interface and
16 basic implementations.
17
19 significant
20 Because we treat whitespace and other non-code items as Tokens (in
21 order to be able to "round trip" the PPI::Document back to a file) the
22 "significant" method allows us to distinguish between tokens that form
23 a part of the code, and tokens that aren't significant, such as
24 whitespace, POD, or the portion of a file after (and including) the
25 "__END__" token.
26 Returns true if the Element is significant, or false it not.
28 class
30 The "class" method is provided as a convenience, and really does
31 nothing more than returning ref($self). However, some people have found
32 that they appreciate the laziness of "$Foo->class eq 'whatever'", so I
33 have caved to popular demand and included it.
34 Returns the class of the Element as a string
36 tokens
38 The "tokens" method returns a list of PPI::Token objects for the
39 Element, essentially getting back that part of the document as if it
40 had not been lexed.
41 This also means there are no Statements and no Structures in the list,
43 just the Token classes.
44 content
46 For any "PPI::Element", the "content" method will reconstitute the base
47 code for it as a single string. This method is also the method used for
48 overloading stringification. When an Element is used in a double-quoted
49 string for example, this is the method that is called.
50 WARNING:
52 You should be aware that because of the way that here-docs are handled,
54 any here-doc content is not included in "content", and as such you
55 should not eval or execute the result if it contains any
56 PPI::Token::HereDoc.
57 The PPI::Document method "serialize" should be used to stringify a PDOM
59 document into something that can be executed as expected.
60 Returns the basic code as a string (excluding here-doc content).
62 parent
64 Elements themselves are not intended to contain other Elements, that is
65 left to the PPI::Node abstract class, a subclass of "PPI::Element".
66 However, all Elements can be contained within a parent Node.
67 If an Element is within a parent Node, the "parent" method returns the
69 Node.
70 descendant_of $element
72 Answers whether a "PPI::Element" is contained within another one.
73 "PPI::Element"s are considered to be descendants of themselves.
75 ancestor_of $element
77 Answers whether a "PPI::Element" is contains another one.
78 "PPI::Element"s are considered to be ancestors of themselves.
80 statement
82 For a "PPI::Element" that is contained (at some depth) within a
83 PPI::Statement, the "statement" method will return the first parent
84 Statement object lexically 'above' the Element.
85 Returns a PPI::Statement object, which may be the same Element if the
87 Element is itself a PPI::Statement object.
88 Returns false if the Element is not within a Statement and is not
90 itself a Statement.
91 top
93 For a "PPI::Element" that is contained within a PDOM tree, the "top"
94 method will return the top-level Node in the tree. Most of the time
95 this should be a PPI::Document object, however this will not always be
96 so. For example, if a subroutine has been removed from its Document, to
97 be moved to another Document.
98 Returns the top-most PDOM object, which may be the same Element, if it
100 is not within any parent PDOM object.
101 document
103 For an Element that is contained within a PPI::Document object, the
104 "document" method will return the top-level Document for the Element.
105 Returns the PPI::Document for this Element, or false if the Element is
107 not contained within a Document.
108 next_sibling
110 All PPI::Node objects (specifically, our parent Node) contain a number
111 of "PPI::Element" objects. The "next_sibling" method returns the
112 "PPI::Element" immediately after the current one, or false if there is
113 no next sibling.
114 snext_sibling
116 As per the other 's' methods, the "snext_sibling" method returns the
117 next significant sibling of the "PPI::Element" object.
118 Returns a "PPI::Element" object, or false if there is no 'next'
120 significant sibling.
121 previous_sibling
123 All PPI::Node objects (specifically, our parent Node) contain a number
124 of "PPI::Element" objects. The "previous_sibling" method returns the
125 Element immediately before the current one, or false if there is no
126 'previous' "PPI::Element" object.
127 sprevious_sibling
129 As per the other 's' methods, the "sprevious_sibling" method returns
130 the previous significant sibling of the "PPI::Element" object.
131 Returns a "PPI::Element" object, or false if there is no 'previous'
133 significant sibling.
134 first_token
136 As a support method for higher-order algorithms that deal specifically
137 with tokens and actual Perl content, the "first_token" method finds the
138 first PPI::Token object within or equal to this one.
139 That is, if called on a PPI::Node subclass, it will descend until it
141 finds a PPI::Token. If called on a PPI::Token object, it will return
142 the same object.
143 Returns a PPI::Token object, or dies on error (which should be
145 extremely rare and only occur if an illegal empty PPI::Statement exists
146 below the current Element somewhere.)
147 last_token
149 As a support method for higher-order algorithms that deal specifically
150 with tokens and actual Perl content, the "last_token" method finds the
151 last PPI::Token object within or equal to this one.
152 That is, if called on a PPI::Node subclass, it will descend until it
154 finds a PPI::Token. If called on a PPI::Token object, it will return
155 the itself.
156 Returns a PPI::Token object, or dies on error (which should be
158 extremely rare and only occur if an illegal empty PPI::Statement exists
159 below the current Element somewhere.)
160 next_token
162 As a support method for higher-order algorithms that deal specifically
163 with tokens and actual Perl content, the "next_token" method finds the
164 PPI::Token object that is immediately after the current Element, even
165 if it is not within the same parent PPI::Node as the one for which the
166 method is being called.
167 Note that this is not defined as a PPI::Token-specific method, because
169 it can be useful to find the next token that is after, say, a
170 PPI::Statement, although obviously it would be useless to want the next
171 token after a PPI::Document.
172 Returns a PPI::Token object, or false if there are no more tokens after
174 the Element.
175 previous_token
177 As a support method for higher-order algorithms that deal specifically
178 with tokens and actual Perl content, the "previous_token" method finds
179 the PPI::Token object that is immediately before the current Element,
180 even if it is not within the same parent PPI::Node as this one.
181 Note that this is not defined as a PPI::Token-only method, because it
183 can be useful to find the token is before, say, a PPI::Statement,
184 although obviously it would be useless to want the next token before a
185 PPI::Document.
186 Returns a PPI::Token object, or false if there are no more tokens
188 before the "Element".
189 clone
191 As per the Clone module, the "clone" method makes a perfect copy of an
192 Element object. In the generic case, the implementation is done using
193 the Clone module's mechanism itself. In higher-order cases, such as for
194 Nodes, there is more work involved to keep the parent-child links
195 intact.
196 insert_before @Elements
198 The "insert_before" method allows you to insert lexical perl content,
199 in the form of "PPI::Element" objects, before the calling "Element".
200 You need to be very careful when modifying perl code, as it's easy to
201 break things.
202 In its initial incarnation, this method allows you to insert a single
204 Element, and will perform some basic checking to prevent you inserting
205 something that would be structurally wrong (in PDOM terms).
206 In future, this method may be enhanced to allow the insertion of
208 multiple Elements, inline-parsed code strings or
209 PPI::Document::Fragment objects.
210 Returns true if the Element was inserted, false if it can not be
212 inserted, or "undef" if you do not provide a "PPI::Element" object as a
213 parameter.
214 insert_after @Elements
216 The "insert_after" method allows you to insert lexical perl content, in
217 the form of "PPI::Element" objects, after the calling "Element". You
218 need to be very careful when modifying perl code, as it's easy to break
219 things.
220 In its initial incarnation, this method allows you to insert a single
222 Element, and will perform some basic checking to prevent you inserting
223 something that would be structurally wrong (in PDOM terms).
224 In future, this method may be enhanced to allow the insertion of
226 multiple Elements, inline-parsed code strings or
227 PPI::Document::Fragment objects.
228 Returns true if the Element was inserted, false if it can not be
230 inserted, or "undef" if you do not provide a "PPI::Element" object as a
231 parameter.
232 remove
234 For a given "PPI::Element", the "remove" method will remove it from its
235 parent intact, along with all of its children.
236 Returns the "Element" itself as a convenience, or "undef" if an error
238 occurs while trying to remove the "Element".
239 delete
241 For a given "PPI::Element", the "delete" method will remove it from its
242 parent, immediately deleting the "Element" and all of its children (if
243 it has any).
244 Returns true if the "Element" was successfully deleted, or "undef" if
246 an error occurs while trying to remove the "Element".
247 replace $Element
249 Although some higher level class support more exotic forms of replace,
250 at the basic level the "replace" method takes a single "Element" as an
251 argument and replaces the current "Element" with it.
252 To prevent accidental damage to code, in this initial implementation
254 the replacement element must be of the same class (or a subclass) as
255 the one being replaced.
256 If successful, returns the replace element. Otherwise, returns
258 "undef".
259 location
261 If the Element exists within a PPI::Document that has indexed the
262 Element locations using "PPI::Document::index_locations", the
263 "location" method will return the location of the first character of
264 the Element within the Document.
265 Returns the location as a reference to a five-element array in the form
267 "[ $line, $rowchar, $col, $logical_line, $logical_file_name ]". The
268 values are in a human format, with the first character of the file
269 located at "[ 1, 1, 1, ?, 'something' ]".
270 The second and third numbers are similar, except that the second is the
272 literal horizontal character, and the third is the visual column,
273 taking into account tabbing (see "tab_width [ $width ]" in
274 PPI::Document).
275 The fourth number is the line number, taking into account any "#line"
277 directives. The fifth element is the name of the file that the element
278 was found in, if available, taking into account any "#line" directives.
279 Returns "undef" on error, or if the PPI::Document object has not been
281 indexed.
282 line_number
284 If the Element exists within a PPI::Document that has indexed the
285 Element locations using "PPI::Document::index_locations", the
286 "line_number" method will return the line number of the first character
287 of the Element within the Document.
288 Returns "undef" on error, or if the PPI::Document object has not been
290 indexed.
291 column_number
293 If the Element exists within a PPI::Document that has indexed the
294 Element locations using "PPI::Document::index_locations", the
295 "column_number" method will return the column number of the first
296 character of the Element within the Document.
297 Returns "undef" on error, or if the PPI::Document object has not been
299 indexed.
300 visual_column_number
302 If the Element exists within a PPI::Document that has indexed the
303 Element locations using "PPI::Document::index_locations", the
304 "visual_column_number" method will return the visual column number of
305 the first character of the Element within the Document, according to
306 the value of "tab_width [ $width ]" in PPI::Document.
307 Returns "undef" on error, or if the PPI::Document object has not been
309 indexed.
310 logical_line_number
312 If the Element exists within a PPI::Document that has indexed the
313 Element locations using "PPI::Document::index_locations", the
314 "logical_line_number" method will return the line number of the first
315 character of the Element within the Document, taking into account any
316 "#line" directives.
317 Returns "undef" on error, or if the PPI::Document object has not been
319 indexed.
320 logical_filename
322 If the Element exists within a PPI::Document that has indexed the
323 Element locations using "PPI::Document::index_locations", the
324 "logical_filename" method will return the logical file name containing
325 the first character of the Element within the Document, taking into
326 account any "#line" directives.
327 Returns "undef" on error, or if the PPI::Document object has not been
329 indexed.
330
332 It would be nice if "location" could be used in an ad-hoc manner. That
333 is, if called on an Element within a Document that has not been
334 indexed, it will do a one-off calculation to find the location. It
335 might be very painful if someone started using it a lot, without
336 remembering to index the document, but it would be handy for things
337 that are only likely to use it once, such as error handlers.
338
340 See the support section in the main module.
341
343 Adam Kennedy <adamk@cpan.org>
344
346 Copyright 2001 - 2011 Adam Kennedy.
347 This program is free software; you can redistribute it and/or modify it
349 under the same terms as Perl itself.
350 The full text of the license can be found in the LICENSE file included
352 with this module.
353perl v5.36.0 2023-01-20 PPI::Element(3)