local-lib5/man/man3/PPI::Node.3pm

   1 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.10)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 'br\}
  42 .\"
  43 .\" Escape single quotes in literal strings from groff's Unicode transform.
  44 .ie \n(.g .ds Aq \(aq
  45 .el       .ds Aq '
  46 .\"
  47 .\" If the F register is turned on, we'll generate index entries on stderr for
  48 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  49 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  50 .\" output yourself in some meaningful fashion.
  51 .ie \nF \{\
  52 .    de IX
  53 .    tm Index:\\$1\t\\n%\t"\\$2"
  54 ..
  55 .    nr % 0
  56 .    rr F
  57 .\}
  58 .el \{\
  59 .    de IX
  60 ..
  61 .\}
  62 .\"
  63 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  64 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  65 .    \" fudge factors for nroff and troff
  66 .if n \{\
  67 .    ds #H 0
  68 .    ds #V .8m
  69 .    ds #F .3m
  70 .    ds #[ \f1
  71 .    ds #] \fP
  72 .\}
  73 .if t \{\
  74 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  75 .    ds #V .6m
  76 .    ds #F 0
  77 .    ds #[ \&
  78 .    ds #] \&
  79 .\}
  80 .    \" simple accents for nroff and troff
  81 .if n \{\
  82 .    ds ' \&
  83 .    ds ` \&
  84 .    ds ^ \&
  85 .    ds , \&
  86 .    ds ~ ~
  87 .    ds /
  88 .\}
  89 .if t \{\
  90 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  91 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  92 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  93 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  94 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
  95 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
  96 .\}
  97 .    \" troff and (daisy-wheel) nroff accents
  98 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
  99 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 100 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 101 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 102 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 103 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 104 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 105 .ds ae a\h'-(\w'a'u*4/10)'e
 106 .ds Ae A\h'-(\w'A'u*4/10)'E
 107 .    \" corrections for vroff
 108 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 109 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 110 .    \" for low resolution devices (crt and lpr)
 111 .if \n(.H>23 .if \n(.V>19 \
 112 \{\
 113 .    ds : e
 114 .    ds 8 ss
 115 .    ds o a
 116 .    ds d- d\h'-1'\(ga
 117 .    ds D- D\h'-1'\(hy
 118 .    ds th \o'bp'
 119 .    ds Th \o'LP'
 120 .    ds ae ae
 121 .    ds Ae AE
 122 .\}
 123 .rm #[ #] #H #V #F C
 124 .\" ========================================================================
 125 .\"
 126 .IX Title "PPI::Node 3"
 127 .TH PPI::Node 3 "2009-08-08" "perl v5.8.7" "User Contributed Perl Documentation"
 128 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 129 .\" way too many mistakes in technical documents.
 130 .if n .ad l
 131 .nh
 132 .SH "NAME"
 133 PPI::Node \- Abstract PPI Node class, an Element that can contain other Elements
 134 .SH "INHERITANCE"
 135 .IX Header "INHERITANCE"
 136 .Vb 2
 137 \&  PPI::Node
 138 \&  isa PPI::Element
 139 .Ve
 140 .SH "SYNOPSIS"
 141 .IX Header "SYNOPSIS"
 142 .Vb 2
 143 \&  # Create a typical node (a Document in this case)
 144 \&  my $Node = PPI::Document\->new;
 145 \&
 146 \&  # Add an element to the node( in this case, a token )
 147 \&  my $Token = PPI::Token::Word\->new(\*(Aqmy\*(Aq);
 148 \&  $Node\->add_element( $Token );
 149 \&
 150 \&  # Get the elements for the Node
 151 \&  my @elements = $Node\->children;
 152 \&
 153 \&  # Find all the barewords within a Node
 154 \&  my $barewords = $Node\->find( \*(AqPPI::Token::Word\*(Aq );
 155 \&
 156 \&  # Find by more complex criteria
 157 \&  my $my_tokens = $Node\->find( sub { $_[1]\->content eq \*(Aqmy\*(Aq } );
 158 \&
 159 \&  # Remove all the whitespace
 160 \&  $Node\->prune( \*(AqPPI::Token::Whitespace\*(Aq );
 161 \&
 162 \&  # Remove by more complex criteria
 163 \&  $Node\->prune( sub { $_[1]\->content eq \*(Aqmy\*(Aq } );
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 The \f(CW\*(C`PPI::Node\*(C'\fR class provides an abstract base class for the Element
 168 classes that are able to contain other elements PPI::Document,
 169 PPI::Statement, and PPI::Structure.
 170 .PP
 171 As well as those listed below, all of the methods that apply to
 172 PPI::Element objects also apply to \f(CW\*(C`PPI::Node\*(C'\fR objects.
 173 .SH "METHODS"
 174 .IX Header "METHODS"
 175 .SS "scope"
 176 .IX Subsection "scope"
 177 The \f(CW\*(C`scope\*(C'\fR method returns true if the node represents a lexical scope
 178 boundary, or false if it does not.
 179 .ie n .SS "add_element $Element"
 180 .el .SS "add_element \f(CW$Element\fP"
 181 .IX Subsection "add_element $Element"
 182 The \f(CW\*(C`add_element\*(C'\fR method adds a PPI::Element object to the end of a
 183 \&\f(CW\*(C`PPI::Node\*(C'\fR. Because Elements maintain links to their parent, an
 184 Element can only be added to a single Node.
 185 .PP
 186 Returns true if the PPI::Element was added. Returns \f(CW\*(C`undef\*(C'\fR if the
 187 Element was already within another Node, or the method is not passed
 188 a PPI::Element object.
 189 .SS "elements"
 190 .IX Subsection "elements"
 191 The \f(CW\*(C`elements\*(C'\fR method accesses all child elements \fBstructurally\fR within
 192 the \f(CW\*(C`PPI::Node\*(C'\fR object. Note that in the base of the PPI::Structure
 193 classes, this \f(CW\*(C`DOES\*(C'\fR include the brace tokens at either end of the
 194 structure.
 195 .PP
 196 Returns a list of zero or more PPI::Element objects.
 197 .PP
 198 Alternatively, if called in the scalar context, the \f(CW\*(C`elements\*(C'\fR method
 199 returns a count of the number of elements.
 200 .SS "first_element"
 201 .IX Subsection "first_element"
 202 The \f(CW\*(C`first_element\*(C'\fR method accesses the first element structurally within
 203 the \f(CW\*(C`PPI::Node\*(C'\fR object. As for the \f(CW\*(C`elements\*(C'\fR method, this does include
 204 the brace tokens for PPI::Structure objects.
 205 .PP
 206 Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if for some reason the
 207 \&\f(CW\*(C`PPI::Node\*(C'\fR object does not contain any elements.
 208 .SS "last_element"
 209 .IX Subsection "last_element"
 210 The \f(CW\*(C`last_element\*(C'\fR method accesses the last element structurally within
 211 the \f(CW\*(C`PPI::Node\*(C'\fR object. As for the \f(CW\*(C`elements\*(C'\fR method, this does include
 212 the brace tokens for PPI::Structure objects.
 213 .PP
 214 Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if for some reason the
 215 \&\f(CW\*(C`PPI::Node\*(C'\fR object does not contain any elements.
 216 .SS "children"
 217 .IX Subsection "children"
 218 The \f(CW\*(C`children\*(C'\fR method accesses all child elements lexically within the
 219 \&\f(CW\*(C`PPI::Node\*(C'\fR object. Note that in the case of the PPI::Structure
 220 classes, this does \fB\s-1NOT\s0\fR include the brace tokens at either end of the
 221 structure.
 222 .PP
 223 Returns a list of zero of more PPI::Element objects.
 224 .PP
 225 Alternatively, if called in the scalar context, the \f(CW\*(C`children\*(C'\fR method
 226 returns a count of the number of lexical children.
 227 .SS "schildren"
 228 .IX Subsection "schildren"
 229 The \f(CW\*(C`schildren\*(C'\fR method is really just a convenience, the significant-only
 230 variation of the normal \f(CW\*(C`children\*(C'\fR method.
 231 .PP
 232 In list context, returns a list of significant children. In scalar context,
 233 returns the number of significant children.
 234 .ie n .SS "child $index"
 235 .el .SS "child \f(CW$index\fP"
 236 .IX Subsection "child $index"
 237 The \f(CW\*(C`child\*(C'\fR method accesses a child PPI::Element object by its
 238 position within the Node.
 239 .PP
 240 Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if there is no child
 241 element at that node.
 242 .ie n .SS "schild $index"
 243 .el .SS "schild \f(CW$index\fP"
 244 .IX Subsection "schild $index"
 245 The lexical structure of the Perl language ignores 'insignificant' items,
 246 such as whitespace and comments, while \s-1PPI\s0 treats these items as valid
 247 tokens so that it can reassemble the file at any time. Because of this,
 248 in many situations there is a need to find an Element within a Node by
 249 index, only counting lexically significant Elements.
 250 .PP
 251 The \f(CW\*(C`schild\*(C'\fR method returns a child Element by index, ignoring
 252 insignificant Elements. The index of a child Element is specified in the
 253 same way as for a normal array, with the first Element at index 0, and
 254 negative indexes used to identify a \*(L"from the end\*(R" position.
 255 .ie n .SS "contains $Element"
 256 .el .SS "contains \f(CW$Element\fP"
 257 .IX Subsection "contains $Element"
 258 The \f(CW\*(C`contains\*(C'\fR method is used to determine if another PPI::Element
 259 object is logically \*(L"within\*(R" a \f(CW\*(C`PPI::Node\*(C'\fR. For the special case of the
 260 brace tokens at either side of a PPI::Structure object, they are
 261 generally considered \*(L"within\*(R" a PPI::Structure object, even if they are
 262 not actually in the elements for the PPI::Structure.
 263 .PP
 264 Returns true if the PPI::Element is within us, false if not, or \f(CW\*(C`undef\*(C'\fR
 265 on error.
 266 .ie n .SS "find $class | \e&wanted"
 267 .el .SS "find \f(CW$class\fP | \e&wanted"
 268 .IX Subsection "find $class | &wanted"
 269 The \f(CW\*(C`find\*(C'\fR method is used to search within a code tree for
 270 PPI::Element objects that meet a particular condition.
 271 .PP
 272 To specify the condition, the method can be provided with either a simple
 273 class name (full or shortened), or a \f(CW\*(C`CODE\*(C'\fR/function reference.
 274 .PP
 275 .Vb 2
 276 \&  # Find all single quotes in a Document (which is a Node)
 277 \&  $Document\->find(\*(AqPPI::Quote::Single\*(Aq);
 278 \&
 279 \&  # The same thing with a shortened class name
 280 \&  $Document\->find(\*(AqQuote::Single\*(Aq);
 281 \&
 282 \&  # Anything more elaborate, we so with the sub
 283 \&  $Document\->find( sub {
 284 \&        # At the top level of the file...
 285 \&        $_[1]\->parent == $_[0]
 286 \&        and (
 287 \&                # ...find all comments and POD
 288 \&                $_[1]\->isa(\*(AqPPI::Token::Pod\*(Aq)
 289 \&                or
 290 \&                $_[1]\->isa(\*(AqPPI::Token::Comment\*(Aq)
 291 \&        )
 292 \&  } );
 293 .Ve
 294 .PP
 295 The function will be passed two arguments, the top-level \f(CW\*(C`PPI::Node\*(C'\fR
 296 you are searching in and the current PPI::Element that the condition
 297 is testing.
 298 .PP
 299 The anonymous function should return one of three values. Returning true
 300 indicates a condition match, defined-false (\f(CW0\fR or \f(CW\*(Aq\*(Aq\fR) indicates
 301 no-match, and \f(CW\*(C`undef\*(C'\fR indicates no-match and no-descend.
 302 .PP
 303 In the last case, the tree walker will skip over anything below the
 304 \&\f(CW\*(C`undef\*(C'\fR\-returning element and move on to the next element at the same
 305 level.
 306 .PP
 307 To halt the entire search and return \f(CW\*(C`undef\*(C'\fR immediately, a condition
 308 function should throw an exception (i.e. \f(CW\*(C`die\*(C'\fR).
 309 .PP
 310 Note that this same wanted logic is used for all methods documented to
 311 have a \f(CW\*(C`\e&wanted\*(C'\fR parameter, as this one does.
 312 .PP
 313 The \f(CW\*(C`find\*(C'\fR method returns a reference to an array of PPI::Element
 314 objects that match the condition, false (but defined) if no Elements match
 315 the condition, or \f(CW\*(C`undef\*(C'\fR if you provide a bad condition, or an error
 316 occurs during the search process.
 317 .PP
 318 In the case of a bad condition, a warning will be emitted as well.
 319 .ie n .SS "find_first $class | \e&wanted"
 320 .el .SS "find_first \f(CW$class\fP | \e&wanted"
 321 .IX Subsection "find_first $class | &wanted"
 322 If the normal \f(CW\*(C`find\*(C'\fR method is like a grep, then \f(CW\*(C`find_first\*(C'\fR is
 323 equivalent to the Scalar::Util \f(CW\*(C`first\*(C'\fR function.
 324 .PP
 325 Given an element class or a wanted function, it will search depth-first
 326 through a tree until it finds something that matches the condition,
 327 returning the first Element that it encounters.
 328 .PP
 329 See the \f(CW\*(C`find\*(C'\fR method for details on the format of the search condition.
 330 .PP
 331 Returns the first PPI::Element object that matches the condition, false
 332 if nothing matches the condition, or \f(CW\*(C`undef\*(C'\fR if given an invalid condition,
 333 or an error occurs.
 334 .ie n .SS "find_any $class | \e&wanted"
 335 .el .SS "find_any \f(CW$class\fP | \e&wanted"
 336 .IX Subsection "find_any $class | &wanted"
 337 The \f(CW\*(C`find_any\*(C'\fR method is a short-circuiting true/false method that behaves
 338 like the normal \f(CW\*(C`find\*(C'\fR method, but returns true as soon as it finds any
 339 Elements that match the search condition.
 340 .PP
 341 See the \f(CW\*(C`find\*(C'\fR method for details on the format of the search condition.
 342 .PP
 343 Returns true if any Elements that match the condition can be found, false if
 344 not, or \f(CW\*(C`undef\*(C'\fR if given an invalid condition, or an error occurs.
 345 .ie n .SS "remove_child $Element"
 346 .el .SS "remove_child \f(CW$Element\fP"
 347 .IX Subsection "remove_child $Element"
 348 If passed a PPI::Element object that is a direct child of the Node,
 349 the \f(CW\*(C`remove_element\*(C'\fR method will remove the \f(CW\*(C`Element\*(C'\fR intact, along
 350 with any of its children. As such, this method acts essentially as a
 351 \&'cut' function.
 352 .PP
 353 If successful, returns the removed element.  Otherwise, returns \f(CW\*(C`undef\*(C'\fR.
 354 .ie n .SS "prune $class | \e&wanted"
 355 .el .SS "prune \f(CW$class\fP | \e&wanted"
 356 .IX Subsection "prune $class | &wanted"
 357 The \f(CW\*(C`prune\*(C'\fR method is used to strip PPI::Element objects out of a code
 358 tree. The argument is the same as for the \f(CW\*(C`find\*(C'\fR method, either a class
 359 name, or an anonymous subroutine which returns true/false. Any Element
 360 that matches the class|wanted will be deleted from the code tree, along
 361 with any of its children.
 362 .PP
 363 The \f(CW\*(C`prune\*(C'\fR method returns the number of \f(CW\*(C`Element\*(C'\fR objects that matched
 364 and were removed, \fBnon-recursively\fR. This might also be zero, so avoid a
 365 simple true/false test on the return false of the \f(CW\*(C`prune\*(C'\fR method. It
 366 returns \f(CW\*(C`undef\*(C'\fR on error, which you probably \fBshould\fR test for.
 367 .SH "TO DO"
 368 .IX Header "TO DO"
 369 \&\- Move as much as possible to \s-1PPI::XS\s0
 370 .SH "SUPPORT"
 371 .IX Header "SUPPORT"
 372 See the support section in the main module.
 373 .SH "AUTHOR"
 374 .IX Header "AUTHOR"
 375 Adam Kennedy <adamk@cpan.org>
 376 .SH "COPYRIGHT"
 377 .IX Header "COPYRIGHT"
 378 Copyright 2001 \- 2009 Adam Kennedy.
 379 .PP
 380 This program is free software; you can redistribute
 381 it and/or modify it under the same terms as Perl itself.
 382 .PP
 383 The full text of the license can be found in the
 384 \&\s-1LICENSE\s0 file included with this module.