view release on metacpan or  search on metacpan

lib/Tie/ShadowHash.pm  view on Meta::CPAN

##############################################################################
# Module return value and documentation
##############################################################################

# Make sure the module returns true.
1;

__DATA__

=head1 NAME

Tie::ShadowHash - Merge multiple data sources into a hash

=for stopwords
DBM Allbery

=head1 SYNOPSIS

    use Tie::ShadowHash;
    use AnyDBM_File;
    use Fcntl qw(O_RDONLY);
    tie(my %db, 'AnyDBM_File', 'file', O_RDONLY, oct('666'));
    my $obj = tie(my %hash, 'Tie::ShadowHash', \%db, 'otherdata.txt');

    # Accesses search %db first, then the hashed otherdata.txt.
    print "$hash{key}\n";

    # Changes override data sources, but don't change them.
    $hash{key} = 'foo';
    delete $hash{bar};

    # Add more data sources on the fly.
    my %extra = (fee => 'fi', foe => 'fum');
    $obj->add(\%extra);

    # Add a text file as a data source, taking the first "word" up
    # to whitespace on each line as the key and the rest of the line
    # as the value.
    my $split = sub { my ($line) = @_; split(q{ }, $line, 2) };
    $obj->add([text => "pairs.txt", $split]);

    # Add a text file as a data source, splitting each line on
    # whitespace and taking the first "word" to be the key and an
    # anonymous array consisting of the remaining words to be the
    # data.
    $split = sub { my ($line) = @_; split(q{ }, $line) };
    $obj->add([text => "triples.txt", $split]);

=head1 DESCRIPTION

This module merges together multiple sets of data in the form of hashes into a
data structure that looks to Perl like a single simple hash.  When that hash
is accessed, the data structures managed by that shadow hash are searched in
order they were added for that key.  This allows the rest of a program simple
and convenient access to a disparate set of data sources.

The shadow hash can be modified, and the modifications override the data
sources, but modifications aren't propagated back to the data sources.  In
other words, the shadow hash treats all data sources as read-only and saves
your modifications in an overlay in memory.  This lets you make changes to the
shadow hash and have them reflected later in your program without affecting
the underlying data in any way.  This behavior is the reason why it is called
a shadow hash.

=head1 Constructing the hash

Tie::ShadowHash takes one or more underlying data sources as additional
arguments to tie().  Data sources can also be added later by calling the add()
method on the object returned by tie().

A data source can be anything that looks like a hash.  This includes other
tied hashes, so you can include DB and DBM files as data sources for a shadow
hash.

If the data source is a scalar string instead of a hash reference,
Tie::ShadowHash will treat that string as a file name and construct a hash
from it.  Each chomped line of the file will be a key, and the number of times
that line is seen in the file will be the corresponding value.

Tie::Shadowhash also supports special tagged data sources that can take
options specifying their behavior.  Tagged data sources are distinguished from
normal data sources by passing them to tie() or add() as an array reference.
The first element is the data source tag and the remaining elements are
arguments for that data source.  The following tagged data sources are
supported:

=over 4

=item C<text>

The arguments must be the file name of a text file and a reference to a sub.
The sub is called for every line of the file, with that line as an argument,
and is expected to return a list.  The first element of the list will be the
key, and the second and subsequent elements will be the value or values.  If
there is more than one value, the value stored in the hash and associated with
that key is an anonymous array containing all of them.  See the usage summary
above for examples.

=back

=head1 Clearing the hash

If the shadow hash is cleared by assigning the empty list to it, calling
CLEAR(), or some other method, all data sources are dropped from the shadow
hash.  There is no other way of removing a data source from a shadow hash
after it's been added (you can, of course, always untie the shadow hash and
dispose of the underlying object if you saved it to destroy the shadow hash
completely).

=head1 INSTANCE METHODS

=over 4

=item add(SOURCE [, SOURCE ...])

Adds the given sources to an existing shadow hash.  This method can be called
on the object returned by the initial tie() call.  It takes the same arguments
as the initial tie() and interprets them the same way.

=back