Catman...leStore(3pm)

💖 Catmandu::FileStore 💖

okay bestie, sit down, hydrate, because this one is a whole namespace and it's iconic. it lives in the User Contributed Perl Documentation corner of the manpages (you know, section 3pm, where all the perl modules hang out), and it's genuinely so useful. let's get into it 🫶

---

✨ NAME ✨

Catmandu::FileStore — it's literally a namespace for packages that can make files persistent. that's it, that's the whole vibe. files that stay put. 💅

---

🌸 SYNOPSIS 🌸

first up, from the command line, because we love a terminal moment:

# From the command line

# Export a list of all file containers
$ catmandu export File::Simple --root t/data to YAML

# Export a list of all files in container '1234'
$ catmandu export File::Simple --root t/data --bag 1234 to YAML

# Add a file to the container '1234'
$ catmandu stream /tmp/myfile.txt to File::Simple --root t/data --bag 1234 --id myfile.txt

# Download the file 'myfile.txt' from the container '1234'
$ catmandu stream File::Simple --root t/data --bag 1234 --id myfile.txt to /tmp/output.txt

# Delete the file 'myfile.txt' from the container '1234'
$ catmandu delete File::Simple --root t/data --bag 1234 --id myfile.txt

and now the Perl side, no cap:

# From Perl
use Catmandu;

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

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

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

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

# Get the container
my $files = $store->index->files('1234');

# Add a file to the container
$files->upload(IO::File->new('<foobar.txt'), 'foobar.txt');

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

# Stream the contents of a file
$files->stream(IO::File->new('>foobar.txt'), $file);

# Delete a file
$files->delete('foobar.txt');

# Delete a container
$store->index->delete('1234');

like… look at that. upload, get, stream, delete. main character energy fr fr 🌈

---

🦋 DESCRIPTION 🦋

so, every single Catmandu::FileStore is a Catmandu::Store — and it inherits all of that one's methods, no exceptions, it's giving nepo baby but make it legit.

a Catmandu::FileStore is a package whose whole job is to store and retrieve binary content — whether that's on an actual filesystem, in memory, or over a network. wherever you want, bestie. and inside a Catmandu::FileStore you'll find one or more Catmandu::FileBags, which are basically folders. a folder is a folder, we're not reinventing the wheel here 🎀

and each Catmandu::FileBag contains one or more files. obviously. nesting! we love a nesting moment.

now here's the lil special one: there's one particular Catmandu::FileBag called the index, and it holds the listing of every Catmandu::FileBag inside the Catmandu::FileStore. so the index is like the group chat roster, and everybody else is the actual chats. iykyk 💜

---

✨ CONFIGURATION ✨

🍓 index_bag

the name of the index bag to use when no bag name is given. the index bag is a bag that contains a listing of all Catmandu::FileBag-s in the Store. it's the VIP list, basically.

my $index = $store->index;

$index->each(sub {
    my $bag = shift;

    printf "%s\n" , $bag->{_id};
});

🧚 index_class

the default class implementation to use for an index of Catmandu::FileBag-s. by default this is the Catmandu::FileStore implementation with '::Index' added. so like, the default just takes the class name and glues ::Index on the end. cute, efficient, we stan. ✨

---

💅 METHODS 💅

💜 bag($name)

creates — or retrieves, if it's already there — a bag with the name $name. hands you back a Catmandu::FileBag. one function, two jobs, she's versatile. 👑

🎀 index

returns the index Catmandu::FileBag for the Catmandu::FileStore.

my $index = $store->index;

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

# Anf use it...
my $container = $store->bag('1234');

$container->upload(IO::File->new('data.txt') , 'data.txt');

🌸 log

returns the current logger. super handy when you're out here building your own Stores, bestie.

for example:

package Catmandu::Store::Hash;

...

sub generator {
    my ($self) = @_;

    $self->log->debug("generating record");
    ...
}

see also: Catmandu for activating the logger in your main code. go turn that logging on, you deserve the visibility 🔥

---

👑 AUTHOR 👑

• Patrick Hochstenbach, <patrick.hochstenbach at ugent.be>
• Nicolas Steenlant, <nicolas.steenlant at ugent.be>
• Nicolas Franck, <nicolas.franck at ugent.be>

three legends, three emails, one iconique module. periodt. 💖

---

🌈 SEE ALSO 🌈

• Catmandu::Store::File::Simple
• Catmandu::Store::File::Memory
• Catmandu::FileBag

go read those too, don't be a stranger to the docs 💜

---

⭐ LICENSE AND COPYRIGHT ⭐

this program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

see <http://dev.perl.org/licenses/> for more information.

---

okay that's the whole page, bestie, you ate it 💅✨ this little beauty shipped as part of perl v5.36.0 and the docs are dated 2022-12-10 — so yeah, vintage but make it relevant. mwah 🫶💖