Catman...:Simple(3pm)

💖 Catmandu::Store::File::Simple 💖

okay bestie, so this is a page from the User Contributed Perl Documentation, and the module we're obsessing over is Catmandu::Store::File::Simple. she's a whole vibe. let's get into it 🫶

---

✨ NAME ✨

Catmandu::Store::File::Simple — a Catmandu::FileStore that stores your files on disk. like, actually on disk. real files. physical. iconic. 💅

---

🌸 SYNOPSIS 🌸

first up, from the command line, bestie:

# 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

now define a config file, the way that she deserves:

# Define a configuration file
$ cat catmandu.yml
---
store:
   mypaths:
     package: DBI
     options:
       data_source: dbi:sqlite:dbname=data/index.db
   myfiles:
     package: File::Simple
     options:
       root: data/files
       directory_index_package: Map
       directory_index_options:
            store_name: mypaths
            bag_name: data
...

and then use that default catmandu.yml config file to add data to the FileStore:

# Use the default 'catmandu.yml' configuraion file to add data to the FileStore
$ catmandu stream /tmp/myfile.txt to myfiles --bag 1234 --id myfile.txt
$ catmandu stream myfiles --bag 1234 --id myfile.txt to /tmp/myfile.txt

(and yes, that typo says configuraion, we're leaving it, it's part of her charm now 🎀)

and finally, from Perl, no cap:

# From Perl
use Catmandu;

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

my $index = $store->index;

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

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

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

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

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

# Retrieve a file
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 folder
$index->delete('1234');

---

🦋 DESCRIPTION 🦋

Catmandu::Store::File::Simple is a Catmandu::FileStore implementation that stores files in a directory structure. and when we say directory structure, we mean she goes deep. every Catmandu::FileBag is a deeply nested directory built off the numeric identifier of the bag. for example:

$store->bag(1234)

gets stored as

${ROOT}/000/001/234

and inside that directory, all the Catmandu::FileBag items are just stored as flat files. simple! clean! lowkey elegant! ✨

---

💅 METHODS 💅

new(root => $path , [ keysize => NUM , uuid => 1])

make a brand new Catmandu::Store::File::Simple, and she takes these config parameters:

• root — the root directory where all the files get stored. Required. like, you genuinely cannot skip this one.
• keysize — DEPRECATED: use directory_index_package and directory_index_options instead. by default the directory structure is 3 levels deep. with the keysize option you can create deeper nesting. keysize needs to be a multiple of 3. and every container key of a Catmandu::Store::File::Simple must be an integer. no decimals, no vibes, integers only.
• uuid — DEPRECATED: use directory_index_package and directory_index_options instead. if it's set to a true value, then the Simple store will require UUID-s as keys.
• directory_index_package — the package name that translates between an id and a directory. the prefix "Catmandu::DirectoryIndex::" can be omitted. Default: Catmandu::DirectoryIndex::Number.
• directory_index_options — constructor arguments for the directory_index_package (see above).
• directory_index — an instance of Catmandu::DirectoryIndex. when you supply this, directory_index_package and directory_index_options get ignored. when you don't, this object is constructed from directory_index_package and directory_index_options. periodt.

---

🌈 INHERITED METHODS 🌈

this Catmandu::FileStore implements:

• Catmandu::FileStore
• Catmandu::Droppable

the index Catmandu::Bag in this Catmandu::Store implements:

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

the file Catmandu::Bag in this Catmandu::Store implements:

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

she's got range. the family tree is giving main character energy fr fr. 🌳

---

🎀 SEE ALSO 🎀

• Catmandu::Store::File::Simple::Index
• Catmandu::Store::File::Simple::Bag
• Catmandu::Plugin::SideCar
• Catmandu::FileStore

go read those next, bestie, iykyk 💜

---

and that's the whole page, mwah 💋 this one shipped as part of perl v5.36.0, dated 2022-12-10 — she's vintage, she's stable, she ate and left no crumbs. byeeee 🦋✨💖