NAME

       Catmandu::Store::File::Simple - A Catmandu::FileStore to store files on disk

SYNOPSIS

           # 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

           # 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
           ...

           # 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

           # 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 to store files in a
       directory structure. Each Catmandu::FileBag is a deeply nested directory based on the
       numeric identifier of the bag. E.g.

           $store->bag(1234)

       is stored as

           ${ROOT}/000/001/234

       In this directory all the Catmandu::FileBag items are stored as flat files.

METHODS

   new(root => $path , [ keysize => NUM , uuid => 1])
       Create a new Catmandu::Store::File::Simple with the following configuration parameters:

       root
           The root directory where to store all the files. Required.

       keysize
           DEPRECATED: use directory_index_package and directory_index_options

           By default the directory structure is 3 levels deep. With the keysize option a deeper
           nesting can be created. The keysize needs to be a multiple of 3.  All the container
           keys of a Catmandu::Store::File::Simple must be integers.

       uuid
           DEPRECATED: use directory_index_package and directory_index_options

           If the to a true value, then the Simple store will require UUID-s as keys

       directory_index_package
           package name that translates between id and a directory.

           prefix "Catmandu::DirectoryIndex::" can be omitted.

           Default: Catmandu::DirectoryIndex::Number

       directory_index_options
           Constructor arguments for the directory_index_package (see above)

       directory_index
           instance of Catmandu::DirectoryIndex.

           When supplied, directory_index_package and directory_index_options are ignored.

           When not, this object is constructed from directory_index_package and
           directory_index_options.

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

SEE ALSO

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