.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "PPI::Node 3pm"
.TH PPI::Node 3pm 2024-03-16 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
PPI::Node \- Abstract PPI Node class, an Element that can contain other Elements
.SH INHERITANCE
.IX Header "INHERITANCE"
.Vb 2
\&  PPI::Node
\&  isa PPI::Element
.Ve
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  # 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(\*(Aqmy\*(Aq);
\&  $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( \*(AqPPI::Token::Word\*(Aq );
\&  
\&  # Find by more complex criteria
\&  my $my_tokens = $Node\->find( sub { $_[1]\->content eq \*(Aqmy\*(Aq } );
\&  
\&  # Remove all the whitespace
\&  $Node\->prune( \*(AqPPI::Token::Whitespace\*(Aq );
\&  
\&  # Remove by more complex criteria
\&  $Node\->prune( sub { $_[1]\->content eq \*(Aqmy\*(Aq } );
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \f(CW\*(C`PPI::Node\*(C'\fR class provides an abstract base class for the Element
classes that are able to contain other elements PPI::Document,
PPI::Statement, and PPI::Structure.
.PP
As well as those listed below, all of the methods that apply to
PPI::Element objects also apply to \f(CW\*(C`PPI::Node\*(C'\fR objects.
.SH METHODS
.IX Header "METHODS"
.SS scope
.IX Subsection "scope"
The \f(CW\*(C`scope\*(C'\fR method returns true if the node represents a lexical scope
boundary, or false if it does not.
.ie n .SS "add_element $Element"
.el .SS "add_element \f(CW$Element\fP"
.IX Subsection "add_element $Element"
The \f(CW\*(C`add_element\*(C'\fR method adds a PPI::Element object to the end of a
\&\f(CW\*(C`PPI::Node\*(C'\fR. Because Elements maintain links to their parent, an
Element can only be added to a single Node.
.PP
Returns true if the PPI::Element was added. Returns \f(CW\*(C`undef\*(C'\fR if the
Element was already within another Node, or the method is not passed 
a PPI::Element object.
.SS elements
.IX Subsection "elements"
The \f(CW\*(C`elements\*(C'\fR method accesses all child elements \fBstructurally\fR within
the \f(CW\*(C`PPI::Node\*(C'\fR object. Note that in the base of the PPI::Structure
classes, this \f(CW\*(C`DOES\*(C'\fR include the brace tokens at either end of the
structure.
.PP
Returns a list of zero or more PPI::Element objects.
.PP
Alternatively, if called in the scalar context, the \f(CW\*(C`elements\*(C'\fR method
returns a count of the number of elements.
.SS first_element
.IX Subsection "first_element"
The \f(CW\*(C`first_element\*(C'\fR method accesses the first element structurally within
the \f(CW\*(C`PPI::Node\*(C'\fR object. As for the \f(CW\*(C`elements\*(C'\fR method, this does include
the brace tokens for PPI::Structure objects.
.PP
Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if for some reason the
\&\f(CW\*(C`PPI::Node\*(C'\fR object does not contain any elements.
.SS last_element
.IX Subsection "last_element"
The \f(CW\*(C`last_element\*(C'\fR method accesses the last element structurally within
the \f(CW\*(C`PPI::Node\*(C'\fR object. As for the \f(CW\*(C`elements\*(C'\fR method, this does include
the brace tokens for PPI::Structure objects.
.PP
Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if for some reason the
\&\f(CW\*(C`PPI::Node\*(C'\fR object does not contain any elements.
.SS children
.IX Subsection "children"
The \f(CW\*(C`children\*(C'\fR method accesses all child elements lexically within the
\&\f(CW\*(C`PPI::Node\*(C'\fR object. Note that in the case of the PPI::Structure
classes, this does \fBNOT\fR include the brace tokens at either end of the
structure.
.PP
Returns a list of zero of more PPI::Element objects.
.PP
Alternatively, if called in the scalar context, the \f(CW\*(C`children\*(C'\fR method
returns a count of the number of lexical children.
.SS schildren
.IX Subsection "schildren"
The \f(CW\*(C`schildren\*(C'\fR method is really just a convenience, the significant-only
variation of the normal \f(CW\*(C`children\*(C'\fR method.
.PP
In list context, returns a list of significant children. In scalar context,
returns the number of significant children.
.ie n .SS "child $index"
.el .SS "child \f(CW$index\fP"
.IX Subsection "child $index"
The \f(CW\*(C`child\*(C'\fR method accesses a child PPI::Element object by its
position within the Node.
.PP
Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if there is no child
element at that node.
.ie n .SS "schild $index"
.el .SS "schild \f(CW$index\fP"
.IX Subsection "schild $index"
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.
.PP
The \f(CW\*(C`schild\*(C'\fR 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.
.ie n .SS "contains $Element"
.el .SS "contains \f(CW$Element\fP"
.IX Subsection "contains $Element"
The \f(CW\*(C`contains\*(C'\fR method is used to determine if another PPI::Element
object is logically "within" a \f(CW\*(C`PPI::Node\*(C'\fR. 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.
.PP
Returns true if the PPI::Element is within us, false if not, or \f(CW\*(C`undef\*(C'\fR
on error.
.ie n .SS "find $class | \e&wanted"
.el .SS "find \f(CW$class\fP | \e&wanted"
.IX Subsection "find $class | &wanted"
The \f(CW\*(C`find\*(C'\fR method is used to search within a code tree for
PPI::Element objects that meet a particular condition.
.PP
To specify the condition, the method can be provided with either a simple
class name (full or shortened), or a \f(CW\*(C`CODE\*(C'\fR/function reference.
.PP
.Vb 2
\&  # Find all single quotes in a Document (which is a Node)
\&  $Document\->find(\*(AqPPI::Quote::Single\*(Aq);
\&  
\&  # The same thing with a shortened class name
\&  $Document\->find(\*(AqQuote::Single\*(Aq);
\&  
\&  # Anything more elaborate, we go with the sub
\&  $Document\->find( sub {
\&        # At the top level of the file...
\&        $_[1]\->parent == $_[0]
\&        and (
\&                # ...find all comments and POD
\&                $_[1]\->isa(\*(AqPPI::Token::Pod\*(Aq)
\&                or
\&                $_[1]\->isa(\*(AqPPI::Token::Comment\*(Aq)
\&        )
\&  } );
.Ve
.PP
The function will be passed two arguments, the top-level \f(CW\*(C`PPI::Node\*(C'\fR
you are searching in and the current PPI::Element that the condition
is testing.
.PP
The anonymous function should return one of three values. Returning true
indicates a condition match, defined-false (\f(CW0\fR or \f(CW\*(Aq\*(Aq\fR) indicates
no-match, and \f(CW\*(C`undef\*(C'\fR indicates no-match and no-descend.
.PP
In the last case, the tree walker will skip over anything below the
\&\f(CW\*(C`undef\*(C'\fR\-returning element and move on to the next element at the same
level.
.PP
To halt the entire search and return \f(CW\*(C`undef\*(C'\fR immediately, a condition
function should throw an exception (i.e. \f(CW\*(C`die\*(C'\fR).
.PP
Note that this same wanted logic is used for all methods documented to
have a \f(CW\*(C`\e&wanted\*(C'\fR parameter, as this one does.
.PP
The \f(CW\*(C`find\*(C'\fR 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 \f(CW\*(C`undef\*(C'\fR if you provide a bad condition, or an error
occurs during the search process.
.PP
In the case of a bad condition, a warning will be emitted as well.
.ie n .SS "find_first $class | \e&wanted"
.el .SS "find_first \f(CW$class\fP | \e&wanted"
.IX Subsection "find_first $class | &wanted"
If the normal \f(CW\*(C`find\*(C'\fR method is like a grep, then \f(CW\*(C`find_first\*(C'\fR is
equivalent to the List::Util \f(CW\*(C`first\*(C'\fR function.
.PP
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.
.PP
See the \f(CW\*(C`find\*(C'\fR method for details on the format of the search condition.
.PP
Returns the first PPI::Element object that matches the condition, false
if nothing matches the condition, or \f(CW\*(C`undef\*(C'\fR if given an invalid condition,
or an error occurs.
.ie n .SS "find_any $class | \e&wanted"
.el .SS "find_any \f(CW$class\fP | \e&wanted"
.IX Subsection "find_any $class | &wanted"
The \f(CW\*(C`find_any\*(C'\fR method is a short-circuiting true/false method that behaves
like the normal \f(CW\*(C`find\*(C'\fR method, but returns true as soon as it finds any
Elements that match the search condition.
.PP
See the \f(CW\*(C`find\*(C'\fR method for details on the format of the search condition.
.PP
Returns true if any Elements that match the condition can be found, false if
not, or \f(CW\*(C`undef\*(C'\fR if given an invalid condition, or an error occurs.
.ie n .SS "remove_child $Element"
.el .SS "remove_child \f(CW$Element\fP"
.IX Subsection "remove_child $Element"
If passed a PPI::Element object that is a direct child of the Node,
the \f(CW\*(C`remove_element\*(C'\fR method will remove the \f(CW\*(C`Element\*(C'\fR intact, along
with any of its children. As such, this method acts essentially as a
\&'cut' function.
.PP
If successful, returns the removed element.  Otherwise, returns \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "replace_child $Element, $Replacement"
.el .SS "replace_child \f(CW$Element\fP, \f(CW$Replacement\fP"
.IX Subsection "replace_child $Element, $Replacement"
If successful, returns the replace element.  Otherwise, returns \f(CW\*(C`undef\*(C'\fR.
.ie n .SS "prune $class | \e&wanted"
.el .SS "prune \f(CW$class\fP | \e&wanted"
.IX Subsection "prune $class | &wanted"
The \f(CW\*(C`prune\*(C'\fR method is used to strip PPI::Element objects out of a code
tree. The argument is the same as for the \f(CW\*(C`find\*(C'\fR 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.
.PP
The \f(CW\*(C`prune\*(C'\fR method returns the number of \f(CW\*(C`Element\*(C'\fR objects that matched
and were removed, \fBnon-recursively\fR. This might also be zero, so avoid a
simple true/false test on the return false of the \f(CW\*(C`prune\*(C'\fR method. It
returns \f(CW\*(C`undef\*(C'\fR on error, which you probably \fBshould\fR test for.
.SH "TO DO"
.IX Header "TO DO"
\&\- Move as much as possible to PPI::XS
.SH SUPPORT
.IX Header "SUPPORT"
See the support section in the main module.
.SH AUTHOR
.IX Header "AUTHOR"
Adam Kennedy <adamk@cpan.org>
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2001 \- 2011 Adam Kennedy.
.PP
This program is free software; you can redistribute
it and/or modify it under the same terms as Perl itself.
.PP
The full text of the license can be found in the
LICENSE file included with this module.