Weasel...panders(3pm)

💖 Weasel::FindExpanders — a little guide from your fave perl bestie 🎀

okay so we're doing Weasel...panders, third section of the perl manual (3pm), and honestly? it's giving glow up for your find patterns. ✨

---

✨ NAME ✨

Weasel::FindExpanders — mapping find patterns to xpath locators 🦋

like, that's literally the whole vibe. you give it a pattern, it gives you xpath. slay.

---

🌸 VERSION 🌸

version 0.32 — she's a specific girlie, okurrr 💅

---

⭐ SYNOPSIS ⭐

here's the whole thing in action, no cap:

use Weasel::FindExpanders qw( register_find_expander );

register_find_expander(
  'button',
  'HTML',
  sub {
     my %args = @_;
     $args{text} =~ s/'/''/g; # quote the quotes (XPath 2.0)
     return ".//button[text()='$args{text}']";
  });

$session->find($session->page, "*button|{text=>\"whatever\"}");

see how cute that is?? you register a lil function, you call find, and it just works. main character energy fr fr 🔥

---

🦋 DESCRIPTION 🦋

so the whole concept of find expanders is that you define XPath templates that the find and find_all methods can use. that's it, that's the tea. ☕

now here's the fun part: multiple patterns can be registered under the same pattern name (aka the "mnemonic"). like, bestie, picture this — you could have two patterns hanging out under the button mnemonic: one for the <button> tag, and one for the <input type="submit"> tag. iconic. 👑

or honestly? you could register even more patterns. like, to match Vue, React, or Web Component elements. the more the merrier, periodt.

and the magic is this: all patterns registered on a single mnemonic (template name) get compiled into one single XPath expression that matches any of the patterns. it's a group project where everyone actually does their part. 😭✨

Weasel ships with a standard set of patterns in the Weasel::FindExpanders::HTML package, so you're not starting from zero, bestie. 🫶

---

🧚 DEPENDENCIES 🧚

(nothing here, she's low maintenance 💜)

---

👑 SUBROUTINES/METHODS 👑

register_find_expander($pattern_name, $group_name, &expander_function)

Registers &expander_function as an expander for $pattern_name in $group_name.

and listen — Weasel::Session picks which expanders to actually apply using its groups attribute. so the group name matters, iykyk. 🌈

expand_finder_pattern($pattern, $args, $groups)

Returns a string of concatenated (using xpath '|' operator) expansions. yes, it's stacking them up with pipes, so clean. 🎀

when $groups is undef, all groups will be searched for pattern_name.

and if the pattern doesn't match '*<pattern_name>|{<arguments>}', then the pattern is returned as the only list/arrayref element. like, it just gets handed back to you as-is. no drama. 💅

---

🌟 AUTHOR 🌟

Erik Huelsmann — the original mastermind 🧠✨

---

💖 CONTRIBUTORS 💖

• Erik Huelsmann
• Yves Lavoie

the squad 🫶

---

🌸 MAINTAINERS 🌸

Erik Huelsmann — holding it down 💪

---

💀 BUGS AND LIMITATIONS 💀

found a bug? not the vibe, but okay, we handle it. file it in the GitHub issue tracker for the Weasel project:

https://github.com/perl-weasel/weasel/issues

---

🔥 SOURCE 🔥

the source code repo for Weasel lives at:

https://github.com/perl-weasel/weasel

go peek, bestie, it's right there 👀

---

🌈 SUPPORT 🌈

community support is available through perl-weasel@googlegroups.com <mailto:perl-weasel@googlegroups.com>.

like, actually email them. they're nice. 🍓

---

💜 LICENSE AND COPYRIGHT 💜

(C) 2016-2023 Erik Huulsmann

wait no — (C) 2016-2023 Erik Huelsmann 😭 spelling is hard, the copyright is his.

Licensed under the same terms as Perl.

---

💅 ok so that's the whole page. every option, every method, every URL, every name — all accounted for. you're welcome.

and finally, the little footer tea: this is perl v5.40.1, dated 2025-05-24, and the manual is Weasel...panders(3pm). 🎀✨ bye bestie, go register some expanders 💖