NAME

Tie::Hash::Easy - Perl module for the simple creation of tied hashes

SYNOPSIS

use Tie::Hash::Easy;

$hash_ref = new Tie::Hash::Easy([ $funcs, \%hash, ... ]);

DESCRIPTION

Tie::Hash::Easy is meant to provide a simple way to create a tied hash without creating a new class, and to allow the simple overriding of the access functions.

The new() function is a simple wrapper to tie(). It's just there for convienience. It passes it's arguments to tie() without any processing. A reference to the newly tied hash is returned. Both parameters are optional.

The first argument should be a hash containing the names of the various hash access functions to be overridden as the keys, and sub-refs to the subroutines to override with as the values.

The second argument should be a HASH ref, and will be tied if passed.

Any other arguments will be passed on to the overridden TIEHASH(), if you provide one.

GUTS

It can't hurt to know what's really going on in this particular module.

TIEHASH() takes one argument, a hash reference that is to be blessed to become the object. The argument is not checked to see what it's values contain, which means you can store interesting stuff in it, which will be kept intact in the object.

The default methods only access two keys in the object, hash and keys. The hash key contains a reference to the hash that is accessed by the default access methods. The keys key is used in the key iteration method to store a list of keys returned by the KEYS() member, which will be explained later.

Every default hash access function can be overridden by passing a hash to new() which contains the function's name as a key, and a reference to the function to be called when the action the function handles occurs.

Only one of the default hash access function prototypes changes when you use it in in this class, and that is TIEHASH(). For the prototypes of the other access functions, see perltie(1).

TIEHASH this, LIST

When this is called, the object has already been created. Any arguments not recognized by new() or the original TIEHASH() are passed as LIST. The return-value from this function is irrelevant and discarded.

Whenever I write a tied hash class, I find myself taking excessive time attempting to write the FIRSTKEY() and NEXTKEY() functions. To save myself, and some of you, alot of time and effort, I've come up with a new KEYS() function.

KEYS this

This function is a substitute for replacing FIRSTKEY() and NEXTKEY(). If it is defined, it must return an reference to an array containing a list of the keys in the object. The list returned is modified. The order of the keys is maintained through the calls to NEXTKEY().

EXAMPLES

Well, I thought I should just toss out a long example of how this class can go a long way towards simplifying the creation of tied hashes.

The following code will probably create an ordered hash.

use Tie::Hash::Easy;

$hash = new Tie::Hash::Easy {
    STORE =>
	sub {
	    my($self, $key, $value) = @_;

	    push @{$$self{'order'}}, $key;
	    $$self{'hash'}{$key} = $value;
	},
    DELETE =>
	sub {
	    my($self, $key) = @_;

	    delete $$self{'hash'}{$key};
	    my $i;
	    for($i = 0; $i < @{$$self{'order'}}; $i++) {
		splice @{$$self{'order'}}, $i, 1
		    if $$self{'order'}[$i] eq $key;
	    }
	},
    KEYS =>
	sub {
	    my $self = shift;

	    return [ @{$$self{'order'}} ];
	}
};

AUTHOR

Ashley Winters <jql@accessone.com>

SEE ALSO

perl(1), perltie(1), perlref(1).