NAME

Tie::Hash::Overlay - Perl module for overlaying hashes

SYNOPSIS

use Tie::Hash::Overlay;
$a = new Tie::Hash::Overlay($hashlist [, $remainder]);

use Tie::Hash::Overlay qw(&overlay);
$a = new Tie::Hash::Overlay($hashlist [, $remainder]);
overlay($a, $hashlist [, $remainder]);

DESCRIPTION

This module provides a standardized method for interfacing multiple hashes through one variable using tie().

The new() function runs tie() transparently on a newly created hash reference, and if given arguments, runs overlay() with whatever arguments are given to it. You are returned a baby hash reference which you can bless into your class, or do any number of cool things with.

The overlay() function is the most important function. It must be explicitly imported into your namespace by adding qw(&overlay) to the arguments of use() if you want to avoid calling it as Tie::Hash::Overlay::overlay().

The first argument must be a reference to the hash being modified. overlay() cannot be a member-function of the hash reference because the reference must be able to be blessed into another class, because that is the main purpose of this whole package.

If the second parameter is a hash reference, it will be pushed to the end of an internal list of overlayed hashes. If the second parameter is an array reference, then each element of the list will be pushed onto the list of overlayed hashes. Note that the first hashes overlayed will have higher priority than the hashes overlayed afterwards.

The optional third argument is a 'catchall' hash reference. If a hash key is accessed which none of the overlayed hashes think exists, a fall-through hash stores that value to make sure it isn't lost. If you want control over that fall-through hash, just pass a reference to the hash you want the unrecognized keys to access. This hash is guaranteed to always be searched last, and can have elements in it when you pass it to overlay(). This can be useful when you want to capture certain accesses to a dbm hash. Just tie() your own hash that captures whatever elements you like, and run *dbm = new Tie::Hash::Overlay($mine, \%dbm); or something equally effective. You probably get the idea.

Tie::Hash::Overlay does not copy the hashes passed to it. Everything is kept completely intact on purpose, in order to allow the programmer the most flexibility. Perhaps you have DBM hash that you want to capture all of the accesses to a certain element? Or maybe you have a diabolical plan to take over the Earth and need to overlay tied hashes in Perl for it to work? It's reasons like that which caused me not to fiddle with what is passed to overlay().

EXAMPLES

Go ahead and consider me a show-off, but I think a little demonstration is in order.

use Tie::Hash::Overlay qw(&overlay);  # import &overlay manually

$hashes = [ { a => 1, b => 200 }, { foo => bar, blurfle => z } ];
*a = new Tie::Hash::Overlay($hashes);
$b = new Tie::Hash::Overlay($hashes);

print "$a{b}\n";		# This prints 200
$$b{what} = 'is that?';
print "what $$b{what}\n";	# This prints "what is that?"
$x = join ", ", sort keys %a;
print "$x\n";		# This prints "a, b, blurfle, foo, what"
$a{b}++;
print "$$b{b}\n";	# This prints 201? Interesting.
overlay($b, { "good guys" => "never win" });
print "$a{good guys}\n";	# Print "never win"

Getting the idea? Basically they're identical to any other hash, except they're extremely different. Makes sense to me.

BUGS

Bugs? If there was a bug, do you think it would exist long enough to be put in here? Having to manually import overlay() is a good thing!

Anyways, the mere fact that this thing has a version-number of 0.02 nearly qualifies as a bug in and of itself.

Oh, and blame any other bugs on tie(). :)

If you actually find a bug, or have a suggestion, go ahead and e-mail me. See the AUTHOR section for my contact address.

AUTHOR

Ashley Winters <jql@accessone.com>

SEE ALSO

perl(1).