view release on metacpan or  search on metacpan

lib/File/Cache/Persistent.pm  view on Meta::CPAN

File::Cache::Persistent - Caches file content and allows to use it even after file is deleted

=head1 SYNOPSIS

    use File::Cache::Persistent;
       
    # Reloading cache if the file was modified
    my $cache = new File::Cache::Persistent;
    say $cache->get('index.html');
    . . . # Some code that modifies the file.
    say $cache->get('index.html');
    
    # Using cached copy forever
    my $cache = new File::Cache::Persistent;
    say $cache->get('index.html');
    unlink 'index.html';
    say $cache->get('index.html');
    
    # Checking if the file was modified after timeout
    my $cache = new File::Cache::Persistent(timeout => 30);
    say $cache->get('index.html');
    sleep 40;
    say $cache->get('index.html');
    
    # Remove the file from cache and then reload it    
    $cache->remove('index.html');
    say $cache->get('index.html');
    
    # Learn out what was used
    say $cache->get('index.html');
    warn "Used cached version"
        if $cache->status | $File::Cache::Persistent::CACHE;
    warn "Used cached version but the file is deleted"
        if $cache->status | $File::Cache::Persistent::CACHE
        && $cache->status | $File::Cache::Persistent::NO_FILE;
        
    # Using custom data provider
    my $cache = new File::Cache::Persistent(reader => \&my_reader);
    . . .
    sub reader {
        my $file_path = shift;
        # Read the file, analyse its content
        # and return something that should be cached
        return $data;
    }

=head1 ABSTRACT

File::Cache::Persistent caches file content, controls if the files are changed,
ignores any changes withing predefined timeout and allows to use cache for
files which were removed after entering the cache.

=head1 DESCRIPTION

This module aims to put caching logic to the background and avoid manually
checking conditions of cache expiration. It also is useful when files are not
available after cache timeout and provides cached version although it is
inevitably outdated.

Access to the data is granted through C<get> method. It transparently reads the
file and caches it if it is needed. By default, raw content of the file is
put to the cache. 

=head2 new

Constructor C<new> creates an instance of caching object. It accepts three
named parameters, each of them are optional.

    my $default_cache = new File::Cache::Persistent(
        prefix  => '/www/data/xsl',
        timeout => 30,
        reader  => \&custom_reader
    );

C<prefix> parameter defines a directory where files will be looked for. By
default it is assumed that files are located in the current directory.

C<timeout> specifies how long the instance uses pure cache and makes no attempt
to check whether the file is modified. During that period every call of
C<get> method returns data stored in cache (excluding the first call when
the cache is empty).

C<reader> allows to replace default routine of reading the file. Default
behaviour is getting anyting from (text) file and put it to the cache. Reader
replacer may be a subroutine which accepts a filename and returns something to
put to cache. Returning value may not only be the text: it may, for example, be
a reference to an object which was created with the data from file. Note that
file must exists even if the reader is not going to get the data from it.

Here is an example of custom reader subroutine which calculates the square of an
image and returns it in a hash together with image dimentions.

    use Image::Size;
    . . .
    sub image_metrics {
        my $path = shift;        
        my ($width, $height) = imgsize($path);
        return {
            width  => $width,
            height => $height,
            square => $width * $height,
        };
    }

If the reader encounters an error, its explanation may be found by calling
C<reader_error> method.

    my $data = $cache->get('wrong.xml');
    say $cache->reader_error() unless $data;

It is possible to call C<new> with no parameters, which is equivalent to
calling with defaults:

    my $default_cache = new File::Cache::Persistent(
        prefix  => undef,
        timeout => 0,
        reader  => undef
    );

=head2 get