local-lib5/man/man3/PPI::Find.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::Find 3"
 127 .TH PPI::Find 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::Find \- Object version of the Element\->find method
 134 .SH "SYNOPSIS"
 135 .IX Header "SYNOPSIS"
 136 .Vb 2
 137 \&  # Create the Find object
 138 \&  my $Find = PPI::Find\->new( \e&wanted );
 139 \&
 140 \&  # Return all matching Elements as a list
 141 \&  my @found = $Find\->in( $Document );
 142 \&
 143 \&  # Can we find any matching Elements
 144 \&  if ( $Find\->any_matches($Document) ) {
 145 \&        print "Found at least one matching Element";
 146 \&  }
 147 \&
 148 \&  # Use the object as an iterator
 149 \&  $Find\->start($Document) or die "Failed to execute search";
 150 \&  while ( my $token = $Find\->match ) {
 151 \&        ...
 152 \&  }
 153 .Ve
 154 .SH "DESCRIPTION"
 155 .IX Header "DESCRIPTION"
 156 PPI::Find is the primary \s-1PDOM\s0 searching class in the core \s-1PPI\s0 package.
 157 .SS "History"
 158 .IX Subsection "History"
 159 It became quite obvious during the development of \s-1PPI\s0 that many of the
 160 modules that would be built on top of it were going to need large numbers
 161 of saved, storable or easily creatable search objects that could be
 162 reused a number of times.
 163 .PP
 164 Although the internal \->find method provides a basic ability to search,
 165 it is by no means thorough. PPI::Find attempts to resolve this problem.
 166 .SS "Structure and Style"
 167 .IX Subsection "Structure and Style"
 168 PPI::Find provides a similar \s-1API\s0 to the popular File::Find::Rule
 169 module for file searching, but without the ability to assemble queries.
 170 .PP
 171 The implementation of a separate PPI::Find::Rule sub-class that does
 172 provide this ability is left as an exercise for the reader.
 173 .SS "The &wanted function"
 174 .IX Subsection "The &wanted function"
 175 At the core of each PPI::Find object is a \*(L"wanted\*(R" function that is
 176 passed a number of arguments and returns a value which controls the
 177 flow of the search.
 178 .PP
 179 As the search executes, each Element will be passed to the wanted function
 180 in depth-first order.
 181 .PP
 182 It will be provided with two arguments. The current Element to test as \f(CW$_\fR[0],
 183 and the top-level Element of the search as \f(CW$_\fR[1].
 184 .PP
 185 The &wanted function is expected to return 1 (positive) if the Element
 186 matches the condition, 0 (false) if it does not, and undef (undefined) if
 187 the condition does not match, and the Find search should not descend to
 188 any of the current Element's children.
 189 .PP
 190 Errors should be reported from the &wanted function via die, which will be
 191 caught by the Find object and returned as an error.
 192 .SH "METHODS"
 193 .IX Header "METHODS"
 194 .SS "new &wanted"
 195 .IX Subsection "new &wanted"
 196 The \f(CW\*(C`new\*(C'\fR constructor takes a single argument of the &wanted function,
 197 as described above and creates a new search.
 198 .PP
 199 Returns a new PPI::Find object, or \f(CW\*(C`undef\*(C'\fR if not passed a \s-1CODE\s0 reference.
 200 .SS "clone"
 201 .IX Subsection "clone"
 202 The \f(CW\*(C`clone\*(C'\fR method creates another instance of the same Find object.
 203 .PP
 204 The cloning is done safely, so if your existing Find object is in the
 205 middle of an iteration, the cloned Find object will not also be in the
 206 iteration and can be safely used independently.
 207 .PP
 208 Returns a duplicate PPI::Find object.
 209 .ie n .SS "in $Document [, array_ref => 1 ]"
 210 .el .SS "in \f(CW$Document\fP [, array_ref => 1 ]"
 211 .IX Subsection "in $Document [, array_ref => 1 ]"
 212 The \f(CW\*(C`in\*(C'\fR method starts and completes a full run of the search.
 213 .PP
 214 It takes as argument a single PPI::Element object which will
 215 serve as the top of the search process.
 216 .PP
 217 Returns a list of PPI::Element objects that match the condition
 218 described by the &wanted function, or the null list on error.
 219 .PP
 220 You should check the \->errstr method for any errors if you are
 221 returned the null list, which may also mean simply that no Elements
 222 were found that matched the condition.
 223 .PP
 224 Because of this need to explicitly check for errors, an alternative
 225 return value mechanism is provide. If you pass the \f(CW\*(C`array_ref =\*(C'\fR 1>
 226 parameter to the method, it will return the list of matched Elements
 227 as a reference to an \s-1ARRAY\s0. The method will return false if no elements
 228 were matched, or \f(CW\*(C`undef\*(C'\fR on error.
 229 .PP
 230 The \->errstr method can still be used to get the error message as normal.
 231 .ie n .SS "start $Element"
 232 .el .SS "start \f(CW$Element\fP"
 233 .IX Subsection "start $Element"
 234 The \f(CW\*(C`start\*(C'\fR method lets the Find object act as an iterator. The method
 235 is passed the parent PPI::Element object as for the \f(CW\*(C`in\*(C'\fR method, but does
 236 not accept any parameters.
 237 .PP
 238 To simplify error handling, the entire search is done at once, with the
 239 results cached and provided as-requested.
 240 .PP
 241 Returns true if the search completes, and false on error.
 242 .SS "match"
 243 .IX Subsection "match"
 244 The \f(CW\*(C`match\*(C'\fR method returns the next matching Element in the iteration.
 245 .PP
 246 Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if there are no remaining
 247 Elements to be returned.
 248 .SS "finish"
 249 .IX Subsection "finish"
 250 The \f(CW\*(C`finish\*(C'\fR method provides a mechanism to end iteration if you wish to
 251 stop the iteration prematurely. It resets the Find object and allows it to
 252 be safely reused.
 253 .PP
 254 A Find object will be automatically finished when \f(CW\*(C`match\*(C'\fR returns false.
 255 This means you should only need to call \f(CW\*(C`finnish\*(C'\fR when you stop
 256 iterating early.
 257 .PP
 258 You may safely call this method even when not iterating and it will return
 259 without failure.
 260 .PP
 261 Always returns true
 262 .SS "errstr"
 263 .IX Subsection "errstr"
 264 The \f(CW\*(C`errstr\*(C'\fR method returns the error messages when a given PPI::Find
 265 object fails any action.
 266 .PP
 267 Returns a string, or \f(CW\*(C`undef\*(C'\fR if there is no error.
 268 .SH "TO DO"
 269 .IX Header "TO DO"
 270 \&\- Implement the PPI::Find::Rule class
 271 .SH "SUPPORT"
 272 .IX Header "SUPPORT"
 273 See the support section in the main module.
 274 .SH "AUTHOR"
 275 .IX Header "AUTHOR"
 276 Adam Kennedy <adamk@cpan.org>
 277 .SH "COPYRIGHT"
 278 .IX Header "COPYRIGHT"
 279 Copyright 2001 \- 2009 Adam Kennedy.
 280 .PP
 281 This program is free software; you can redistribute
 282 it and/or modify it under the same terms as Perl itself.
 283 .PP
 284 The full text of the license can be found in the
 285 \&\s-1LICENSE\s0 file included with this module.