Hey::Cache - Cache data multiple data structures

Hey-Cache documentation Contained in the Hey-Cache distribution.

Index

Code Index:

NAME

Top

Hey::Cache - Cache data multiple data structures

SYNOPSIS

Top

  use Hey::Cache;

  my $cache = Hey::Cache->new(
      Namespace => 'WeatherApp2000',		# string (optional, default='default')
      CacheFile => 'fun_cache_file.xml',	# file path and name (optional, default='cache.xml')
      AutoSync => 1,				# boolean (optional, default=1)
      Expires => 300, 				# seconds (optional, default=86400)
  );

  $cache->set(
      Name => '98501',				# sets the name/key of the piece of data
      Value => { Temperature => 17,		# sets the data that you wish to cache
		 Condition => 'Rain',
		 High => 19,
		 Low => 7 },
      Expires => 600, 				# optional, defaults to what was set in the constructor above
  );

  $value = $cache->get( Name => '98501' ); 	# returns what you had set

  ... enough time passes (at least 10 minutes, according to the "Expires" value) ...

  $value = $cache->get( Name => '98501' ); 	# returns undef because it has expired

  $value = $cache->get( Name => '98501', Expires => 86400 );	# returns what you had set
								# because it is newer than a day

DESCRIPTION

Top

Helps with regular data caching. It's targetted for items that are in hash references, primarly.

new

  my $cache = Hey::Cache->new(
      Namespace => 'WeatherApp2000',		# string (optional, default='default')
      CacheFile => 'fun_cache_file.xml',	# file path and name (optional, default='cache.xml')
      AutoSync => 1,				# boolean (optional, default=1)
      Expires => 300, 				# seconds (optional, default=86400)
  );

Namespace [optional]

Default value is "default".

CacheFile [optional]

Default value is "cache.xml".

AutoSync [optional]

Default value is 1.

Expires [optional]

Default value is 86400 (24 hours).

sync

  $cache->sync;

Sends the data out to file. If AutoSync is disabled (per call or in the constructor), this will manually save out your data to the cache file. If AutoSync is enabled, this will happen automatically.

get

  $weather = $cache->get( Name => '98501' );
  $weather = $cache->get( Name => '98501', Expires => 600 ); # override the expiration of the item

Gets the named data from the cache.

Name [required]

The name of the item to return. This name was specified in the $cache->set function.

Expires [optional]

Age in number of seconds that would be acceptable. If the cached item is newer than this value, it will return the item. If the cached item is older than the value, it will return undef.

set

  $value = { Temperature => 14, High => 15, Low => 12 };
  $cache->get( Name => '98501', Value => $value );

Set a value (scalar, hash, etc) by name into the cache.

Name [required]

The name. Name of the item. Use this as a key to get it later with the $cache->get function.

Value [required]

The value. It works best if it's a reference to something, especially a hash.

Sync [optional]

Boolean. Defaults to the value specified in the constructor, which defaults to true.

Timestamp [optional]

Defaults to the current time. If it is useful to set a different timestamp, you can do it here. This value is in epoch seconds.

Expires [optional]

Defaults to the value specified in the constructor. Sets the expiration time for this item. Expiration is stored with each item separately, so you can assign different expirations for different items.

AUTHOR

Top

Dusty Wilson, <hey-cache-module@dusty.hey.nu>

COPYRIGHT AND LICENSE

Top

Copyright (C) 2006 by Dusty Wilson <http://dusty.hey.nu/>

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available.

Hey-Cache documentation Contained in the Hey-Cache distribution. 
package Hey::Cache;

our $VERSION = '0.01';

use Data::DumpXML qw(dump_xml);


sub new {
  my $class = shift;
  my %options = @_;
  my $self = {};
  bless($self, $class); # class-ify it.

  $self->{cacheFile} = $options{CacheFile} || 'cache.xml'; # define location of cache file
  $self->{autoSync} = (!defined($options{AutoSync}) ? 1 : ($options{AutoSync} ? 1 : 0)); # default to true
  $self->{expires} = int($options{Expires}) || 86400; # default to 24 hours
  $self->{namespace} = $options{Namespace} || $options{NameSpace} || 'default'; # which namespace to read/write

  use Data::DumpXML::Parser;
  my $parser = Data::DumpXML::Parser->new( Blesser => sub {} );

  $self->{cache} = {}; # preset to emptiness
  eval { $self->{cache} = $parser->parsefile($self->{cacheFile})->[0] }; # try to load cache file

  return $self;
}


sub sync {
  my $self = shift || return undef;

  my $cacheOut = dump_xml($self->{cache}); # convert hashref data into XML structure
  if ($cacheOut) { # only if cacheOut is valid/existing (wouldn't want to wipe out our only cache with null)
    if (open(CACHEFH, '>'.$self->{cacheFile})) { # overwrite old cache file with new cache file
      print CACHEFH $cacheOut;
      close(CACHEFH);
      return 1;
    }
  }

  return undef;
}


sub get {
  my $self = shift || return undef;
  my %options = @_;

  my $var = $options{Name} || return undef;

  (defined($self->{cache}->{$self->{namespace}})) || ($self->{cache}->{$self->{namespace}} = {}); # make sure this object exists

  my $obj = $self->{cache}->{$self->{namespace}}->{$var}; # get object

  return undef unless $obj; # no obj?  no problem.  your job is your credit!

  my $expires = int($options{Expires}) || $obj->{expires};

  if ($obj->{timestamp} + $expires <= time()) { # if expired
    return undef;
  }

  return $obj->{value}; # return object's value
}


sub set {
  my $self = shift || return undef;
  my %options = @_;

  my $var = $options{Name} || return undef;
  my $value = $options{Value};
  my $doSync = (defined($options{Sync}) ? $options{Sync} : $self->{autoSync});
  my $timestamp = $options{Timestamp} || $options{TimeStamp} || time();
  my $expires = int($options{Expires}) || $self->{expires};

  $self->{cache}->{$self->{namespace}}->{$var} = { # set the object in the cache
      timestamp => $timestamp,
      expires => $expires,
      value => $value,
  };

  $self->sync if $doSync; # write it out to file

  return 1;
}


1;