Lucy::...napshot(3pm)

💖 Lucy::Index::Snapshot — point-in-time index file list 💖

okay bestie, so this is from the User Contributed Perl Documentation corner of the manual, and it's genuinely one of the cutest little classes in Lucy. let's get into it 🦋

---

✨ NAME ✨

Lucy::Index::Snapshot — a point-in-time list of index files. it's giving "polaroid of your index" energy fr fr 📸

---

🌸 SYNOPSIS 🌸

my $snapshot = Lucy::Index::Snapshot->new;
$snapshot->read_file( folder => $folder );    # load most recent snapshot
my $files = $snapshot->list;
print "$_\n" for @$files;

like, that's it. that's the whole vibe. you make one, you load it, you list the files, you print them. slay. 💅

---

🎀 DESCRIPTION 🎀

okay so a Snapshot is literally just a list of index files and folders. that's the whole thing.

but here's the iconic part: because index files, once they've been written, are never modified — like, ever, they're frozen, they don't get touched again — a Snapshot defines a point-in-time view of the data in an index. it's a timestamped selfie of your index that never changes. no cap. 🫶

and IndexReader objects? they interpret the data associated with a single Snapshot. one reader, one snapshot, no crossover. periodt.

---

🧚 CONSTRUCTORS 🧚

✨ new

my $snapshot = Lucy::Index::Snapshot->new;

the constructor. takes no arguments. she's low maintenance, she doesn't need anything from you. 👑

---

💜 METHODS 💜

⭐ list

my $arrayref = $snapshot->list();

returns an array of all the entries. every single one. no gatekeeping. 📋

🦋 num_entries

my $int = $snapshot->num_entries();

returns the number of entries — and yes bestie, that count includes directories. don't forget the directories. 🔢

🌸 add_entry

$snapshot->add_entry($entry);

adds a filepath to the snapshot. one (1) filepath, right into the list. 🫶

💅 delete_entry

my $bool = $snapshot->delete_entry($entry);

deletes a filepath from the snapshot. bye bestie 👋

Returns: true if the entry actually existed and got successfully deleted, false otherwise. so like, it tells you the truth either way. honest queen. ✨

🎀 read_file

my $result = $snapshot->read_file(
    folder => $folder,  # required
    path   => $path,    # default: undef
);

decodes a snapshot file and initializes the object to reflect its contents. like, it reads the file and then becomes it. main character energy honestly. 🌈

• folder — a Folder. required bestie, do not skip.
• path — the location of the snapshot file. if you don't supply it, the most recent snapshot file in the base directory gets chosen for you. she picks for you, and she picks well. 💖

Returns: the Snapshot object itself. it hands you back itself. iconic behavior.

💖 write_file

$snapshot->write_file(
    folder => $folder,  # required
    path   => $path,    # default: undef
);

writes a snapshot file. 🖊️

⚠️ okay so important: the caller must lock the index while this operation takes place, and the operation will fail if the snapshot file already exists. no overwrites. none. don't even try it.

• folder — a Folder. required.
• path — the path of the file to write. if it's undef, a file name will be chosen which supersedes the latest snapshot file in the index folder. so it just naturally levels up. ⬆️

🧚 set_path

$snapshot->set_path($path);

sets the path to the file that the Snapshot object serves as a proxy for. she's standing in for the file. representative. delegate. 💁

👑

my $string = $snapshot->get_path();

gets the path to the snapshot file. initially undef, and then it gets updated by read_file(), write_file(), and set_path(). so it starts out not knowing who it is and then finds itself. character development fr fr 😭✨

---

🌟 INHERITANCE 🌟

Lucy::Index::Snapshot isa Clownfish::Obj. it's in the family. the lineage is real. 👑

---

---

and that's the whole page bestie!! 🎀 this was perl v5.42.0, dated 2025-07-25, and yeah it came out of the same Lucy::...napshot(3pm) manual you're holding right now — go forth and snapshot responsibly 💖✨🦋