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.

statement

For a PPI::Element that is contained (at some depth) within a PPI::Statment, the statement method will return the first parent PPI::Statement object 'above' the PPI::Element.

Returns a PPI::Statement object, which may be the same PPI::Element if the element is itself a PPI::Statement object. Returns false if the Element is not within a PPI::Statement, or is not itself a PPI::Statement.

top

For a 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 PPI::Node objects contain a number of PPI::Elements. The next_sibling method returns the PPI::Element immediately after the current one, or false if there is no next sibling.

snext_sibling

As per the other 's' methods, the snext_sibling method returns the next significant sibling of the PPI::Element object.

Returns a PPI::Element object, or false if there is no 'next' significant sibling.

previous_sibling

All PPI::Node objects contain a number of PPI::Element object. The previous_sibling method returns the PPI::Element immediately before the current one, or false if there is no previous PPI::Element object.

sprevious_sibling

As per the other 's' methods, the sprevious_sibling method returns the previous significant sibling of the PPI::Element object.

Returns a PPI::Element object, or false if there is no 'previous' significant sibling.

next_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the next_token method finds the PPI::Token object that is immediately after the current PPI::Element object, even if it is not within the same parent PPI::Node object as this one.

Note that this is not defined as a PPI::Token-only method, because it can be useful to find the next token that is after, say, a PPI::Statement, although obviously it would be useless to want the next token after a PPI::Document.

Returns a PPI::Token object, or false if there are no more tokens after the PPI::Element.

previous_token

As a support method for higher-order algorithms that deal specifically with tokens and actual Perl content, the previous_token method finds the PPI::Token object that is immediately before the current PPI::Element object, even if it is not within the same parent PPI::Node object as this one.

Note that this is not defined as a PPI::Token-only method, because it can be useful to find the token is before, say, a PPI::Statement, although obviously it would be useless to want the next token before a PPI::Document

Returns a PPI::Token object, or false if there are no more tokens before the PPI::Element.

clone

As per the Clone module, the clone method makes a perfect copy of an Element object. In the generic case, the implementation if done using the Clone module's mechanism itself.

insert_before @Elements

The insert_before method allows you to insert lexical perl content, in the form of PPI::Element objects, before the calling Element. You need to be very careful when modifying perl code, as it's easy to break things.

This method is not yet implemented, mainly due to the difficulty in making it just DWYM.

insert_after @Elements

The insert_after method allows you to insert lexical perl content, in the form of PPI::Element objects, before the calling Element. You need to be very careful when modifying perl code, as it's easy to break things.

This method is not yet implemented, mainly due to the difficulty in making it just DWYM.

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.

cpanm PPI

perl -MCPAN -e shell
install PPI