Lucy::Simple(3pm)

💖 Lucy::Simple 💖

okay bestie, welcome to Lucy::Simple — the Basic search engine from the User Contributed Perl Documentation section of the manual (yes that's the (3pm) in Lucy::Simple(3pm), iykyk). she's little, she's cute, she's a whole search engine. let's get into it 🦋

---

✨ NAME ✨

Lucy::Simple — Basic search engine. that's it. that's the vibe. 💅

---

🌸 SYNOPSIS 🌸

okay so first things first, you gotta build an index of your documents. no index, no search, no slay.

my $index = Lucy::Simple->new(
    path     => '/path/to/index/'
    language => 'en',
);

while ( my ( $title, $content ) = each %source_docs ) {
    $index->add_doc({
        title    => $title,
        content  => $content,
    });
}

and then, later (like, whenever you want), you search the index. main character move fr fr.

my $total_hits = $index->search(
    query      => $query_string,
    offset     => 0,
    num_wanted => 10,
);

print "Total hits: $total_hits\n";
while ( my $hit = $index->next ) {
    print "$hit->{title}\n",
}

---

💜 DESCRIPTION 💜

Lucy::Simple is a stripped-down interface for the Apache Lucy search engine library. like, all the power, none of the extra baggage. she's giving minimal but make it work. 👑

---

🎀 CONSTRUCTORS 🎀

new

my $lucy = Lucy::Simple->new(
    path     => '/path/to/index/',
    language => 'en',
);

Create a Lucy::Simple object 🫶 — and the cute part is you can use this one object for both indexing and searching. multitasking queen.

both parameters, path and language, are required. no skipping, bestie, she will notice.

• path — where the index directory should live. and here's the cute part: if there's no index at the location you named, one gets created for you. she's self-sufficient like that 💅
• language — the language of the documents in your collection, and you tell her with a two-letter ISO code. 12 languages are supported, periodt:

|-----------------------|
| Language   | ISO code |
|-----------------------|
| Danish     | da       |
| Dutch      | nl       |
| English    | en       |
| Finnish    | fi       |
| French     | fr       |
| German     | de       |
| Italian    | it       |
| Norwegian  | no       |
| Portuguese | pt       |
| Spanish    | es       |
| Swedish    | sv       |
| Russian    | ru       |
|-----------------------|

---

🌈 METHODS 🌈

add_doc

$lucy->add_doc({
    location => $url,
    title    => $title,
    content  => $content,
});

Add a document to the index 📥. the document has to come in as a hashref, where the field names are the keys and the content is the values. simple as that, no cap.

search

my $int = $simple->search(
    query      => $query,       # required
    offset     => $offset,      # default: 0
    num_wanted => $num_wanted,  # default: 10
    sort_spec  => $sort_spec,   # default: undef
);

Search the index 🔍. she returns the total number of documents which match the query. and heads up — that number is unlikely to match num_wanted. don't @ her about it, that's just how it is.

• query — a search query string. this one's required, obviously, like how are you gonna search with no query bestie 😭
• offset — the number of most-relevant hits to discard, typically used when “paging” through hits N at a time. so like: set offset to 20 and num_wanted to 10 and you get hits 21-30 — assuming that 30 hits can even be found. math is mathing ✨
• num_wanted — the number of hits you would like to see after offset is taken into account. manifesting hits fr fr 🙈
• sort_spec — a SortSpec, which will affect how results are ranked and returned. fancy.

next

my $hit_doc = $simple->next();

Return the next hit, or undef when the iterator is exhausted. when she's out of hits, she's out — no dramatic goodbye, just undef. 💀

---

👑 INHERITANCE 👑

Lucy::Simple isa Clownfish::Obj. family tree slay 🌈

---

and that's the whole page bestie!! 🎀 this one shipped with perl v5.42.0, dated 2025-07-25, from the User Contributed Perl Documentation corner of the manual — go forth and index your little heart out, you're gonna eat 💅✨🦋