NAME
PPI::Element - The abstract Element class, a base for all source objects
INHERITANCE
PPI::Base
\--> PPI::ElementDESCRIPTION
The abstract PPI::Element serves as a base class for all source-related objects, from a single whitespace token to an entire document. It provides a basic set of methods to provide a common interface and basic implementations.
METHODS
significant
Because we treat whitespace and other non-code items as tokens (in order to be able to "round trip" the PPI::Document back to a file) the significant allows us to distinguish between tokens that form a part of the code, and tokens that arn't significant, such as whitespace, POD, or the portion of a file after the __END__ token.
tokens
The tokens method returns a flat list of PPI::Token object for the PPI::Element, essentially undoing the lexing of the document.
content
For ANY PPI::element, the content method will reconstitute the raw source code for it as a single string.
Returns the code as a string, or undef on error.
parent
Elements themselves are not intended to contain other elements, that is left to the PPI::Node abstract class, a subclass of PPI::Element. However, all elements can be contained within a higher ::Node object.
If an ::Element object is within a ::Node, the parent method returns the patent ::Node object.
top
For an PPI::Element that is contained within other ::Elements, the top method will return the top-level ::Element in the tree that this is part of.
Returns the top-most PPI::Element object, which may be the same PPI::Element if it is not within any other ::Elements.
For a PPI::Element that is contained within a PPI::Document object, the top method will return the top-level Document for the Element.
Returns the PPI::Document for this Element, or false if the Element is not contained within a Document.
next_sibling
All ::Node objects contain a number of ::Elements. The next_sibling method returns the ::Element immediately after it, false if there is no next ::Element, or undef if the ::Element does not have a parent ::Node, or some other error occurs.
previous_sibling
All ::Node objects contain a number of ::Elements. The previous_sibling method returns the ::Element immediately before it, false if there is no previous ::Element, or undef if the ::Element does not have a parent ::Node, or some other error occurs.
clone
As per the Clone module, the clone method makes a perfect copy of an Element object. In the generic case, the implemtation if done using the Clone module's mechanism itself.
remove
For a given PPI::Element, the remove method will remove it from it's parent INTACT, along with all of it's children.
Returns the Element itself as a convenience, or undef if an error occurs while trying to remove the Element.
delete
For a given PPI::Element, the remove method will remove it from it's parent, deleting the Element and all of it's children.
Returns true if the Element was successfully deleted, or undef if an error occurs while trying to remove the Element.
location
If the Element exists within a PPI::Document that has indexed the Element locations, the location method will return the location of the Element.
Returns the location as a reference to a two-element array in the form [ $line, $col ]. The values are in a human format, with the first character of the file located at [ 1, 1 ]. Returns undef on error, or if the PPI::Document object has not been indexed.
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 146:
=cut found outside a pod block. Skipping to next block.