藤 吾郎 > Hash-FieldHash > Hash::FieldHash

Download:
Hash-FieldHash-0.12.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.12   Source   Latest Release: Hash-FieldHash-0.14

NAME ^

Hash::FieldHash - Lightweight field hash for inside-out objects

VERSION ^

This document describes Hash::FieldHash version 0.12.

SYNOPSIS ^

        use Hash::FieldHash qw(:all);

        fieldhash my %foo;

        fieldhashes \my(%bar, %baz);

        {
                my $o = Something->new();

                $foo{$o} = 42;

                print $foo{$o}; # => 42
        }
        # when $o is released, $foo{$o} is also deleted,
        # so %foo is empty in here.

        # in a class
        {
                package Foo;
                use Hash::FieldHash qw(:all);

                fieldhash my %bar, 'bar'; # make an accessor
        }

        my $obj = bless {}, 'Foo';
        $obj->bar(10); # does $bar{$obj} = 10

DESCRIPTION ^

Hash::FieldHash provides the field hash mechanism which supports the inside-out technique.

You may know Hash::Util::FieldHash. It's a very useful module, but too complex to understand the functionality and only available in 5.10. H::U::F::Compat is available for pre-5.10, but it is too slow to use.

This is a better alternative to H::U::F with following features:

Simpler interface

Hash::FieldHash provides a few functions: fieldhash() and fieldhashes(). That's enough.

Higher performance

Hash::FieldHash is faster than Hash::Util::FieldHash, because its internals use simpler structures.

Relic support

Although Hash::FieldHash uses a new feature introduced in Perl 5.10, the uvar magic for hashes described in "GUTS" in Hash::Util::Fieldhash, it supports Perl 5.8 using the traditional tie-hash layer.

INTERFACE ^

Exportable functions

fieldhash(%hash, ?$name, ?$package)

Creates a field hash. The first argument must be a hash.

Optional $name and $package indicate the name of the field, which will create rw-accessors, using the same name as $name.

Returns nothing.

fieldhashes(@hash_refs)

Creates a number of field hashes. All the arguments must be hash references.

Returns nothing.

from_hash($object, \%fields)

Fills the named fields associated with $object with %fields. The keys of %fields can be simple or fully qualified.

Returns $object.

to_hash($object, ?-fully_qualify)

Serializes $object into a hash reference.

If the -fully_qualify option is supplied , field keys are fully qualified.

For example:

        package MyClass;
        use FieldHash qw(:all);

        fieldhash my %foo => 'foo';

        sub new{
                my $class = shift;
                my $self  = bless {}, $class;
                return from_hash($self, @_);
        }

        package MyDerivedClass;
        use parent -norequire => 'MyClass';
        use FieldHash qw(:all);

        fieldhash my %bar => 'bar';

        package main;

        my $o = MyDerivedClass->new(foo => 10, bar => 20);
        my $p = MyDerivedClass->new('MyClass::foo' => 10, 'MyDerivedClass::bar' => 20);

        use Data::Dumper;
        print Dumper($o->to_hash());
        # $VAR1 = { foo => 10, bar => 20 }

        print Dumper($o->to_hash(-fully_qualify));
        # $VAR1 = { 'MyClass::foo' => 10, 'MyDerived::bar' => 20 }

ROBUSTNESS ^

Thread support

As Hash::Util::FieldHash does, Hash::FieldHash fully supports threading using the CLONE method.

Memory leaks

Hash::FieldHash itself does not leak memory, but it may leak memory when you uses hash references as field hash keys because of an issue of perl 5.10.0.

NOTES ^

The type of field hash keys

Hash::FieldHash accepts only references and registered addresses as its keys, whereas Hash::Util::FieldHash accepts any type of scalars.

According to "The Generic Object" in Hash::Util::FieldHash, Non-reference keys in H::U::F are used for class fields. That is, all the fields defined by H::U::F act as both object fields and class fields by default. It seems confusing; if you do not want them to be class fields, you must check the type of $self explicitly. In addition, these class fields are never inherited. This behavior seems problematic, so Hash::FieldHash restricts the type of keys.

The ID of field hash keys

While Hash::Util::FieldHash uses refaddr as the IDs of field hash keys, Hash::FieldHash allocates arbitrary integers as the IDs.

What accessors return

The accessors fieldhash() creates are chainable accessors. That is, it returns the $object (i.e. $self) with a parameter, where as it returns the $value without it.

For example:

    my $o = YourClass->new();
    $o->foo(42);           # returns $o itself
    my $value = $o->foo(); # retuns 42

DEPENDENCIES ^

Perl 5.8.5 or later, and a C compiler.

BUGS ^

No bugs have been reported.

Please report any bugs or feature requests to the author.

SEE ALSO ^

Hash::Util::FieldHash.

Hash::Util::FieldHash::Compat.

"Magic Virtual Tables" in perlguts.

Class::Std describes the inside-out technique.

AUTHOR ^

Fuji, Goro (gfx) <gfuji(at)cpan.org>.

LICENSE AND COPYRIGHT ^

Copyright (c) 2009-2010, Fuji, Goro. All rights reserved.

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

syntax highlighting: