/ 
Data-StackedHash-0.99
River stage zero No dependents
/ Data::StackedHash

NAME

Data::StackedHash - Stack of PERL Hashes

SYNOPSIS

use Data::StackedHash;

tie %h, Data::StackedHash;

$h{'a'}=1;
$h{'b'}=2;
tied(%h)->push; # put a new hash on the stack
$h{'a'}=3;      # override value of key 'a'
  ...
tied(%h)->pop;  # remove top hash from the stack,
                # $h{'a'} == 1 again

DESCRIPTION

The Data::StackedHash module implements a stack of hashes; the whole stack acts collectively and transparently as a single PERL hash, that is, you can perform the usual operations (fetching/storing values, keys, delete, etc.) on it. All the PERL buitlins which operate on hashes are supported.

Assigning a value to a key, as in $h{'a'}=1, puts the key/value pair into the hash at the top of the stack. Reading a key off the stack of hashes searches the whole stack, from the topmost hash to the bottom one, until it finds a hash which holds some value associated to the given key; returns undef if no match was found.

The built-in functions keys, values, each act on the whole collection of all key/value defined in any hash of the stack.

You can add a hash on top of the stack by the method push, and remove the topmost hash by the method pop.

Clearing a stack of hashes only clears the topmost one: that is,

use Data::StackedHash;
tie %h, Data::StackedHash, {'a'=>1};

# put some hash on top of the stack
tied(%h)->push({'a'=>2}); 

print $h{'a'}; # prints 2

%h = {}; # clear topmost hash

print $h{'a'}; # prints 1

METHODS

push()

The push() method puts a new hash on top of the stack: you can either pass to it a reference to the hash to put on top, or call push() with no arguments, in which case an empty hash is pushed onto the stack.

use Data::StackedHash; 
tie %h, Data::StackedHash;

# put some hash on top of the stack
tied(%h)->push({'a'=>1, 'b'=>2}); 

# put an empty hash on top of the stack
tied(%h)->push;

pop()

The pop() method removes the hash on top of the stack and returns a reference to it; all key/value pairs defined only in that hash are lost.

delete(), delete_all()

A call to the built-in delete will remove only the first-found key, and return the associated value, or undef if no such key was found.

use Data::StackedHash; 
tie %h, Data::StackedHash, { 'a'=>1 };

# put one more hash on top of the stack
tied(%h)->push(); 
$h{'a'}=2;
print "$h{a}\n"; # 2

# delete the topmost occurrence of the 'a' key
delete $h{'a'};
print "$h{a}\n"; # 1

The delete_all method deletes the specified key from all hashes in the stack; it returns the array of values found in the stack, or the empty array if no value was associated with the given key. Values from the topmost stack are first in the returned array.

use Data::StackedHash; 
tie %h, Data::StackedHash, { 'a'=>1 };

# put one more hash on top of the stack
tied(%h)->push(); 
$h{'a'}=2;
print "$h{a}\n"; # 2

# delete all occurrences of the 'a' key
tied(%h)->delete_all('a');
print "$h{a}\n"; # undef

fetch_all(key)

Returns all values associated with the given key; values from topmost hash are first in the returned array.

keys(), values(), each()

The built-in functions keys, values and each operate on the union of all key/value pairs defined in any hash of the stack.

use Data::StackedHash; 
tie %h, Data::StackedHash, { 'a'=>1 };

# put one more hash on top of the stack
tied(%h)->push(); 
$h{'b'}=2;

# print all defined keys
print keys %h; # ab

height()

The height method returns the current height of the stack of hashes.

use Data::StackedHash; 
tie %h, Data::StackedHash, { 'a'=>1 };

# put one more hash on top of the stack
tied(%h)->push(); 

print tied(%h)->height; # prints 2

count(key)

Given a key, the count method returns the number of hashes in which that key is associated to a value.

use Data::StackedHash; 
tie %h, Data::StackedHash, { 'a'=>1 };

# put one more hash on top of the stack
tied(%h)->push({'b'=>2}); 

print tied(%h)->count('a'); # prints 1

SEE ALSO

Data::MultiValuedHash, "delete" in perlfunc, "keys" in perlfunc, "values" in perlfunc, "each" in perlfunc.

AUTHOR

Riccardo Murri, <riccardomurri@yahoo.it>

LICENCE

This package is free software and is provided "as is" without express or implied warranty. It may be used, redistributed and/or modified under the same terms as Perl itself.