NAME

Class::Hash - Perl extension for hashes that look like classes

SYNOPSIS

use Class::Hash ALL_METHODS => 1;

$hash = Class::Hash->new(foo => 'bar');

print "foo: ",$hash->foo,"\n"; # prints "foo: bar"

$hash->hello = "World";
print "Hello ",$hash->hello,"!\n"; # prints "Hello World!"

# Other accessor methods
$hash->store("foo", "something else");
$foo = $hash->fetch("foo");

# Or just use it like a plain hash ref!
$stuff->{foo} = "whoa dude!";

ABSTRACT

This component provides a method-based interface to a hash. Occasionally, it's
more convenient to have named methods to access a hash than hash keys. This
module generalizes this behavior.

DESCRIPTION

This component provides a method-based interface to a hash. Occasionally, it's more convenient to have named methods to access a hash than hash keys. This module generalizes this behavior. It tries to work the tied hash interface inside-out.

This module tries to do as much or as little for you as you want and provides a number of configuration options. The options allow you to determine what kind of interface the object has. The interface may also be altered after-the-fact. See "OPTIONS" for details.

METHODS

use Class::Hash [ %default_options ];

When telling Perl to use Class::Hash, you may specify any default options that should be made available. By default, all options are off--giving you the simplest set of features. The default options can be modified per-instance and options can be modified after instantiation via options.

For more information on the options, see "OPTIONS".

$hash = Class::Hash->new( [ %hash ] [, \%options ] )

This initializes a particular "hash". The first list of arguments are the initial key/value pairs to set in the hash. If none are given, the hash is initially empty.

The second argument is also optional. It is a hash reference containing the optiosn to set on this instance of the hash. If not options are given, then the defaults set during import are used. FOr more information on the options, see "OPTIONS".

NB: It should be noted that:

$hash = Class::Hash->new;

is not the same as:

$hash2 = $hash->new;

The first will be treated as a constructor and the second as an accessor.

$value = $hash->accessor [ ($new_value) ]

$value = Class::Hash->accessor [ ($hash, $new_value) ]

This method is the accessor for the hash-key named accessor. This can be any valid Perl symbol and is the simplest way of accessing values in the hash. The current value is returned by the accessor--which is first set to $new_value if specified.

It is possible to disable the named accessor syntax by setting the "no_named_accessors" option. See the "OPTIONS" section for details.

$value = $hash->fetch($name)

$value = Class::Hash->fetch [ ($hash, $new_value) ]

This is the get accessor for the hash key named $name. This fetches the current value stored in $name. This accessor is only available when the "fetch" option is set. See the "OPTIONS" section for details.

$hash->store($name, $new_value)

$hash->store($name) = $new_value

Class::Hash->store($hash, $name, $new_value)

Class::Hash->store($hash, $name) = $new_value

This is the set accessor for the hash key named $name. This sets the current value to be stored in $name. This accessor is only available when the "store" option is set. See the "OPTIONS" section for details.

$old_value = $hash->delete($name)

$old_value = Class::Hash->delete($hash, $name)

Deletes the value associated with the given key $name. This method is only available when the "delete" option is set. See the "OPTIONS" section for details.

$hash->clear

Class::Hash->clear($hash)

Clears all values from the hash. This method is only available when the "clear" option is set. See "OPTIONS" for details.

$hash->exists($name)

Class::Hash->exists($hash, $name)

Determines whether the given hash key has been set--even if it has been set to undef. This method is only available when the "exists" option is set. See "OPTIONS" for details.

($key, $value) = $hash->each

($key, $value) = Class::Hash->each($hash)

Iterates through all pairs in the hash. This method is only available when the "each" option is set. See "OPTIONS" for details.

@keys = $hash->keys

@keys = $hash->keys($hash)

Returns all keys for the hash. This method is only available when the "keys" option is set. See "OPTIONS" for details.

@values = $hash->values

@values = $hash->values($hash)

Returns all values for the hash. This method is only available when the "values" option is set. See "OPTIONS" for details.

$options = Class::Hash->options($hash)

Class::Hash->options($hash)->{option} = $option

This returns the options currently set on the hash. See "OPTIONS" for details.

$options = Class::Hash->defaults

Class::Hash->defaults->{option} = $option

This returns the default options set on the hash. Making changes to the returned value will effect all instances of Class::Hash constructed after the change is made. Any existing instances are not modified.

OPTIONS

There are two types of options that may be set on Class::Hash objects: method options and aggregate options. The method options determine the presence or absence of various methods that may be defined in the Class::Hash object--see "BUGS" because this isn't strictly correct. The aggregate options alter the settings of more than one other options.

METHOD OPTIONS

It should be noted that there are two possible syntaxes for calling most of the Class::Hash methods. The first is the typical object syntax and the other is a class/object syntax. The object syntax is available for all methods but options. However, the object syntax is only available when it is turned on by the matching option. The class/object syntax (always listed second when both are possible) is always available regardless of option settings--but is far less pretty.

no_named_accessors

When set, this option eliminates the use of named accessors. This will result in an exception being raiesed when access is attempted. For example:

$bob = new Class::Hash(foo => 'bar');
$foo = $bob->foo; # works!

$fred = new Class::Hash(bar => 'foo', { no_named_accessors => 1 });
$bar = $fred->bar; ### <--- ERROR! Undefined subroutine &Class::Hash::bar called

fetch

When set, this option adds the use of the fetch accessor.

store

When set, this option adds the use of the store accessor.

delete

When set, this option adds the use of the delete method.

clear

When set, this option adds the use of the clear method.

exists

When set, this option adds the use of the exists method.

each

When set, this option adds the use of the each method.

keys

When set, this option adds the use of the keys method.

values

When set, this option adds the use of the values method.

AGGREGATE OPTIONS

All aggregate option names are in all caps to suggest that you're turning on or off lots of stuff at once. Aggregate options always work one way, they do not have the effect of turning some things on and some stuff off. This would be too confusing.

METHOD_BASED

This option affects the following: no_named_accessors, fetch, store, delete, clear, exists, each, keys, and values.

ALL_METHODS

This option affects the following: fetch, store, delete, clear, exists, each, keys, and values.

BUGS

The nastiest part of this module is the way AUTOLOAD and other methods are made available. All the methods defined that aren't named accessors (such as fetch, store, delete, clear, etc.) are defined as subroutines whether they are "turned on" via options or not. This won't make a difference 99% of the time as the methods Do-The-Right-Thing(tm). However, when attempting to use can, everything will be screwed up.

I would like to modify the system to have the methods only defined per-instance, but that would require the ability to load and unload method definitions on-the-fly per-instance. Something that might be possible, but would require some very odd finagling to achieve it, so I've stuck with the It-Works-For-Me(tm) method or It-Works-If-You-Just-Use-It-And-Don't-Try-To-Be-Funny(tm) method. :-)

Another problem is that this is currently set to require Perl 5.8.0. I don't know if this is really necessary, but I'm too lazy to find out right now. Because of the lvalue attribute set on AUTOLOAD, it does require 5.7.1, which is almost the same as requiring 5.8.0.

There are probably some nasty documentation bugs. I didn't go back through and carefully proofread the documentation after I changed the implementation mid-way through.

AUTHOR

Andrew Sterling Hanenkamp, <hanenkamp@users.sourceforge.net>

COPYRIGHT AND LICENSE

Copyright 2003 by Andrew Sterling Hanenkamp

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.