The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
PPI-0.824
River stage four • 195 direct dependents • 1581 total dependents
58 ++
/ PPI::Element

NAME

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

INHERITANCE

  PPI::Base
  \--> PPI::Element

DESCRIPTION

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.