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

NAME

6       PPI::Element - The abstract Element class, a base for all source
7       objects
8

INHERITANCE

10         PPI::Element is the root of the PDOM tree
11

DESCRIPTION

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

METHODS

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
27       Returns true if the Element is significant, or false it not.
28
29   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
35       Returns the class of the Element as a string
36
37   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
42       This also means there are no Statements and no Structures in the list,
43       just the Token classes.
44
45   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
51       WARNING:
52
53       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
58       The PPI::Document method "serialize" should be used to stringify a PDOM
59       document into something that can be executed as expected.
60
61       Returns the basic code as a string (excluding here-doc content).
62
63   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
68       If an Element is within a parent Node, the "parent" method returns the
69       Node.
70
71   descendant_of $element
72       Answers whether a "PPI::Element" is contained within another one.
73
74       "PPI::Element"s are considered to be descendants of themselves.
75
76   ancestor_of $element
77       Answers whether a "PPI::Element" is contains another one.
78
79       "PPI::Element"s are considered to be ancestors of themselves.
80
81   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
86       Returns a PPI::Statement object, which may be the same Element if the
87       Element is itself a PPI::Statement object.
88
89       Returns false if the Element is not within a Statement and is not
90       itself a Statement.
91
92   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
99       Returns the top-most PDOM object, which may be the same Element, if it
100       is not within any parent PDOM object.
101
102   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
106       Returns the PPI::Document for this Element, or false if the Element is
107       not contained within a Document.
108
109   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
115   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
119       Returns a "PPI::Element" object, or false if there is no 'next'
120       significant sibling.
121
122   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
128   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
132       Returns a "PPI::Element" object, or false if there is no 'previous'
133       significant sibling.
134
135   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
140       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
144       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
148   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
153       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
157       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
161   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
168       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
173       Returns a PPI::Token object, or false if there are no more tokens after
174       the Element.
175
176   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
182       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
187       Returns a PPI::Token object, or false if there are no more tokens
188       before the "Element".
189
190   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
197   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
203       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
207       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
211       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
215   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
221       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
225       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
229       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
233   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
237       Returns the "Element" itself as a convenience, or "undef" if an error
238       occurs while trying to remove the "Element".
239
240   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
245       Returns true if the "Element" was successfully deleted, or "undef" if
246       an error occurs while trying to remove the "Element".
247
248   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
253       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
257   location
258       If the Element exists within a PPI::Document that has indexed the
259       Element locations using "PPI::Document::index_locations", the
260       "location" method will return the location of the first character of
261       the Element within the Document.
262
263       Returns the location as a reference to a five-element array in the form
264       "[ $line, $rowchar, $col, $logical_line, $logical_file_name ]". The
265       values are in a human format, with the first character of the file
266       located at "[ 1, 1, 1, ?, 'something' ]".
267
268       The second and third numbers are similar, except that the second is the
269       literal horizontal character, and the third is the visual column,
270       taking into account tabbing (see "tab_width [ $width ]" in
271       PPI::Document).
272
273       The fourth number is the line number, taking into account any "#line"
274       directives.  The fifth element is the name of the file that the element
275       was found in, if available, taking into account any "#line" directives.
276
277       Returns "undef" on error, or if the PPI::Document object has not been
278       indexed.
279
280   line_number
281       If the Element exists within a PPI::Document that has indexed the
282       Element locations using "PPI::Document::index_locations", the
283       "line_number" method will return the line number of the first character
284       of the Element within the Document.
285
286       Returns "undef" on error, or if the PPI::Document object has not been
287       indexed.
288
289   column_number
290       If the Element exists within a PPI::Document that has indexed the
291       Element locations using "PPI::Document::index_locations", the
292       "column_number" method will return the column number of the first
293       character of the Element within the Document.
294
295       Returns "undef" on error, or if the PPI::Document object has not been
296       indexed.
297
298   visual_column_number
299       If the Element exists within a PPI::Document that has indexed the
300       Element locations using "PPI::Document::index_locations", the
301       "visual_column_number" method will return the visual column number of
302       the first character of the Element within the Document, according to
303       the value of "tab_width [ $width ]" in PPI::Document.
304
305       Returns "undef" on error, or if the PPI::Document object has not been
306       indexed.
307
308   logical_line_number
309       If the Element exists within a PPI::Document that has indexed the
310       Element locations using "PPI::Document::index_locations", the
311       "logical_line_number" method will return the line number of the first
312       character of the Element within the Document, taking into account any
313       "#line" directives.
314
315       Returns "undef" on error, or if the PPI::Document object has not been
316       indexed.
317
318   logical_filename
319       If the Element exists within a PPI::Document that has indexed the
320       Element locations using "PPI::Document::index_locations", the
321       "logical_filename" method will return the logical file name containing
322       the first character of the Element within the Document, taking into
323       account any "#line" directives.
324
325       Returns "undef" on error, or if the PPI::Document object has not been
326       indexed.
327

TO DO

329       It would be nice if "location" could be used in an ad-hoc manner. That
330       is, if called on an Element within a Document that has not been
331       indexed, it will do a one-off calculation to find the location. It
332       might be very painful if someone started using it a lot, without
333       remembering to index the document, but it would be handy for things
334       that are only likely to use it once, such as error handlers.
335

SUPPORT

337       See the support section in the main module.
338

AUTHOR

340       Adam Kennedy <adamk@cpan.org>
341
343       Copyright 2001 - 2011 Adam Kennedy.
344
345       This program is free software; you can redistribute it and/or modify it
346       under the same terms as Perl itself.
347
348       The full text of the license can be found in the LICENSE file included
349       with this module.
350
351
352
353perl v5.34.0                      2022-02-02                   PPI::Element(3)
Impressum