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
21       Because we treat whitespace and other non-code items as Tokens (in
22       order to be able to "round trip" the PPI::Document back to a file) the
23       "significant" method allows us to distinguish between tokens that form
24       a part of the code, and tokens that aren't significant, such as white‐
25       space, POD, or the portion of a file after (and including) the
26       "__END__" token.
27
28       Returns true if the Element is significant, or false it not.
29
30       class
31
32       The "class" method is provided as a convenience, and really does noth‐
33       ing more than returning "ref($self)". However, some people have found
34       that they appreciate the laziness of "$Foo->class eq 'whatever'", so I
35       have caved to popular demand and included it.
36
37       Returns the class of the Element as a string
38
39       tokens
40
41       The "tokens" method returns a list of PPI::Token objects for the Ele‐
42       ment, essentially getting back that part of the document as if it had
43       not been lexed.
44
45       This also means there are no Statements and no Structures in the list,
46       just the Token classes.
47
48       content
49
50       For any "PPI::Element", the "content" method will reconstitute the base
51       code for it as a single string. This method is also the method used for
52       overloading stringification. When an Element is used in a double-quoted
53       string for example, this is the method that is called.
54
55       WARNING:
56
57       You should be aware that because of the way that here-docs are handled,
58       any here-doc content is not included in "content", and as such you
59       should not eval or execute the result if it contains any
60       PPI::Token::HereDoc.
61
62       The PPI::Document method "serialize" should be used to stringify a PDOM
63       document into something that can be executed as expected.
64
65       Returns the basic code as a string (excluding here-doc content).
66
67       parent
68
69       Elements themselves are not intended to contain other Elements, that is
70       left to the PPI::Node abstract class, a subclass of "PPI::Element".
71       However, all Elements can be contained within a parent Node.
72
73       If an Element is within a parent Node, the "parent" method returns the
74       Node.
75
76       statement
77
78       For a "PPI::Element" that is contained (at some depth) within a
79       PPI::Statment, the "statement" method will return the first parent
80       Statement object lexically 'above' the Element.
81
82       Returns a PPI::Statement object, which may be the same Element if the
83       Element is itself a PPI::Statement object.
84
85       Returns false if the Element is not within a Statement and is not
86       itself a Statement.
87
88       top
89
90       For a "PPI::Element" that is contained within a PDOM tree, the "top"
91       method will return the top-level Node in the tree. Most of the time
92       this should be a PPI::Document object, however this will not always be
93       so. For example, if a subroutine has been removed from its Document, to
94       be moved to another Document.
95
96       Returns the top-most PDOM object, which may be the same Element, if it
97       is not within any parent PDOM object.
98
99       For an Element that is contained within a PPI::Document object, the
100       "document" method will return the top-level Document for the Element.
101
102       Returns the PPI::Document for this Element, or false if the Element is
103       not contained within a Document.
104
105       next_sibling
106
107       All PPI::Node objects (specifically, our parent Node) contain a number
108       of "PPI::Element" objects. The "next_sibling" method returns the
109       "PPI::Element" immediately after the current one, or false if there is
110       no next sibling.
111
112       snext_sibling
113
114       As per the other 's' methods, the "snext_sibling" method returns the
115       next significant sibling of the "PPI::Element" object.
116
117       Returns a "PPI::Element" object, or false if there is no 'next' signif‐
118       icant sibling.
119
120       previous_sibling
121
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
127       sprevious_sibling
128
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
137       As a support method for higher-order algorithms that deal specifically
138       with tokens and actual Perl content, the "first_token" method finds the
139       first PPI::Token object within or equal to this one.
140
141       That is, if called on a PPI::Node subclass, it will descend until it
142       finds a PPI::Token. If called on a PPI::Token object, it will return
143       the same object.
144
145       Returns a PPI::Token object, or dies on error (which should be
146       extremely rare and only occur if an illegal empty PPI::Statement exists
147       below the current Element somewhere.
148
149       last_token
150
151       As a support method for higher-order algorithms that deal specifically
152       with tokens and actual Perl content, the "last_token" method finds the
153       last PPI::Token object within or equal to this one.
154
155       That is, if called on a PPI::Node subclass, it will descend until it
156       finds a PPI::Token. If called on a PPI::Token object, it will return
157       the itself.
158
159       Returns a PPI::Token object, or dies on error (which should be
160       extremely rare and only occur if an illegal empty PPI::Statement exists
161       below the current Element somewhere.
162
163       next_token
164
165       As a support method for higher-order algorithms that deal specifically
166       with tokens and actual Perl content, the "next_token" method finds the
167       PPI::Token object that is immediately after the current Element, even
168       if it is not within the same parent PPI::Node as the one for which the
169       method is being called.
170
171       Note that this is not defined as a PPI::Token-specific method, because
172       it can be useful to find the next token that is after, say, a
173       PPI::Statement, although obviously it would be useless to want the next
174       token after a PPI::Document.
175
176       Returns a PPI::Token object, or false if there are no more tokens after
177       the Element.
178
179       previous_token
180
181       As a support method for higher-order algorithms that deal specifically
182       with tokens and actual Perl content, the "previous_token" method finds
183       the PPI::Token object that is immediately before the current Element,
184       even if it is not within the same parent PPI::Node as this one.
185
186       Note that this is not defined as a PPI::Token-only method, because it
187       can be useful to find the token is before, say, a PPI::Statement,
188       although obviously it would be useless to want the next token before a
189       PPI::Document.
190
191       Returns a PPI::Token object, or false if there are no more tokens
192       before the "Element".
193
194       clone
195
196       As per the Clone module, the "clone" method makes a perfect copy of an
197       Element object. In the generic case, the implementation is done using
198       the Clone module's mechanism itself. In higher-order cases, such as for
199       Nodes, there is more work involved to keep the parent-child links
200       intact.
201
202       insert_before @Elements
203
204       The "insert_before" method allows you to insert lexical perl content,
205       in the form of "PPI::Element" objects, before the calling "Element".
206       You need to be very careful when modifying perl code, as it's easy to
207       break things.
208
209       In its initial incarnation, this method allows you to insert a single
210       Element, and will perform some basic checking to prevent you inserting
211       something that would be structurally wrong (in PDOM terms).
212
213       In future, this method may be enhanced to allow the insertion of multi‐
214       ple Elements, inline-parsed code strings or PPI::Document::Fragment
215       objects.
216
217       Returns true if the Element was inserted, false if it can not be
218       inserted, or "undef" if you do not provide a PPI::Element object as a
219       parameter.
220
221       insert_after @Elements
222
223       The "insert_after" method allows you to insert lexical perl content, in
224       the form of "PPI::Element" objects, after the calling "Element". You
225       need to be very careful when modifying perl code, as it's easy to break
226       things.
227
228       In its initial incarnation, this method allows you to insert a single
229       Element, and will perform some basic checking to prevent you inserting
230       something that would be structurally wrong (in PDOM terms).
231
232       In future, this method may be enhanced to allow the insertion of multi‐
233       ple Elements, inline-parsed code strings or PPI::Document::Fragment
234       objects.
235
236       Returns true if the Element was inserted, false if it can not be
237       inserted, or "undef" if you do not provide a PPI::Element object as a
238       parameter.
239
240       remove
241
242       For a given "PPI::Element", the "remove" method will remove it from its
243       parent intact, along with all of its children.
244
245       Returns the "Element" itself as a convenience, or "undef" if an error
246       occurs while trying to remove the "Element".
247
248       delete
249
250       For a given "PPI::Element", the "remove" method will remove it from its
251       parent, immediately deleting the "Element" and all of its children (if
252       it has any).
253
254       Returns true if the "Element" was successfully deleted, or "undef" if
255       an error occurs while trying to remove the "Element".
256
257       replace $Element
258
259       Although some higher level class support more exotic forms of replace,
260       at the basic level the "replace" method takes a single "Element" as an
261       argument and replaces the current "Element" with it.
262
263       To prevent accidental damage to code, in this initial implementation
264       the replacement element must be of the same class (or a subclass) as
265       the one being replaced.
266
267       location
268
269       If the Element exists within a PPI::Document that has indexed the Ele‐
270       ment locations using "PPI::Document::index_locations", the "location"
271       method will return the location of the first character of the Element
272       within the Document.
273
274       Returns the location as a reference to a three-element array in the
275       form "[ $line, $rowchar, $col ]". The values are in a human format,
276       with the first character of the file located at "[ 1, 1, 1 ]".
277
278       The second and third numbers are similar, except that the second is the
279       literal horizontal character, and the third is the visual column, tak‐
280       ing into account tabbing.
281
282       Returns "undef" on error, or if the PPI::Document object has not been
283       indexed.
284

TO DO

286       It would be nice if "location" could be used in an ad-hoc manner. That
287       is, if called on an Element within a Document that has not been
288       indexed, it will do a one-off calculation to find the location. It
289       might be very painful if someone started using it a lot, without remem‐
290       bering to index the document, but it would be handy for things that are
291       only likely to use it once, such as error handlers.
292

SUPPORT

294       See the support section in the main module.
295

AUTHOR

297       Adam Kennedy <adamk@cpan.org>
298
300       Copyright 2001 - 2006 Adam Kennedy.
301
302       This program is free software; you can redistribute it and/or modify it
303       under the same terms as Perl itself.
304
305       The full text of the license can be found in the LICENSE file included
306       with this module.
307
308
309
310perl v5.8.8                       2006-09-23                   PPI::Element(3)
Impressum