PPI::Node - Abstract PPI Node class, an Element that can contain other Elements
PPI::Base \--> PPI::Element \--> PPI::Node
# Create a typical node (a Document in this case) my $Node = PPI::Document->new; # Add an element to the node( in this case, a token ) my $Token = PPI::Token::Bareword->new('my'); $Node->add_element( $Token ); # Get the elements for the Node my @elements = $Node->children; # Find all the barewords within a Node my @barewords = $Node->find( 'PPI::Token::Bareword' ); # Find by more complex criteria my @my_tokens = $Node->find( sub { $_[1]->content eq 'my' } ); # Remove all the whitespace $Node->prune( 'PPI::Token::Whitespace' ); # Remove by more complex criteria $Node->prune( sub { $_[1]->content eq 'my' } );
The PPI::Node class privides an abstract base class for the Element classes that are able to contain other elements, PPI::Document, PPI::Statement, and PPI::Structure.
As well as those listed below, all of the methods that apply to PPI::Element objects also apply to PPI::Node objects.
The add_element method adds a PPI::Element object to the end of a PPI::Node. Because Elements maintain links to their parent, an Element can only be added to a single Node.
add_element
Returns true if the PPI::Element was added. Returns undef if the Element was already within another Node, or the method is not passed a PPI::Element object.
undef
The children method accesses all child elements lexically within the PPI::Node object. Note that in the case of the PPI::Structure class, this does NOT include the brace tokens at either end of the structure.
children
Returns a list of zero of more PPI::Element objects.
Alternatively, if called in the scalar context, the children method returns a count of the number of child elements.
The child method accesses a child PPI::Element object by it's position within the Node.
child
Returns a PPI::Element object, or undef if there is no child element at that node.
The lexical structure of the Perl language ignores 'insignifcant' items, such as whitespace and comments, while PPI treats these items as valid tokens so that it can reassemble the file at any time. Because of this, in many situations there is a need to find an Element within a Node by index, only counting lexically significant Elements.
The schild method returns a child Element by index, ignoring insignificant Elements. The index of a child Element is specified in the same way as for a normal array, with the first Element at index 0, and negative indexes used to identify a "from the end" position.
schild
The contains method is used to determine if another PPI::Element object is logically "within" a PPI::Node. For the special case of the brace tokens at either side of a PPI::Structure object, they are generally considered "within" a PPI::Structure object, even if they are not actually in the elements for the PPI::Structure.
contains
Returns true if the PPI::Element is within us, false if not, or undef on error.
The find method is used to search within a code tree for PPI::Element objects that meet a particular condition. To specify the condition, the method can be provided with either a simple class name, or an anonymous subroutine.
find
The anonymous subroutine will be passed two arguments, the top-level Node being searched within and the current Element that the condition is testing. The anonymous subroutine should return a simple true/false value incating match or no match.
The find method returns a reference to an array of PPI::Element object that match the condition, false if no Elements match the condition, or undef if an error occurs during the search process.
The find_any is a short-circuiting true/false method that behaves like the normal find method, but returns true as soon as it finds any Elements that match the search condition.
find_any
See the find method for details on the format of the search condition.
Returns true if any Elements that match the condition can be found, false if not, or undef if given an invalid condition, or an error occurs.
If passed a PPI::Element object that is a direct child of the Node, the remove_element method will remove the Element intact, along with any of it's children. As such, this method acts essentially as a lexical 'cut' function.
remove_element
The prune method is used to strip PPI::Element objects out of a code tree. The argument is the same as for the find method, either a class name, or an anonymous subroutine which returns true/false. Any Element that matches the class|condition will be deleted from the code tree, along with any of it's children.
prune
The prune method returns the number of Element objects that matched and were removed, NOT including the child Elements of those that matched the condition. This might also be zero, so avoid a simple true/false test on the return false of the prune method. It returns undef on error, which you probably SHOULD test for.
To install PPI, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PPI
CPAN shell
perl -MCPAN -e shell install PPI
For more information on module installation, please visit the detailed CPAN module installation guide.