package Class::DataStore;
=pod
=head1 NAME
Class::DataStore - Generic OO data storage/retrieval
=head1 SYNOPSIS
my %values = ( one => 1, two => 2 );
my $store = Class::DataStore->new( \%values );
# using get/set methods
$store->set( 'three', 3 );
my $three = $store->get( 'three' );
# using AUTOLOAD method
$store->four( 4 );
my $four = $store->four;
my @four = $store->four; # returns a list
my $exists = $store->exists( 'three' ); # $exists = 1
my $data_hashref = $store->dump;
$store->clear;
=head1 DESCRIPTION
Class::DataStore implements a simple storage system for object data. This data
can be accessed via get/set methods and AUTOLOAD. AUTOLOAD calls are not added
to the symbol table, so using get/set will be faster. Using AUTOLOAD also means
that you will not be able to store data with a key that is already used by a
instance method, such as "get" or "exists".
This module was written originally as part of a website framework that was used
for the Democratic National Committee website in 2004. Some of the
implementations here, such as get() optionally returning a list if called in
array context, reflect the way this module was originally used for building web
applications.
Class::DataStore is most useful when subclassed. To preserve the AUTOLOAD
functionality, be sure to add the following when setting up the subclass:
use base 'Class::DataStore';
*AUTOLOAD = \&Class::DataStore::AUTOLOAD;
This module is also a useful add-on for modules that need quick and simple data
storage, e.g. to store configuration data:
$self->{_config} = Class::Datastore->new( $config_data );
sub config { return $_[0]->{_config}; }
my $server = $self->config->server;
my $sender = $self->config->get( 'sender' );
=head1 METHODS
=cut
use 5.006;
use strict;
use warnings;
our $AUTOLOAD;
our $VERSION = '0.07';
=pod
=head2 new( $data_hashref )
The $data_hashref is stored in $self->{_data}. Returns the blessed object.
=cut
sub new {
my $class = shift;
my $data = shift || {};
my $self = bless { _data => $data }, $class;
return $self;
}
=pod
=head2 exists( $key )
Returns 1 if the $key exists in the $self->{_data} hashref. Otherwise, returns
0.
=cut
sub exists {
my $self = shift;
my $key = shift;
return 1 if exists $self->{_data}->{$key};
return 0;
}
=pod
=head2 get( $key )
Returns the value of $self->{_data}->{$key}, or undef.
If the value is stored as an ARRAYREF, HASHREF or a scalar, and wantarray is
true, the return value will be a list. Otherwise, the value will be returned
unaltered.
=cut
sub get {
my $self = shift;
my $key = shift;
my $value = $self->{_data}->{$key};
if ( ref $value eq 'ARRAY' ) {
return wantarray ? @$value : $value;
} elsif ( ref $value eq 'HASH' ) {
return wantarray ? %$value : $value;
} elsif ( ref $value eq '' ) {
return wantarray ? ( $value ) : $value;
} else {
return $value;
}
}
=pod
=head2 set( $key => $value )
Sets $self->{_data}->{$key} to $value, and returns $value. Values must be
scalars, including, of course, references.
=cut
sub set {
my $self = shift;
my $key = shift;
my $value = shift;
$self->{_data}->{$key} = $value;
return $value;
}
=pod
=head2 dump()
Returns the $self->{_data} as hashref or hash, depending on the call.
=cut
sub dump {
my $self = shift;
return wantarray ? %{ $self->{_data} } : $self->{_data};
}
=pod
=head2 clear()
Deletes all the keys from $self->{_data}. Returns the number of keys deleted.
=cut
sub clear {
my $self = shift;
my $ct = 0;
foreach my $key ( keys %{ $self->{_data} } ) {
delete $self->{_data}->{$key};
$ct++;
}
return $ct;
}
=pod
=head2 AUTOLOAD()
Tries to determine $key from the method call. Returns $self->{_data}->{$key},
or undef.
=cut
sub AUTOLOAD {
no strict;
if ( $AUTOLOAD =~ /(\w+)$/ ) {
my $key = $1;
my ( $self, $value ) = @_;
if ( @_ == 2 ) {
return $self->set( $key, $value );
} else {
return $self->get( $key );
}
} else {
return;
}
}
sub DESTROY {}
=pod
=head1 AUTHOR
Eric Folley, E<lt>eric@folley.netE<gt>
=head1 COPYRIGHT AND LICENSE
Copyright 2004-2005 by Eric Folley
This library is free software; you can redistribute it and/or modify it under
the same terms as Perl itself.
=cut
1;