Historical(3pm)

✨ Historical — Cache::Historical ✨

okay bestie, gather round 💖 this is a User Contributed Perl Documentation page for the module Cache::Historical, and it does exactly what it says on the tin: it caches historical values. no cap.

---

🌸 NAME 🌸

Cache::Historical — literally just: cache historical values. iconic behavior tbh.

---

🎀 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 );

like… it's giving "I remember everything" and honestly? slay 💅

---

🦋 DESCRIPTION 🦋

so Cache::Historical caches historical values, indexed by key and date. think 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

and then you can store those in Cache::Historical like this:

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, bestie:

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

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

and here's the part where it gets ✨main character energy✨: 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" );

like it's literally reaching back in time for you. obsessed 🫶

---

💜 Methods 💜

💅 new()

creates the object, queen. it 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. no sharing, babe, that's the rule 🙈

💅 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();

⚠️ bestie. $cache->clear(); with no args wipes the entire cache. that's not a vibe check, that's a vibe nuke. proceed accordingly 💀

💅 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.

(translation: it's free, it's Perl-licensed, go wild 🎀)

---

🌈 AUTHOR 🌈

2007, Mike Schilli <cpan@perlmeister.com>

---

okay that's the whole page, you ate it up, you understood it, periodt 💖 this was Historical(3pm) from perl v5.36.0, dated 2022-12-10 — thanks for coming to my ted talk, mwah 🦋✨