NAME

Tie::Hash::Overlay - base class for overlayed hashed

SYNOPSIS

use Tie::Hash::Overlay qw(&overlay);
$a = overlay($arrayref [, $remainder]);
overlay(\%foo, $arrayref [, $remainder]);

DESCRIPTION

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

If the first parameter is a hash reference, it will be tied and returned as the overlayed hash. Otherwise, a new tied hash created within overlay() will be returned.

The $arrayref paramater is a reference to the list of hashes that will be accessed through the overlayed hash. They are searched in order for the variables used in the overlayed hash. If you keep a copy of $arrayref (or manage to figure out where in the object I hid it), you can modify it at run-time to change the layout of the overlayed hash.

Ahh... but what happens if you try to read/write a variable that doesn't exist in any of the hashes you overlay? Fortunatly, Tie::Hash::Overlay has thought of that already. A secret hash is kept that stores these unexpected variables. If you want to have access to those variables, add a $remainder parameter. It should just be an empty hashref (which you keep a copy of).

Tie::Hash::Overlay does not copy the hashes passed to it. Nor does it copy the array ref 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 } ];
overlay(\%a, $hashes);
$b = 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(%{$b});
print "$x\n";		# This prints "a, b, blurfle, foo, what"
$a{b}++;
print "$$b{b}\n";	# This prints 201. Interesting.
push @{$hashes}, { "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? The only things that could be considered annoying is the need to pass a hash to be tied by reference, and having to explicitly tell use to import overlay(). But that last one is a good thing!

On second thought... If two hashes contained the same key in different hashes, each %overlay would see that key twice before reaching the end of the hash.

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

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

TODO

Well, I'm pretty sure I'll need to make some minor modifications to the code in order to support Data::Inherit (which I plan on writing), and any bugs that can be easily fixed probably should be.

AUTHOR

Ashley Winters <jql@accessone.com>

SEE ALSO

perl(1).