.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" 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 .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . 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::Find 3pm" .TH PPI::Find 3pm "2019-07-21" "perl v5.28.1" "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::Find \- Object version of the Element\->find method .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # Create the Find object \& my $Find = PPI::Find\->new( \e&wanted ); \& \& # Return all matching Elements as a list \& my @found = $Find\->in( $Document ); \& \& # Can we find any matching Elements \& if ( $Find\->any_matches($Document) ) { \& print "Found at least one matching Element"; \& } \& \& # Use the object as an iterator \& $Find\->start($Document) or die "Failed to execute search"; \& while ( my $token = $Find\->match ) { \& ... \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" PPI::Find is the primary \s-1PDOM\s0 searching class in the core \s-1PPI\s0 package. .SS "History" .IX Subsection "History" It became quite obvious during the development of \s-1PPI\s0 that many of the modules that would be built on top of it were going to need large numbers of saved, storable or easily creatable search objects that could be reused a number of times. .PP Although the internal \->find method provides a basic ability to search, it is by no means thorough. PPI::Find attempts to resolve this problem. .SS "Structure and Style" .IX Subsection "Structure and Style" PPI::Find provides a similar \s-1API\s0 to the popular File::Find::Rule module for file searching, but without the ability to assemble queries. .PP The implementation of a separate PPI::Find::Rule sub-class that does provide this ability is left as an exercise for the reader. .SS "The &wanted function" .IX Subsection "The &wanted function" At the core of each PPI::Find object is a \*(L"wanted\*(R" function that is passed a number of arguments and returns a value which controls the flow of the search. .PP As the search executes, each Element will be passed to the wanted function in depth-first order. .PP It will be provided with two arguments. The current Element to test as \f(CW$_\fR[0], and the top-level Element of the search as \f(CW$_\fR[1]. .PP The &wanted function is expected to return 1 (positive) if the Element matches the condition, 0 (false) if it does not, and undef (undefined) if the condition does not match, and the Find search should not descend to any of the current Element's children. .PP Errors should be reported from the &wanted function via die, which will be caught by the Find object and returned as an error. .SH "METHODS" .IX Header "METHODS" .SS "new &wanted" .IX Subsection "new &wanted" The \f(CW\*(C`new\*(C'\fR constructor takes a single argument of the &wanted function, as described above and creates a new search. .PP Returns a new PPI::Find object, or \f(CW\*(C`undef\*(C'\fR if not passed a \s-1CODE\s0 reference. .SS "clone" .IX Subsection "clone" The \f(CW\*(C`clone\*(C'\fR method creates another instance of the same Find object. .PP The cloning is done safely, so if your existing Find object is in the middle of an iteration, the cloned Find object will not also be in the iteration and can be safely used independently. .PP Returns a duplicate PPI::Find object. .ie n .SS "in $Document [, array_ref => 1 ]" .el .SS "in \f(CW$Document\fP [, array_ref => 1 ]" .IX Subsection "in $Document [, array_ref => 1 ]" The \f(CW\*(C`in\*(C'\fR method starts and completes a full run of the search. .PP It takes as argument a single PPI::Element object which will serve as the top of the search process. .PP Returns a list of PPI::Element objects that match the condition described by the &wanted function, or the null list on error. .PP You should check the \->errstr method for any errors if you are returned the null list, which may also mean simply that no Elements were found that matched the condition. .PP Because of this need to explicitly check for errors, an alternative return value mechanism is provide. If you pass the \f(CW\*(C`array_ref => 1\*(C'\fR parameter to the method, it will return the list of matched Elements as a reference to an \s-1ARRAY.\s0 The method will return false if no elements were matched, or \f(CW\*(C`undef\*(C'\fR on error. .PP The \->errstr method can still be used to get the error message as normal. .ie n .SS "start $Element" .el .SS "start \f(CW$Element\fP" .IX Subsection "start $Element" The \f(CW\*(C`start\*(C'\fR method lets the Find object act as an iterator. The method is passed the parent PPI::Element object as for the \f(CW\*(C`in\*(C'\fR method, but does not accept any parameters. .PP To simplify error handling, the entire search is done at once, with the results cached and provided as-requested. .PP Returns true if the search completes, and false on error. .SS "match" .IX Subsection "match" The \f(CW\*(C`match\*(C'\fR method returns the next matching Element in the iteration. .PP Returns a PPI::Element object, or \f(CW\*(C`undef\*(C'\fR if there are no remaining Elements to be returned. .SS "finish" .IX Subsection "finish" The \f(CW\*(C`finish\*(C'\fR method provides a mechanism to end iteration if you wish to stop the iteration prematurely. It resets the Find object and allows it to be safely reused. .PP A Find object will be automatically finished when \f(CW\*(C`match\*(C'\fR returns false. This means you should only need to call \f(CW\*(C`finish\*(C'\fR when you stop iterating early. .PP You may safely call this method even when not iterating and it will return without failure. .PP Always returns true .SS "errstr" .IX Subsection "errstr" The \f(CW\*(C`errstr\*(C'\fR method returns the error messages when a given PPI::Find object fails any action. .PP Returns a string, or \f(CW\*(C`undef\*(C'\fR if there is no error. .SH "TO DO" .IX Header "TO DO" \&\- Implement the PPI::Find::Rule class .SH "SUPPORT" .IX Header "SUPPORT" See the support section in the main module. .SH "AUTHOR" .IX Header "AUTHOR" Adam Kennedy .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 \&\s-1LICENSE\s0 file included with this module.