NAME

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

VERSION

       This document describes Hash::FieldHash version 0.15.

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.

perl v5.38.2                                       2024-04-01                               Hash::FieldHash(3pm)