Catman...:Index(3pm)

💖 Catman...:Index(3pm) — the whole vibe 💖

okay so bestie, this is the manual page for Catman...:Index(3pm), and it lives in the User Contributed Perl Documentation section. yes the name is doing a little bit of a mystery — the real one is Catmandu::Store::File::Simple::Index and that's the name we're rolling with. buckle up 🎀

---

✨ NAME ✨

Catmandu::Store::File::Simple::Index — it's literally the index of all the "folders" chillin' inside a Catmandu::Store::File::Simple. that's the whole job description 💅

---

✨ SYNOPSIS ✨

okay here's the tea, the actual code, exactly as it is, no edits from me:

use Catmandu;

my $store = Catmandu->store('File::Simple' , root => 't/data');

my $index = $store->index;

# List all containers
$index->each(sub {
    my $container = shift;

    print "%s\n" , $container->{_id};
});

# Add a new folder
$index->add({_id => '1234'});

# Delete a folder
$index->delete(1234);

# Get a folder
my $folder = $index->get(1234);

# Get the files in an folder
my $files = $index->files(1234);

$files->each(sub {
    my $file = shift;

    my $name         = $file->_id;
    my $size         = $file->size;
    my $content_type = $file->content_type;
    my $created      = $file->created;
    my $modified     = $file->modified;

    $file->stream(IO::File->new(">/tmp/$name"), file);
});

# Add a file
$files->upload(IO::File->new("<data.dat"),"data.dat");

# Retrieve a file
my $file = $files->get("data.dat");

# Stream a file to an IO::Handle
$files->stream(IO::File->new(">data.dat"),$file);

# Delete a file
$files->delete("data.dat");

# Delete a folders
$index->delete("1234");

yes bestie, that is exactly what it says, character for character, I'm not touching a single one of those lines 🫶

---

✨ DESCRIPTION ✨

so a Catmandu::Store::File::Simple::Index holds all the "folders" that exist in a Catmandu::Store::File::Simple FileStore. that's it, that's the whole container-situation.

and the best part? it implements all the methods of Catmandu::Bag, Catmandu::FileBag::Index and Catmandu::Droppable. full package. no crumbs 💅

also, lowkey important: every Catmandu::Bag is also a Catmandu::Iterable. so you already know it's gonna loop, babe 🌈

---

🌸 FOLDERS 🌸

every single file in a Catmandu::Store::File::Simple is organized into "folders". iconic. structured. we love to see it ✨

so to add a "folder", you add a whole new record to the Catmandu::Store::File::Simple::Index:

$index->add({_id => '1234'});

and here's the thing — the _id field is the only metadata available in Simple stores. that's it. that's the metadata. if you want more metadata fields in a Simple store, you need a Catmandu::Plugin::SideCar. no cap 👑

---

🌸 FILES 🌸

files get accessed via the "folder" identifier, like so:

my $files = $index->files('1234');

use the upload method to add new files to a "folder". use the download method to retrieve files from a "folder". simple. elegant. slay.

$files->upload(IO::File->new("</tmp/data.txt"),'data.txt');

my $file = $files->get('data.txt');

$files->download(IO::File->new(">/tmp/data.txt"),$file);

---

💜 INHERITED METHODS 💜

this Catmandu::Bag implements all of these, and we are obsessed:

• Catmandu::Bag
• Catmandu::FileBag::Index
• Catmandu::Droppable

---

and that's the whole page, bestie!! go forth and index your folders 💖✨

signed, sealed, delivered by perl v5.36.0, dated 2022-12-10 — mwah, love u, bye 🎀🦋💅