1MDOM::Element(3) User Contributed Perl Documentation MDOM::Element(3)
2
6 MDOM::Element - The abstract Element class, a base for all source
7 objects
8
10 MDOM::Element is the root of the PDOM tree
11
13 The abstract "MDOM::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 MDOM::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 MDOM::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 "MDOM::Element", the "content" method will reconstitute the
47 base code for it as a single string. This method is also the method
48 used for overloading stringification. When an Element is used in a
49 double-quoted 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 MDOM::Token::HereDoc.
57 The MDOM::Document method "serialize" should be used to stringify a
59 PDOM 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 MDOM::Node abstract class, a subclass of "MDOM::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 statement
72 For a "MDOM::Element" that is contained (at some depth) within a
73 MDOM::Statment, the "statement" method will return the first parent
74 Statement object lexically 'above' the Element.
75 Returns a MDOM::Statement object, which may be the same Element if the
77 Element is itself a MDOM::Statement object.
78 Returns false if the Element is not within a Statement and is not
80 itself a Statement.
81 top
83 For a "MDOM::Element" that is contained within a PDOM tree, the "top"
84 method will return the top-level Node in the tree. Most of the time
85 this should be a MDOM::Document object, however this will not always be
86 so. For example, if a subroutine has been removed from its Document, to
87 be moved to another Document.
88 Returns the top-most PDOM object, which may be the same Element, if it
90 is not within any parent PDOM object.
91 For an Element that is contained within a MDOM::Document object, the
93 "document" method will return the top-level Document for the Element.
94 Returns the MDOM::Document for this Element, or false if the Element is
96 not contained within a Document.
97 next_sibling
99 All MDOM::Node objects (specifically, our parent Node) contain a number
100 of "MDOM::Element" objects. The "next_sibling" method returns the
101 "MDOM::Element" immediately after the current one, or false if there is
102 no next sibling.
103 snext_sibling
105 As per the other 's' methods, the "snext_sibling" method returns the
106 next significant sibling of the "MDOM::Element" object.
107 Returns a "MDOM::Element" object, or false if there is no 'next'
109 significant sibling.
110 previous_sibling
112 All MDOM::Node objects (specifically, our parent Node) contain a number
113 of "MDOM::Element" objects. The "previous_sibling" method returns the
114 Element immediately before the current one, or false if there is no
115 'previous' "MDOM::Element" object.
116 sprevious_sibling
118 As per the other 's' methods, the "sprevious_sibling" method returns
119 the previous significant sibling of the "MDOM::Element" object.
120 Returns a "MDOM::Element" object, or false if there is no 'previous'
122 significant sibling.
123 first_token
125 As a support method for higher-order algorithms that deal specifically
126 with tokens and actual Perl content, the "first_token" method finds the
127 first MDOM::Token object within or equal to this one.
128 That is, if called on a MDOM::Node subclass, it will descend until it
130 finds a MDOM::Token. If called on a MDOM::Token object, it will return
131 the same object.
132 Returns a MDOM::Token object, or dies on error (which should be
134 extremely rare and only occur if an illegal empty MDOM::Statement
135 exists below the current Element somewhere.
136 last_token
138 As a support method for higher-order algorithms that deal specifically
139 with tokens and actual Perl content, the "last_token" method finds the
140 last MDOM::Token object within or equal to this one.
141 That is, if called on a MDOM::Node subclass, it will descend until it
143 finds a MDOM::Token. If called on a MDOM::Token object, it will return
144 the itself.
145 Returns a MDOM::Token object, or dies on error (which should be
147 extremely rare and only occur if an illegal empty MDOM::Statement
148 exists below the current Element somewhere.
149 next_token
151 As a support method for higher-order algorithms that deal specifically
152 with tokens and actual Perl content, the "next_token" method finds the
153 MDOM::Token object that is immediately after the current Element, even
154 if it is not within the same parent MDOM::Node as the one for which the
155 method is being called.
156 Note that this is not defined as a MDOM::Token-specific method, because
158 it can be useful to find the next token that is after, say, a
159 MDOM::Statement, although obviously it would be useless to want the
160 next token after a MDOM::Document.
161 Returns a MDOM::Token object, or false if there are no more tokens
163 after the Element.
164 previous_token
166 As a support method for higher-order algorithms that deal specifically
167 with tokens and actual Perl content, the "previous_token" method finds
168 the MDOM::Token object that is immediately before the current Element,
169 even if it is not within the same parent MDOM::Node as this one.
170 Note that this is not defined as a MDOM::Token-only method, because it
172 can be useful to find the token is before, say, a MDOM::Statement,
173 although obviously it would be useless to want the next token before a
174 MDOM::Document.
175 Returns a MDOM::Token object, or false if there are no more tokens
177 before the "Element".
178 clone
180 As per the Clone module, the "clone" method makes a perfect copy of an
181 Element object. In the generic case, the implementation is done using
182 the Clone module's mechanism itself. In higher-order cases, such as for
183 Nodes, there is more work involved to keep the parent-child links
184 intact.
185 insert_before @Elements
187 The "insert_before" method allows you to insert lexical perl content,
188 in the form of "MDOM::Element" objects, before the calling "Element".
189 You need to be very careful when modifying perl code, as it's easy to
190 break things.
191 In its initial incarnation, this method allows you to insert a single
193 Element, and will perform some basic checking to prevent you inserting
194 something that would be structurally wrong (in PDOM terms).
195 In future, this method may be enhanced to allow the insertion of
197 multiple Elements, inline-parsed code strings or
198 MDOM::Document::Fragment objects.
199 Returns true if the Element was inserted, false if it can not be
201 inserted, or "undef" if you do not provide a MDOM::Element object as a
202 parameter.
203 insert_after @Elements
205 The "insert_after" method allows you to insert lexical perl content, in
206 the form of "MDOM::Element" objects, after the calling "Element". You
207 need to be very careful when modifying perl code, as it's easy to break
208 things.
209 In its initial incarnation, this method allows you to insert a single
211 Element, and will perform some basic checking to prevent you inserting
212 something that would be structurally wrong (in PDOM terms).
213 In future, this method may be enhanced to allow the insertion of
215 multiple Elements, inline-parsed code strings or
216 MDOM::Document::Fragment objects.
217 Returns true if the Element was inserted, false if it can not be
219 inserted, or "undef" if you do not provide a MDOM::Element object as a
220 parameter.
221 remove
223 For a given "MDOM::Element", the "remove" method will remove it from
224 its parent intact, along with all of its children.
225 Returns the "Element" itself as a convenience, or "undef" if an error
227 occurs while trying to remove the "Element".
228 delete
230 For a given "MDOM::Element", the "remove" method will remove it from
231 its parent, immediately deleting the "Element" and all of its children
232 (if it has any).
233 Returns true if the "Element" was successfully deleted, or "undef" if
235 an error occurs while trying to remove the "Element".
236 replace $Element
238 Although some higher level class support more exotic forms of replace,
239 at the basic level the "replace" method takes a single "Element" as an
240 argument and replaces the current "Element" with it.
241 To prevent accidental damage to code, in this initial implementation
243 the replacement element must be of the same class (or a subclass) as
244 the one being replaced.
245 location
247 If the Element exists within a MDOM::Document that has indexed the
248 Element locations using "MDOM::Document::index_locations", the
249 "location" method will return the location of the first character of
250 the Element within the Document.
251 Returns the location as a reference to a three-element array in the
253 form "[ $line, $rowchar, $col ]". The values are in a human format,
254 with the first character of the file located at "[ 1, 1, 1 ]".
255 The second and third numbers are similar, except that the second is the
257 literal horizontal character, and the third is the visual column,
258 taking into account tabbing.
259 Returns "undef" on error, or if the MDOM::Document object has not been
261 indexed.
262
264 It would be nice if "location" could be used in an ad-hoc manner. That
265 is, if called on an Element within a Document that has not been
266 indexed, it will do a one-off calculation to find the location. It
267 might be very painful if someone started using it a lot, without
268 remembering to index the document, but it would be handy for things
269 that are only likely to use it once, such as error handlers.
270
272 See the support section in the main module.
273
275 Adam Kennedy <adamk@cpan.org>
276
278 Copyright 2001 - 2006 Adam Kennedy.
279 This program is free software; you can redistribute it and/or modify it
281 under the same terms as Perl itself.
282 The full text of the license can be found in the LICENSE file included
284 with this module.
285perl v5.12.0 2008-03-10 MDOM::Element(3)