PPI::Node - Abstract PPI Node class, an Element that can contain other Elements

  PPI::Node
  isa PPI::Element

  # 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::Word->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::Word' );

  # 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 provides 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 CWscope method returns true if the node represents a lexical scope boundary, or false if it does not. The CWadd_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.

Returns true if the PPI::Element was added. Returns CWundef if the Element was already within another Node, or the method is not passed a PPI::Element object.

The CWelements method accesses all child elements structurally within the PPI::Node object. Note that in the base of the PPI::Structure classes, this CWDOES include the brace tokens at either end of the structure.

Returns a list of zero or more PPI::Element objects.

Alternatively, if called in the scalar context, the CWelements method returns a count of the number of elements.

The CWfirst_element method accesses the first element structurally within the PPI::Node object. As for the CWelements method, this does include the brace tokens for PPI::Structure objects.

Returns a PPI::Element object, or CWundef if for some reason the PPI::Node object does not contain any elements.

The CWlast_element method accesses the last element structurally within the PPI::Node object. As for the CWelements method, this does include the brace tokens for PPI::Structure objects.

Returns a PPI::Element object, or CWundef if for some reason the PPI::Node object does not contain any elements.

The CWchildren method accesses all child elements lexically within the PPI::Node object. Note that in the case of the PPI::Structure classes, this does NOT include the brace tokens at either end of the structure.

Returns a list of zero of more PPI::Element objects.

Alternatively, if called in the scalar context, the CWchildren method returns a count of the number of lexical children.

The CWschildren method is really just a convenience, the significant-only variation of the normal CWchildren method.

In list context, returns a list of significant children. In scalar context, returns the number of significant children. The CWchild method accesses a child PPI::Element object by its position within the Node.

Returns a PPI::Element object, or CWundef if there is no child element at that node. The lexical structure of the Perl language ignores 'insignificant' 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 CWschild 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. The CWcontains 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.

Returns true if the PPI::Element is within us, false if not, or CWundef on error. The CWfind 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 (full or shortened), or an anonymous subroutine.

  # Find all single quotes in a Document (which is a Node)
  $Document->find('PPI::Quote::Single');

  # The same thing with a shortened class name
  $Document->find('Quote::Single');

  # Anything more elaborate, we so with the sub
  $Document->find( sub {
        # At the top level of the file...
        $_[1]->parent == $_[0]
        and (
                # ...find all comments and POD
                $_[1]->isa('PPI::Token::Pod')
                or
                $_[1]->isa('PPI::Token::Comment')
        )
  } );

The anonymous subroutine will be passed two arguments, the top-level Node you are searching in and the current Element that the condition is testing. The anonymous subroutine should return a simple true/false value indicating match or no match.

Note that the same wanted logic is used for all methods documented to have a CW\&wanted parameter, as this one does.

The CWfind method returns a reference to an array of PPI::Element objects that match the condition, false (but defined) if no Elements match the condition, or CWundef if you provide a bad condition, or an error occurs during the search process.

In the case of a bad condition, a warning will be emitted as well. If the normal CWfind method is like a grep, then CWfind_first is equivalent to the Scalar::Util CWfirst function.

Given an element class or a wanted function, it will search depth-first through a tree until it finds something that matches the condition, returning the first Element that it encounters.

See the CWfind method for details on the format of the search condition.

Returns the first PPI::Element object that matches the condition, false if nothing matches the condition, or CWundef if given an invalid condition, or an error occurs. The CWfind_any method is a short-circuiting true/false method that behaves like the normal CWfind method, but returns true as soon as it finds any Elements that match the search condition.

See the CWfind 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 CWundef if given an invalid condition, or an error occurs. If passed a PPI::Element object that is a direct child of the Node, the CWremove_element method will remove the Element intact, along with any of its children. As such, this method acts essentially as a lexical 'cut' function. The CWprune method is used to strip PPI::Element objects out of a code tree. The argument is the same as for the CWfind method, either a class name, or an anonymous subroutine which returns true/false. Any Element that matches the class|wanted will be deleted from the code tree, along with any of its children.

The CWprune method returns the number of Element objects that matched and were removed, NOT including the child Elements of those that matched the wanted. This might also be zero, so avoid a simple true/false test on the return false of the CWprune method. It returns CWundef on error, which you probably SHOULD test for.

- Move as much as possible to PPI::XS

See the support section in the main module

Adam Kennedy (Maintainer), <http://ali.as/>, cpan@ali.as

Copyright (c) 2004 - 2005 Adam Kennedy. All rights reserved.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

The full text of the license can be found in the LICENSE file included with this module.