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