Historical(3pm) 					User Contributed Perl Documentation					   Historical(3pm)

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 <cpan@perlmeister.com>

perl v5.10.1							    2011-04-27							   Historical(3pm)