Lucy::...Matcher(3pm)

💖 Lucy::Search::Matcher — the vibe 💖

okay bestie, welcome to Lucy::Search::Matcher(3pm), the manual page for the abstract base class that matches a set of document ids. yes it's giving very "the blueprint" energy and we're obsessed 🎀

---

✨ NAME ✨

Lucy::Search::Matcher — Match a set of document ids. periodt.

---

🌸 SYNOPSIS 🌸

# abstract base class

that's it, that's the whole synopsis, she's mysterious like that 💅

---

🦋 DESCRIPTION 🦋

so here's the tea: a Matcher iterates over a set of ascending document ids. like, they go up, always, no backtracking, no chaos 🌈

some Matchers implement score() and can hand out relevance scores to the docs they match — main character behaviour, fr fr. other implementations may be match-only, which is also valid, we don't judge, every matcher is iconic in its own way 🫶

---

👑 CONSTRUCTORS 👑

💜 new

my $matcher = MyMatcher->SUPER::new;

abstract constructor. that's right — you don't call this one directly, you subclass it, you do the work, you slay ✨

---

🎀 ABSTRACT METHODS 🎀

these are the ones you have to implement, no cap.

⭐ next

my $int = $matcher->next();

proceed to the next doc id. one step forward, bestie 🚶♀️

Returns: a positive doc id, or 0 once the iterator is exhausted. so if you get 0, she's done, the well is dry, we move on 💀

🌸 get_doc_id

my $int = $matcher->get_doc_id();

return the current doc id.

okay so this one is valid only after a successful call to next() or advance() and must not be called otherwise. like, do not call her before she's ready, that's not the vibe 🙈

💅 score

my $float = $matcher->score();

return the score of the current document.

only Matchers which are used for scored search need implement score(). if you're just matching and not scoring, you can skip this, no pressure, live your truth 🦋

---

🌈 METHODS 🌈

💖 advance

my $int = $matcher->advance($target);

advance the iterator to the first doc id greater than or equal to "target". the default implementation simply calls next() over and over (yes, a lil brute force, she's trying her best 😭), but subclasses have the option of doing something more efficient. glow-up opportunity!!

• target — a positive doc id, which must be greater than the current doc id once the iterator has been initialized.

Returns: a positive doc id, or 0 once the iterator is exhausted.

---

🧚 INHERITANCE 🧚

Lucy::Search::Matcher isa Clownfish::Obj.

family tree ate, honestly 👑

---

and that's the whole page, bestie!! go forth and match some doc ids 💜

signing off with love from perl v5.42.0, dated 2025-07-25, in the house of Lucy::...Matcher(3pm) — stay ascending, stay iconic 🎀✨🔥