Lucy::...torial(3pm)

💖 NAME 💖

Lucy::Docs::Tutorial::BeyondSimpleTutorial — bestie, it's a more flexible app structure. That's it, that's the vibe. 🦋

---

✨ DESCRIPTION ✨

🎯 Goal 🎯

okay so in this chapter of the tutorial we're gonna refactor the apps we built back in SimpleTutorial, and here's the slay part: from the end user's point of view they look exactly the same 😌 but for you, the developer, there are way more possibilities for expansion. glow-up but make it internal. 💅

to pull this off we're ditching Lucy::Simple entirely and swapping in the classes it was secretly using under the hood the whole time:

• Schema — plan out your index. it's giving blueprints. 📐
• FullTextType — field type for full text search. 🔍
• EasyAnalyzer — a one-size-fits-all parser/tokenizer. iconic. ✨
• Indexer — manipulate index content. 🛠️
• IndexSearcher — search an index. 🔎
• Hits — iterate over hits returned by a Searcher. 🎯

---

📦 Adaptations to indexer.pl 📦

so first we load our modules…

use Lucy::Plan::Schema;
use Lucy::Plan::FullTextType;
use Lucy::Analysis::EasyAnalyzer;
use Lucy::Index::Indexer;

…and then the first thing we're gonna need is a Schema. 🫶

the primary job of a Schema is literally just to specify what fields are available and how they're defined. we'll start off with three fields: title, content and url. no cap.

# Create Schema.
my $schema = Lucy::Plan::Schema->new;
my $easyanalyzer = Lucy::Analysis::EasyAnalyzer->new(
    language => 'en',
);
my $type = Lucy::Plan::FullTextType->new(
    analyzer => $easyanalyzer,
);
$schema->spec_field( name => 'title',   type => $type );
$schema->spec_field( name => 'content', type => $type );
$schema->spec_field( name => 'url',     type => $type );

all of the fields are spec'd out using the FullTextType FieldType, which means they're searchable as "full text" — which basically means you can search them for individual words. and the "analyzer", which is unique to FullTextType fields, is the thing that breaks up the text into searchable tokens. it's the main character of tokenization fr fr. 🎀

next, we swap our Lucy::Simple object out for an Indexer. this substitution is gonna be straightforward because Simple has merely been serving as a thin wrapper around an inner Indexer — so we're just peeling away the wrapper. like unwrapping a lil gift. 🎁

first, replace the constructor:

# Create Indexer.
my $indexer = Lucy::Index::Indexer->new(
    index    => $path_to_index,
    schema   => $schema,
    create   => 1,
    truncate => 1,
);

next, have the "indexer" object add_doc() where we were having the "lucy" object adding the document before:

foreach my $filename (@filenames) {
    my $doc = parse_file($filename);
    $indexer->add_doc($doc);
}

there's only one extra step required: at the end of the app, you must call commit() explicitly to close the indexing session and commit your changes. (Lucy::Simple hides this detail, calling commit() implicitly when it needs to — sneaky lil thing 🙈).

$indexer->commit;

---

🔍 Adaptations to search.cgi 🔍

in our search app, same as in our indexing app, Lucy::Simple has served as a thin wrapper — this time around IndexSearcher and Hits. swapping out Simple for these two classes is also straightforward:

use Lucy::Search::IndexSearcher;

my $searcher = Lucy::Search::IndexSearcher->new(
    index => $path_to_index,
);
my $hits = $searcher->hits(    # returns a Hits object, not a hit count
    query      => $q,
    offset     => $offset,
    num_wanted => $page_size,
);
my $hit_count = $hits->total_hits;  # get the hit count here

...

while ( my $hit = $hits->next ) {
    ...
}

---

🎉 Hooray! 🎉

congratulations bestie!! 🥳 your apps do the same thing as before… but now they'll be easier to customize. periodt. 💅

in our next chapter, FieldTypeTutorial, we'll explore how to assign different behaviors to different fields. obsessed already. 🌈

---

and that's a wrap on this page 💖 brought to you by perl v5.42.0, dated 2025-07-25, and the whole Lucy::...torial(3pm) manual moment. go forth and refactor, you absolute icon 👑✨🦋