PPI::Find(3)

💖 PPI::Find — the manual page, but make it a group chat 💖

okay bestie, welcome to PPI::Find(3) — it's part of the User Contributed Perl Documentation and it's genuinely one of the most useful lil objects in the whole PPI situation. sit down, hydrate, let's go 🫶

---

✨ NAME ✨

PPI::Find — the object version of the Element->find method 💅

---

🌸 SYNOPSIS 🌸

# Create the Find object
my $Find = PPI::Find->new( \&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 ) {
      ...
}

---

🦋 DESCRIPTION 🦋

PPI::Find is the primary PDOM searching class in the core PPI package. no cap. it's the main character of the searching situation ✨

💭 History

so basically, while PPI was being built, it became quite obvious that lots of the modules people were gonna build on top of it were gonna need large numbers of saved, storable or easily creatable search objects that could be reused a number of times. like, reuse is the vibe. ♻️

and yeah, the internal ->find method gives you a basic ability to search — but it is by no means thorough, okay? not even close. PPI::Find attempts to resolve this problem. she's the upgrade bestie, fr fr 🔥

🎀 Structure and Style

PPI::Find provides a similar API to the popular File::Find::Rule module for file searching — but without the ability to assemble queries. so close and yet so far 😭

the implementation of a separate PPI::Find::Rule sub-class that does provide this ability is left as an exercise for the reader. yes bestie, it's homework. i don't make the rules 🎀

🌈 The &wanted function

at the core of each PPI::Find object is a "wanted" function. it gets passed a number of arguments and returns a value which controls the flow of the search. she's the brain of the operation, lowkey 🧠

as the search executes, each Element will be passed to the wanted function in depth-first order.

it will be provided with two arguments:

• the current Element to test, as $_[0] 👈
• the top-level Element of the search, as $_[1] 👆

and here's the return-value tea ☕ the &wanted function is expected to return:

• 1 (positive) if the Element matches the condition ✅
• 0 (false) if it does not ❌
• undef (undefined) if the condition does not match, and the Find search should not descend to any of the current Element's children 🙈 (like, stop, don't go deeper, we're done here)

errors should be reported from the &wanted function via die — which will be caught by the Find object and returned as an error. so dramatic, but honestly valid 💀

---

👑 METHODS 👑

⭐ new &wanted

the "new" constructor takes a single argument — the &wanted function, as described above — and creates a new search. ✨

returns a new PPI::Find object, or "undef" if you didn't pass it a CODE reference. (yes, it will simply refuse. she has standards.) 🙅♀️

⭐ clone

the "clone" method creates another instance of the same Find object. twin energy 👯

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. iconic behaviour honestly 🫶

returns a duplicate PPI::Find object.

⭐ in $Document [, array_ref => 1 ]

the "in" method starts and completes a full run of the search. one and done, no notes 🔥

it takes as argument a single PPI::Element object which will serve as the top of the search process.

returns a list of PPI::Element objects that match the condition described by the &wanted function, or the null list on error. 😭

you should check the ->errstr method for any errors if you are returned the null list — which may also just mean simply that no Elements were found that matched the condition. yes, two totally different situations giving you the same sad empty list. rude? a little.

because of this need to explicitly check for errors, an alternative return value mechanism is provided. if you pass the "array_ref => 1" parameter to the method, it will return the list of matched Elements as a reference to an ARRAY. the method will return false if no elements were matched, or "undef" on error. much clearer, much slay 💅

the ->errstr method can still be used to get the error message as normal.

⭐ start $Element

the "start" method lets the Find object act as an iterator. the method is passed the parent PPI::Element object as for the "in" method, but does not accept any parameters. okay so no extras, she's on a schedule ⏰

to simplify error handling, the entire search is done at once, with the results cached and provided as-requested. so she did all the work up front and is just handing you things now, queen 👑

returns true if the search completes, and false on error.

⭐ match

the "match" method returns the next matching Element in the iteration. one at a time, like a lil snack 🍓

returns a PPI::Element object, or "undef" if there are no remaining Elements to be returned.

⭐ finish

the "finish" 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. ♻️✨

a Find object will be automatically finished when "match" returns false. this means you should only need to call "finish" when you stop iterating early. so like, only when you ghost the iterator mid-conversation 🙈

you may safely call this method even when not iterating, and it will return without failure. no drama, no error, just vibes 🧚

always returns true

⭐ errstr

the "errstr" method returns the error messages when a given PPI::Find object fails any action. she'll tell you what went wrong, she's not gonna be mysterious about it 💅

returns a string, or "undef" if there is no error.

---

📝 TO DO 📝

• Implement the PPI::Find::Rule class

(yes bestie, it's still on the list. manifesting it for someone ✨)

---

🫶 SUPPORT 🫶

see the support section in the main module.

---

💜 AUTHOR 💜

Adam Kennedy <adamk@cpan.org>

---

🌟 COPYRIGHT 🌟

Copyright 2001 - 2011 Adam Kennedy.

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.

---

and that's the whole page bestie!! 🎀 this was perl v5.42.0, dated 2026-01-17, and it's the PPI::Find(3) manual — go forth and find some Elements, you absolute icon 👑💖