Aldo Calpini > Tie-AliasHash-1.01 > Tie::AliasHash

Download:
Tie-AliasHash-1.01.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.01   Source  

NAME ^

Tie::AliasHash - Hash with aliases key (multiple keys, one value)

SYNOPSIS ^

  use Tie::AliasHash;

  tie %hash, 'Tie::AliasHash';
        
  $hash{ 'foo', 'bar' } = 'baz';
        
  print $hash{foo}; # prints 'baz'
  print $hash{bar}; # prints 'baz' too

  $hash{bar} = 'zab'; # $hash{foo} is changed too
  print $hash{foo}; # prints 'zab'

DESCRIPTION ^

Tie::AliasHash creates hashes that can have multiple keys for a single value. This means that some keys are just 'aliases' for other keys.

The example shown in the synopsys above creates a key 'foo' and an alias key 'bar'. The two keys share the same value, so that fetching either of them will always return the same value, and storing a value in one of them will change both.

The only difference between the two keys is that 'bar' is not reported by keys() and each():

  use Tie::AliasHash;
  tie %hash, 'Tie::AliasHash';
  tied(%hash)->add_alias( 'foo', 'bar' );
  foreach $k (keys %hash) { print "$k\n"; } # prints 'foo'

To get the 'real' keys and the aliases together, use the allkeys function:

  use Tie::AliasHash;
  tie %hash, 'Tie::AliasHash';
  tied(%hash)->add_alias( 'foo', 'bar' );
  foreach $k (tied(%hash)->allkeys) { print "$k\n"; } # prints 'foo' and 'bar'

You can create alias keys with 3 methods:

EXPORT

None by default. You can optionally export the allkeys function to your main namespace, so that it can be used like the builtin keys.

  use Tie::AliasHash 'allkeys';
  tie %hash, 'Tie::AliasHash';
  foreach $k (allkeys %hash) { print "$k\n"; }

But see CAVEATS below for important information about allkeys.

METHODS

add_alias( KEY, ALIAS, [ALIAS, ALIAS, ...] )

Add one or more ALIAS for KEY. If KEY itself is an alias, the aliases are added to the real key which KEY points to.

aliases( KEY )

Returns a list of all the aliases defined for KEY. If KEY itself is an alias, returns the real key pointed by KEY, as well as any other alias (thus excluding KEY itself) it has.

allkeys

Returns all the (real) keys of the hash, as well as all the aliases.

is_alias( KEY )

Returns true if the specified KEY is an alias, false otherwise (either if KEY does not exists in the hash, or it is a real key).

is_key( KEY )

Returns true if the specified KEY is a real key, false otherwise (either if KEY does not exists in the hash, or it is an alias for another key).

remove( KEY )

Remove KEY from the hash: if KEY is a real key, it is removed with all its aliases. If KEY is an alias, only the alias is removed. This is different from the builtin delete, see CAVEATS below.

remove_alias( ALIAS )

Removes the specified ALIAS from its real key. ALIAS is no longer an alias and can be assigned its own value. The real key which ALIAS used to point to is left unchanged.

remove_aliases( KEY )

Removes all the aliases defined for KEY.

remove_jolly( )

Removes the 'jolly' key from the hash. Operations on non-existant keys are restored to normality.

set_jolly( KEY )

Sets the 'jolly' key to KEY. When you set a jolly key, all fetch and store operations on non-existant keys will be done on KEY instead.

CAVEATS ^

This module can generate a wonderful amount of confusion if not used properly. The package should really have a big 'HANDLE WITH CARE' sticker on it. Other than paying special attention to what you're doing, you should be aware of the following subtlenesses:

HISTORY ^

v1.01 (26 Jun 2003)

Fixed a bug in the EXISTS sub, now works as documented (thanks wk)

v1.00 (07 Mar 2001)

First released version

v0.01 (20 Feb 2001)

Original version; created by h2xs 1.20 with options

  -CAXn Tie::AliasHash

AUTHOR ^

Aldo Calpini <dada@perl.it>

syntax highlighting: