Lucy::...Reader(3pm)

💖 Lucy::Index::SegReader — single-segment IndexReader, bestie edition

So this is a page from the Perl docs, user-contributed and all — and it's about Lucy::Index::SegReader, the little reader that knows everything about one single segment of an index. Come sit with me, I promise it's not scary. 🫶

---

✨ SYNOPSIS ✨

okay so first, the vibe: you open a whole index, grab its seg readers, and then peek at each segment one by one. like this, exactly like this:

my $polyreader = Lucy::Index::IndexReader->open(
    index => '/path/to/index',
);
my $seg_readers = $polyreader->seg_readers;
for my $seg_reader (@$seg_readers) {
    my $seg_name = $seg_reader->get_seg_name;
    my $num_docs = $seg_reader->doc_max;
    print "Segment $seg_name ($num_docs documents):\n";
    my $doc_reader = $seg_reader->obtain("Lucy::Index::DocReader");
    for my $doc_id ( 1 .. $num_docs ) {
        my $doc = $doc_reader->fetch_doc($doc_id);
        print "  $doc_id: $doc->{title}\n";
    }
}

iconic behavior honestly 💅

---

🌸 DESCRIPTION 🌸

SegReader reads the data inside a single segment of an index. That's the whole thing. One segment. It's not out here doing the most — it's doing its one job beautifully. 💖

Real talk though: generally speaking, only advanced users writing subclasses which manipulate data at the segment level need to deal with the SegReader API directly. So if that's not you, no shame, you can scroll. 🙈

And here's the tea: nearly all of SegReader's functionality is actually implemented by pluggable components, spawned by Architecture's factory methods. So SegReader is kind of the main character but the whole ensemble is carrying the plot. ✨

---

👑 METHODS 👑

get_seg_name

my $string = $seg_reader->get_seg_name();

Returns the name of the segment. That's it, that's the whole method, and she ate. 🎀

get_seg_num

my $int = $seg_reader->get_seg_num();

Returns the number of the segment. 🔢

del_count

my $int = $seg_reader->del_count();

Returns how many documents have been marked as deleted but not yet purged from the index. They're still hanging around being ghosties. 👻

doc_max

my $int = $seg_reader->doc_max();

Returns the maximum number of documents available to the reader — which is also the highest possible internal document id. Heads up bestie: documents that are marked as deleted but not yet purged from the index are included in this count. So this is the ceiling, not the truth. 💀

doc_count

my $int = $seg_reader->doc_count();

Returns the number of documents actually available to the reader, subtracting any that are marked as deleted. This is the honest one. 💚

_offsets

my $i32_array = $seg_reader->_offsets();

Returns an array with one entry for each segment, corresponding to segment doc_id start offset. (Yes, it starts with an underscore. Yes, that's a whole thing. Mind your business. 🙈)

seg_readers

my $arrayref = $seg_reader->seg_readers();

Returns an array of all the SegReaders represented within the IndexReader. 🦋

---

🌈 INHERITANCE 🌈

the family tree, no cap:

Lucy::Index::SegReader isa Lucy::Index::IndexReader isa Lucy::Index::DataReader isa Clownfish::Obj.

four generations of slay 💜

---

and that's the page, bestie. this one's from perl v5.42.0, dated 2025-07-25 — so if you're reading it way later, hi from the past, hope your segments are purged. 🫶✨🎀