view release on metacpan or  search on metacpan

lib/Padre/Cache.pm  view on Meta::CPAN

package Padre::Cache;

=pod

=head1 NAME

Padre::Cache - The Padre Temporary Data Cache API

=head1 DESCRIPTION

B<Padre::Cache> implements a light memory only caching mechanism which is
designed to support GUI objects that need to temporarily store state data.

By providing this caching in a neutral location that is not directly bound
to the user interface objects, the cached data can survive destruction and
recreation of those interface objects.

This is particularly valuable for situations such as a shift in the active
language or the relocation of a tool that would result in interface objects
being rebuilt.

Cache data is stored in a "Stash", which is a C<HASH> reference containing
arbitrary content, and is keyed off a project or document.

=head1 METHODS

=cut

use 5.008;
use strict;
use warnings;
use Params::Util ();

our $VERSION    = '1.02';
our $COMPATIBLE = '0.70';

my %DATA = ();

=pod

=head2 stash

  my $stash = Padre::Cache->stash( 'Padre::Wx::MyClass' => $project );

The C<stash> method fetches the C<HASH> reference stash for a particular key
pair, which consists of a GUI class name and a project or document.

The C<HASH> reference returned can be used directly withouth the need to do
any kind of C<get> or C<set> call to the stash.

Calling C<stash> multiple times is guarenteed to fetch the same C<HASH>
reference.

=cut

sub stash {
	my $class = shift;
	my $owner = shift;
	my $key   = shift;

	# We need an instantiated cache target
	# NOTE: The defined is needed because Padre::Project::Null
	# boolifies to false. In retrospect, that may have been a bad idea.
	if ( defined Params::Util::_INSTANCE( $key, 'Padre::Project' ) ) {
		$key = $key->root;
	} elsif ( Params::Util::_INSTANCE( $key, 'Padre::Document' ) ) {
		$key = $key->filename;
	} else {
		die "Missing or invalid cache key";
	}

	$DATA{$key}->{$owner}
		or $DATA{$key}->{$owner} = {};
}

=pod

=head2 release