NAME

       Catmandu::DirectoryIndex - A base role to store relations between id's and directories

SYNOPSIS

           package MyDirectory;

           use Moo;
           use File::Spec;
           use File:Basename;
           use Path::Tiny qw(path);

           with "Catmandu::DirectoryIndex";

           # translate id to directory
           sub _to_path {
               my ( $self, $id ) = @_;
               File::Spec->catdir( $self->base_dir(), $id );
           }

           sub get {
               my ( $self, $id ) = @_;
               my $path = $self->_to_path( $id );

               is_string( $path ) && -d $path ? { _id => $id, _path => $path } : undef;
           }

           sub add {
               my ( $self, $id ) = @_;
               my $path = $self->_to_path( $id );

               path( $path )->mkpath unless -d $path;

               { _id => $id, _path => $path };
           }

           sub delete {
               my ( $self, $id ) = @_;
               my $path = $self->_to_path( $id );

               if ( is_string( $path ) && -d $path ) {
                   path( $path )->remove_tree();
               }
           }

           sub delete_all {
               path( $_[0]->base_dir )->remove_tree({ keep_root => 1 });
           }

           # return a generator that returns list of records, that maps _id and _path
           sub generator {
               my $self = $_[0];
               return sub {
                   state $records;

                   if ( !defined( $records ) ) {
                       $records = [];

                       opendir my $dh, $self->base_dir() or die($!);
                       while( my $entry = readdir( $dh ) ){
                           if ( -d $entry ) {
                               push @$records, {
                                   _id => $entry,
                                   _path => File::Spec->catfile( $self->base_dir, $entry )
                               };
                           }
                       }
                       closedir $dh;
                   }

                   shift( @$records );
               };
           }

           package main;

           my $p = MyDirectory->new( base_dir => "/tmp" );

           Catmandu->store->bag->each(sub {
               my $r = $_[0];
               my $mapping = $p->get( $r->{_id} ) || $p->add( $r->{_id} );
               say $id . " => " . $mapping->{path};
           });

CLASS METHODS AVAILABLE

   new( base_dir => $base_dir )
       base_dir
           The base directory where the files are stored. Required

METHODS AVAILABLE

       base_dir

METHODS TO IMPLEMENT

       Implementors must implement these methods

       add( $id ) : $mapping
           * Accepts $id as string

           * Translates $id to directory path

           * Creates directory if necessary

           * Returns HASH with keys "_id" and "_path"

           This method should throw an Catmandu::Error when it detects an invalid id.

           It should either return the mapping or throw an error.

       get( $id ) : $mapping
           * Accepts $id as string

           * Translates $id to directory path

           * Returns HASH with keys "_id" and "_path", if a path exists for $id

           This method should throw an Catmandu::Error when it detects an invalid id.

           Difference with method "add":

           * no directory created

           * no mapping returned if no existing directory could be found

       delete ( $id )
           * Accepts id as string

           * Translates id to directory

           * Removes directory if it exists

           * Do other internal cleanup actions if any required

           This method should throw an Catmandu::Error when at failure.

       delete_all()
           * Deletes files/directories in base_dir. Please keep the base_dir.

           * Do other internal cleanup actions if any required

           This method should throw an Catmandu::Error when at failure.

       generator()
           Inherited requirement from Catmandu::Iterable:

           * return function reference

           * every call to this function must return the next directory entry in the index as a
           HASH with keys "_id" and "path"

INHERITED METHODS

       This Catmandu::DirectoryIndex inherits:

       Catmandu::Iterable
          So all functions from Catmandu::Iterable are available to these objects.

SEE ALSO

       Catmandu::Store::File::Simple , Catmandu::DirectoryIndex::UUID ,
       Catmandu::DirectoryIndex::Number , Catmandu::DirectoryIndex::Map