######################################################################
   Cache::Historical 0.05
######################################################################

NAME
   Cache::Historical - Cache historical values

SYNOPSIS
       use Cache::Historical;

       my $cache = Cache::Historical->new();

          # Set a key's value on a specific date
       $cache->set( $dt, $key, $value );

          # Get a key's value on a specific date
       my $value = $cache->get( $dt, $key );

          # Same as 'get', but if we don't have a value at $dt, but we
          # do have values for dates < $dt, return the previous
          # historic value.
       $cache->get_interpolated( $dt, $key );

DESCRIPTION
   Cache::Historical caches historical values by key and date. If you have
   something like historical stock quotes, for example

       2008-01-02 msft 35.22
       2008-01-03 msft 35.37
       2008-01-04 msft 34.38
       2008-01-07 msft 34.61

   then you can store them in Cache::Historical like

       my $cache = Cache::Historical->new();

       my $fmt = DateTime::Format::Strptime->new(
                     pattern => "%Y-%m-%d");

       $cache->set( $fmt->parse_datetime("2008-01-02"), "msft", 35.22 );
       $cache->set( $fmt->parse_datetime("2008-01-03"), "msft", 35.37 );
       $cache->set( $fmt->parse_datetime("2008-01-04"), "msft", 34.38 );
       $cache->set( $fmt->parse_datetime("2008-01-07"), "msft", 34.61 );

   and retrieve them later by date:

       my $dt = $fmt->parse_datetime("2008-01-03");

         # Returns 35.37
       my $value = $cache->get( $dt, "msft" );

   Even if there's no value available for a given date, but there are
   historical values that predate the requested date, "get_interpolated()"
   will return the next best historical value:

       my $dt = $fmt->parse_datetime("2008-01-06");

         # Returns undef, no value available for 2008-01-06
       my $value = $cache->get( $dt, "msft" );

         # Returns 34.48, the value for 2008-01-04, instead.
       $value = $cache->get_interpolated( $dt, "msft" );

 Methods
   new()
       Creates the object. Takes the SQLite file to put the date into as an
       additional parameter:

           my $cache = Cache::Historical->new(
               sqlite_file => "/tmp/mydata.dat",
           );

       The SQLite file defaults to

           $HOME/.cache-historical/cache-historical.dat

       so if you have multiple caches, you need to use different SQLite
       files.

   time_range()
              # List the time range for which we have values for $key
           my($from, $to) = $cache->time_range( $key );

   keys()
              # List all keys
           my @keys = $cache->keys();

   values()
              # List all the values we have for $key, sorted by date
              # ([$dt, $value], [$dt, $value], ...)
           my @results = $cache->values( $key );

   clear()
              # Remove all values for a specific key
           $cache->clear( $key );

              # Clear the entire cache
           $cache->clear();

   last_update()
              # Return a DateTime object of the last update of a given key
           my $when = $cache->last_update( $key );

   since_last_update()
              # Return a DateTime::Duration object since the time of the last
              # update of a given key.
           my $since = $cache->since_last_update( $key );

LEGALESE
   Copyright 2007-2011 by Mike Schilli, all rights reserved. This program
   is free software, you can redistribute it and/or modify it under the
   same terms as Perl itself.

AUTHOR
   2007, Mike Schilli <[email protected]>