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
32 found that they appreciate the laziness of "$Foo->class eq 'whatever'",
33 so I 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::Statment, 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 For an Element that is contained within a PPI::Document object, the
103 "document" method will return the top-level Document for the Element.
104 Returns the PPI::Document for this Element, or false if the Element is
106 not contained within a Document.
107 next_sibling
109 All PPI::Node objects (specifically, our parent Node) contain a number
110 of "PPI::Element" objects. The "next_sibling" method returns the
111 "PPI::Element" immediately after the current one, or false if there is
112 no next sibling.
113 snext_sibling
115 As per the other 's' methods, the "snext_sibling" method returns the
116 next significant sibling of the "PPI::Element" object.
117 Returns a "PPI::Element" object, or false if there is no 'next'
119 significant sibling.
120 previous_sibling
122 All PPI::Node objects (specifically, our parent Node) contain a number
123 of "PPI::Element" objects. The "previous_sibling" method returns the
124 Element immediately before the current one, or false if there is no
125 'previous' "PPI::Element" object.
126 sprevious_sibling
128 As per the other 's' methods, the "sprevious_sibling" method returns
129 the previous significant sibling of the "PPI::Element" object.
130 Returns a "PPI::Element" object, or false if there is no 'previous'
132 significant sibling.
133 first_token
135 As a support method for higher-order algorithms that deal specifically
136 with tokens and actual Perl content, the "first_token" method finds the
137 first PPI::Token object within or equal to this one.
138 That is, if called on a PPI::Node subclass, it will descend until it
140 finds a PPI::Token. If called on a PPI::Token object, it will return
141 the same object.
142 Returns a PPI::Token object, or dies on error (which should be
144 extremely rare and only occur if an illegal empty PPI::Statement exists
145 below the current Element somewhere.
146 last_token
148 As a support method for higher-order algorithms that deal specifically
149 with tokens and actual Perl content, the "last_token" method finds the
150 last PPI::Token object within or equal to this one.
151 That is, if called on a PPI::Node subclass, it will descend until it
153 finds a PPI::Token. If called on a PPI::Token object, it will return
154 the itself.
155 Returns a PPI::Token object, or dies on error (which should be
157 extremely rare and only occur if an illegal empty PPI::Statement exists
158 below the current Element somewhere.
159 next_token
161 As a support method for higher-order algorithms that deal specifically
162 with tokens and actual Perl content, the "next_token" method finds the
163 PPI::Token object that is immediately after the current Element, even
164 if it is not within the same parent PPI::Node as the one for which the
165 method is being called.
166 Note that this is not defined as a PPI::Token-specific method, because
168 it can be useful to find the next token that is after, say, a
169 PPI::Statement, although obviously it would be useless to want the next
170 token after a PPI::Document.
171 Returns a PPI::Token object, or false if there are no more tokens after
173 the Element.
174 previous_token
176 As a support method for higher-order algorithms that deal specifically
177 with tokens and actual Perl content, the "previous_token" method finds
178 the PPI::Token object that is immediately before the current Element,
179 even if it is not within the same parent PPI::Node as this one.
180 Note that this is not defined as a PPI::Token-only method, because it
182 can be useful to find the token is before, say, a PPI::Statement,
183 although obviously it would be useless to want the next token before a
184 PPI::Document.
185 Returns a PPI::Token object, or false if there are no more tokens
187 before the "Element".
188 clone
190 As per the Clone module, the "clone" method makes a perfect copy of an
191 Element object. In the generic case, the implementation is done using
192 the Clone module's mechanism itself. In higher-order cases, such as for
193 Nodes, there is more work involved to keep the parent-child links
194 intact.
195 insert_before @Elements
197 The "insert_before" method allows you to insert lexical perl content,
198 in the form of "PPI::Element" objects, before the calling "Element".
199 You need to be very careful when modifying perl code, as it's easy to
200 break things.
201 In its initial incarnation, this method allows you to insert a single
203 Element, and will perform some basic checking to prevent you inserting
204 something that would be structurally wrong (in PDOM terms).
205 In future, this method may be enhanced to allow the insertion of
207 multiple Elements, inline-parsed code strings or
208 PPI::Document::Fragment objects.
209 Returns true if the Element was inserted, false if it can not be
211 inserted, or "undef" if you do not provide a PPI::Element object as a
212 parameter.
213 insert_after @Elements
215 The "insert_after" method allows you to insert lexical perl content, in
216 the form of "PPI::Element" objects, after the calling "Element". You
217 need to be very careful when modifying perl code, as it's easy to break
218 things.
219 In its initial incarnation, this method allows you to insert a single
221 Element, and will perform some basic checking to prevent you inserting
222 something that would be structurally wrong (in PDOM terms).
223 In future, this method may be enhanced to allow the insertion of
225 multiple Elements, inline-parsed code strings or
226 PPI::Document::Fragment objects.
227 Returns true if the Element was inserted, false if it can not be
229 inserted, or "undef" if you do not provide a PPI::Element object as a
230 parameter.
231 remove
233 For a given "PPI::Element", the "remove" method will remove it from its
234 parent intact, along with all of its children.
235 Returns the "Element" itself as a convenience, or "undef" if an error
237 occurs while trying to remove the "Element".
238 delete
240 For a given "PPI::Element", the "remove" method will remove it from its
241 parent, immediately deleting the "Element" and all of its children (if
242 it has any).
243 Returns true if the "Element" was successfully deleted, or "undef" if
245 an error occurs while trying to remove the "Element".
246 replace $Element
248 Although some higher level class support more exotic forms of replace,
249 at the basic level the "replace" method takes a single "Element" as an
250 argument and replaces the current "Element" with it.
251 To prevent accidental damage to code, in this initial implementation
253 the replacement element must be of the same class (or a subclass) as
254 the one being replaced.
255 location
257 If the Element exists within a PPI::Document that has indexed the
258 Element locations using "PPI::Document::index_locations", the
259 "location" method will return the location of the first character of
260 the Element within the Document.
261 Returns the location as a reference to a five-element array in the form
263 "[ $line, $rowchar, $col, $logical_line, $logical_file_name ]". The
264 values are in a human format, with the first character of the file
265 located at "[ 1, 1, 1, ?, 'something' ]".
266 The second and third numbers are similar, except that the second is the
268 literal horizontal character, and the third is the visual column,
269 taking into account tabbing (see "tab_width [ $width ]" in
270 PPI::Document).
271 The fourth number is the line number, taking into account any "#line"
273 directives. The fifth element is the name of the file that the element
274 was found in, if available, taking into account any "#line" directives.
275 Returns "undef" on error, or if the PPI::Document object has not been
277 indexed.
278 line_number
280 If the Element exists within a PPI::Document that has indexed the
281 Element locations using "PPI::Document::index_locations", the
282 "line_number" method will return the line number of the first character
283 of the Element within the Document.
284 Returns "undef" on error, or if the PPI::Document object has not been
286 indexed.
287 column_number
289 If the Element exists within a PPI::Document that has indexed the
290 Element locations using "PPI::Document::index_locations", the
291 "column_number" method will return the column number of the first
292 character of the Element within the Document.
293 Returns "undef" on error, or if the PPI::Document object has not been
295 indexed.
296 visual_column_number
298 If the Element exists within a PPI::Document that has indexed the
299 Element locations using "PPI::Document::index_locations", the
300 "visual_column_number" method will return the visual column number of
301 the first character of the Element within the Document, according to
302 the value of "tab_width [ $width ]" in PPI::Document.
303 Returns "undef" on error, or if the PPI::Document object has not been
305 indexed.
306 logical_line_number
308 If the Element exists within a PPI::Document that has indexed the
309 Element locations using "PPI::Document::index_locations", the
310 "logical_line_number" method will return the line number of the first
311 character of the Element within the Document, taking into account any
312 "#line" directives.
313 Returns "undef" on error, or if the PPI::Document object has not been
315 indexed.
316 logical_filename
318 If the Element exists within a PPI::Document that has indexed the
319 Element locations using "PPI::Document::index_locations", the
320 "logical_filename" method will return the logical file name containing
321 the first character of the Element within the Document, taking into
322 account any "#line" directives.
323 Returns "undef" on error, or if the PPI::Document object has not been
325 indexed.
326
328 It would be nice if "location" could be used in an ad-hoc manner. That
329 is, if called on an Element within a Document that has not been
330 indexed, it will do a one-off calculation to find the location. It
331 might be very painful if someone started using it a lot, without
332 remembering to index the document, but it would be handy for things
333 that are only likely to use it once, such as error handlers.
334
336 See the support section in the main module.
337
339 Adam Kennedy <adamk@cpan.org>
340
342 Copyright 2001 - 2009 Adam Kennedy.
343 This program is free software; you can redistribute it and/or modify it
345 under the same terms as Perl itself.
346 The full text of the license can be found in the LICENSE file included
348 with this module.
349perl v5.10.1 2009-08-08 PPI::Element(3)