NAME

Tie::StrictHash - A hash with 'strict'-like semantics

SYNOPSIS

use Tie::StrictHash;

strict_hash %hash, key => value, ...;

$hashctl = tie %hash, 'Tie::StrictHash', key => value , ...;

$hashctl->add(key => value, ...);

@values = $hashctl->delete(key, ...);

$hashctl->clear;

DESCRIPTION

Tie::StrictHash is a module for implementing some of the same semantics for hash members that 'use strict' gives to variables. The following constraints are applied to a strict hash:

o: No new keys may be added to the hash except through the add method of the hash control object.
o: No keys may be deleted except through the delete method of the hash control object.
o: The hash cannot be re-initialized (cleared) except through the clear method of the hash control object.
o: Attempting to retrieve the value for a key that doesn't exist is a fatal error.
o: Attempting to store a value for a key that doesn't exist is a fatal error.

In order to make any changes or modifications to the hash, you must either keep the return value from strict_hash (or tie) or retrieve it by using tied I<%hash>. Think of it as the ``key'' that ``unlocks'' the hash so that you can make changes to it.

The original reason for writing this module was for classes that implement an object as a hash, using hash members as instance variables. It's all too easy to use the wrong member name, with the same results as misspelling a variable name when use strict isn't in effect.

Note that just as use strict allows you to create new variables by either specifying an explicit package name or by using use vars, a strict hash allows you to create or delete members by using the appropriate methods. However, it does prevent you from creating or deleting members accidentally. This is in keeping with the general philosophy of Perl.

If you import the pseudo-symbol warn, Tie::StrictHash will only issue warning messages rather than dying when an attempt is made to reference a hash value that doesn't exist.

If you import the pseudo-symbol confess, either by itself or along with warn, you'll get a stack backtrace as well when something happens.

DEFINING A STRICT HASH

Use the strict_hash subroutine, or call tie directly. The new method is provided to create a strict anonymous hash. This is both a hash reference and its own hash control object.

$hashctl = strict_hash %hash, key => value, ...;: This routine is exported by default, and simply performs the tie statement listed next. However, it also preserves the original contents of %hash, while calling tie directly does not. However, if you call untie %hash, anything added since the call to strict_hash is lost and only the original contents will remain.
$hashctl = tie %hash, 'Tie::StrictHash', key => value , ...;: Sets %hash as a 'strict' hash, and defines its initial contents. The returned value $hashctl is used to make any modifications to the hash. The original contents of the hash are lost when you call tie directly (although they come back if you untie the hash later).

METHODS

Except for new, these must be invoked by using the $hashctl object. This is returned by strict_hash or tie, or may be retrieved by using tied I<%hash> at any time.

$hashref = new Tie::StrictHash key => value, ...;: Creates a new anonymous strict hash with the specified members as its initial contents. The hash reference is both a reference to the hash and the hash control object. It's possible to define an object with its 'instance variables' implemented in terms of a strict hash, provided that the object inherits from Tie::StrictHash...in this case, the object and its underlying hash would effectively belong to different classes! This works because bless applies to the reference, while tie applies to the actual thingy.
$hashctl->add(key => value, ...);: Adds the specified keys and values to %hash.
@values = $hashctl->delete(key, ...);: Deletes the named key(s) from %hash and returns them in @values. They appear in @values in the same order as the keys are specified in the method call.
$hashctl->clear;: Clears the entire hash.

EXAMPLES

To create a hash with just three members in it that can't be added to except by using the add method:

    use Tie::StrictHash;
    use strict;
    use vars qw(%hash $hashctl);


    $hashctl = strict_hash %hash,
        member1 => 'a', member2 => 'b', member3 => 'c';


    print $hash{member1}, "\n";     ## prints "a"
    print $hash{member4}, "\n";     ## gives error!


    $hash{member2} = 'C';           ## OK
    $hash{member4} = 'D';           ## gives error


    ## BUT...


    $hashctl->add(member4 => 'D');  ## Adds new member to hash


    print $hash{member4}, "\n";     ## prints "D"
    $hash{member4} = 'd';           ## OK

To define an object that uses a strict hash to hold its instance variables:

    package StrictObject;
    use Tie::StrictHash;
    use strict;
    use vars qw(@ISA);
    @ISA = qw(Tie::StrictHash);


    sub new {
        my $class = shift;
        ##
        ## Create strict hash and define object variables
        ##
        my $obj = new Tie::StrictHash var1 => 1, var2 => 'A';
        ##
        ## Then bless it into the proper class.
        ##
        return bless $obj, $class;
    }


    package main;


    use vars qw($obj);


    $obj = new StrictObject;


    print ref $obj, "\n";           ## prints "StrictObject"
    print tied %$obj, "\n";         ## prints "Tie::StrictHash=HASH(...)"

DIAGNOSTICS

These are all fatal errors unless the pseudo-symbol warn was imported on the use Tie::StrictHash line.

odd number of elements passed to add

Self-explanatory.

invalid attempt to clear strict hash

A statement such as

    %hash = ();

was attempted. This is not allowed. Use the clear method.

key 'key' does not exist

An attempt was made to access or modify a key that doesn't exist.

invalid attempt to delete key 'key'

A statement such as

    delete $hash{'key'};

was executed. You must use the delete method to delete from a strict hash.

AUTHOR

Kevin Michael Vail <kevin@vaildc.net>

Tie::StrictHash - A hash with 'strict'-like semantics