/ 
Tie-Hash-ImmutableKeys-1.14
River stage zero No dependents
/ Tie::Hash::ImmutableKeys

NAME

Tie::Hash::ImmutableKeys - Perl module to create a HASH where keys are immutable but not the leaf data. It is possible to modify the key by FORCE_STORE or FORCE_DELETE. It is working on all the tree key created (keys and subkeys are immutable).

SYNOPSIS

use Tie::Hash::ImmutableKeys;
use Data::Dumper;


my $z = { aze => 100, tyuiop => 333, qsdfg => 987 };
my $f = { A   => 0,   Z      => 1,   E     => 0, L => $z };
my $a = { a   => 0,   z      => 1,   e     => 1, r => 1, AA => $f };

my $list = {
    S => $a,
    F => $f,
    P => "leaf"
};

## Tie the hash with a list of key and values
tie( my %a, 'Tie::Hash::ImmutableKeys', $list );

## Try to modify a value . If the key is missing this command fail
my $ar = "z" ;
if ( defined( $a{ S }->{ $ar } = 1111 ) )
{
    print "The key is present and data are updated " . Dumper( \%a );

}else
{
    print "The key is NOT present and data are NOT updated " . Dumper( \%a );
}


## Get the object from the tied variable
my $obj = tied( %a );


## force the store over a KEY (or create a new key)
$obj->FORCE_STORE( 'S', { l => 5656565 } );

print "NEW KEY" . Dumper( \%a );


## Now it is possible to use the normal tied hash to modify the data
$a{ S }->{ AA }{ L }{ aze } = "dfsdf";
print "NEW KEY" . Dumper( \%a );


## could not delete normal key
delete $a{ S }->{ AA }{ L }{ aze };
print "NEW KEY" . Dumper( \%a );

## must use the object call to force the delete
$obj->FORCE_DELETE( { 'S' => { AA => { L => 'aze' } } } );
print "NEW KEY after FORCE_DELETE" . Dumper( \%a );

## force the module to exit with an error
tied(%a)->error('exit');

DESCRIPTION

Tie::Hash::ImmutableKeys - Perl module to create a HASH where keys are immutable but not the leaf data. It is possible to modify the key by FORCE_STORE or FORCE_DELETE. It is working on all the tree key created (keys and subkeys are immutable).

  TIEHASH classname, LIST
 	The method invoked by the command "tie %hash, classname". Associates a new hash instance with the specified class. "LIST" would
        represent the structure of the initial hash created.
 
  FORCE_STORE this, key, value
      Store datum value into key for the tied hash this. This call create or averwrite the key(s) if needed
      
  FORCE_DELETE this, key
      Delete the key key from the tied hash this.
  
  There is an exportable function "error" to allow a differrnt way to complain if we try to modify/delete a locked key
  
  use Tie::Hash::ImmutableKeys qw( error );
  
  	my %a;
	tie( %a, 'Tie::Hash::ImmutableKeys', $list );
	tied(%a)->error('exit');
	
  The posible parameter for the error are:
  	croak	this is the default behaviour, the module die if we try to modify a locked key and print some info about the error.
	carp	the module warn if we try to modify a locked key and print some info about the error.
	exit    the module simple exit with a return value of 0
	
   any other value fallback to croak.

SEE ALSO

fields, Hash::Util, Class::PseudoHash

AUTHOR

Fabrice Dulaunoy <fabrice[at]dulaunoy[dot]com>

07 june 2007

COPYRIGHT AND LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.8 or, at your option, any later version of Perl 5 you may have available. Under the GNU GPL2

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Tie::Hash::ImmutableKeys Copyright (C) 2007 DULAUNOY Fabrice. Tie::Hash::ImmutableKeys comes with ABSOLUTELY NO WARRANTY; for details See: http://www.gnu.org/licenses/gpl.html This is free software, and you are welcome to redistribute it under certain conditions;