1Hash::FieldHash(3)    User Contributed Perl Documentation   Hash::FieldHash(3)
2
3
4
5[![Build
6Status](https://travis-ci.org/gfx/p5-Hash-FieldHash.svg?branch=master)](https://travis-ci.org/gfx/p5-Hash-FieldHash)
7

NAME

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

VERSION

12       This document describes Hash::FieldHash version 0.15.
13

SYNOPSIS

15               use Hash::FieldHash qw(:all);
16
17               fieldhash my %foo;
18
19               fieldhashes \my(%bar, %baz);
20
21               {
22                       my $o = Something->new();
23
24                       $foo{$o} = 42;
25
26                       print $foo{$o}; # => 42
27               }
28               # when $o is released, $foo{$o} is also deleted,
29               # so %foo is empty in here.
30
31               # in a class
32               {
33                       package Foo;
34                       use Hash::FieldHash qw(:all);
35
36                       fieldhash my %bar, 'bar'; # make an accessor
37               }
38
39               my $obj = bless {}, 'Foo';
40               $obj->bar(10); # does $bar{$obj} = 10
41

DESCRIPTION

43       "Hash::FieldHash" provides the field hash mechanism which supports the
44       inside-out technique.
45
46       You may know "Hash::Util::FieldHash". It's a very useful module, but
47       too complex to understand the functionality and only available in 5.10.
48       "H::U::F::Compat" is available for pre-5.10, but it is too slow to use.
49
50       This is a better alternative to "H::U::F" with following features:
51
52       Simpler interface
53           "Hash::FieldHash" provides a few functions:  "fieldhash()" and
54           "fieldhashes()".  That's enough.
55
56       Higher performance
57           "Hash::FieldHash" is faster than "Hash::Util::FieldHash", because
58           its internals use simpler structures.
59
60       Relic support
61           Although "Hash::FieldHash" uses a new feature introduced in Perl
62           5.10, the uvar magic for hashes described in "GUTS" in
63           Hash::Util::Fieldhash, it supports Perl 5.8 using the traditional
64           tie-hash layer.
65

INTERFACE

67   Exportable functions
68       "fieldhash(%hash, ?$name, ?$package)"
69           Creates a field hash. The first argument must be a hash.
70
71           Optional $name and $package indicate the name of the field, which
72           will create rw-accessors, using the same name as $name.
73
74           Returns nothing.
75
76       "fieldhashes(@hash_refs)"
77           Creates a number of field hashes. All the arguments must be hash
78           references.
79
80           Returns nothing.
81
82       "from_hash($object, \%fields)"
83           Fills the named fields associated with $object with %fields.  The
84           keys of %fields can be simple or fully qualified.
85
86           Returns $object.
87
88       "to_hash($object, ?-fully_qualify)"
89           Serializes $object into a hash reference.
90
91           If the "-fully_qualify" option is supplied , field keys are fully
92           qualified.
93
94           For example:
95
96                   package MyClass;
97                   use FieldHash qw(:all);
98
99                   fieldhash my %foo => 'foo';
100
101                   sub new{
102                           my $class = shift;
103                           my $self  = bless {}, $class;
104                           return from_hash($self, @_);
105                   }
106
107                   package MyDerivedClass;
108                   use parent -norequire => 'MyClass';
109                   use FieldHash qw(:all);
110
111                   fieldhash my %bar => 'bar';
112
113                   package main;
114
115                   my $o = MyDerivedClass->new(foo => 10, bar => 20);
116                   my $p = MyDerivedClass->new('MyClass::foo' => 10, 'MyDerivedClass::bar' => 20);
117
118                   use Data::Dumper;
119                   print Dumper($o->to_hash());
120                   # $VAR1 = { foo => 10, bar => 20 }
121
122                   print Dumper($o->to_hash(-fully_qualify));
123                   # $VAR1 = { 'MyClass::foo' => 10, 'MyDerived::bar' => 20 }
124

ROBUSTNESS

126   Thread support
127       As "Hash::Util::FieldHash" does, "Hash::FieldHash" fully supports
128       threading using the "CLONE" method.
129
130   Memory leaks
131       "Hash::FieldHash" itself does not leak memory, but it may leak memory
132       when you uses hash references as field hash keys because of an issue of
133       perl 5.10.0.
134

NOTES

136   The type of field hash keys
137       "Hash::FieldHash" accepts only references and registered addresses as
138       its keys, whereas "Hash::Util::FieldHash" accepts any type of scalars.
139
140       According to "The Generic Object" in Hash::Util::FieldHash, Non-
141       reference keys in "H::U::F" are used for class fields. That is, all the
142       fields defined by "H::U::F" act as both object fields and class fields
143       by default. It seems confusing; if you do not want them to be class
144       fields, you must check the type of $self explicitly. In addition, these
145       class fields are never inherited.  This behavior seems problematic, so
146       "Hash::FieldHash" restricts the type of keys.
147
148   The ID of field hash keys
149       While "Hash::Util::FieldHash" uses "refaddr" as the IDs of field hash
150       keys, "Hash::FieldHash" allocates arbitrary integers as the IDs.
151
152   What accessors return
153       The accessors "fieldhash()" creates are chainable accessors.  That is,
154       it returns the $object (i.e. $self) with a parameter, where as it
155       returns the $value without it.
156
157       For example:
158
159           my $o = YourClass->new();
160           $o->foo(42);           # returns $o itself
161           my $value = $o->foo(); # retuns 42
162

DEPENDENCIES

164       Perl 5.8.5 or later, and a C compiler.
165

BUGS

167       No bugs have been reported.
168
169       Please report any bugs or feature requests to the author.
170

SEE ALSO

172       Hash::Util::FieldHash.
173
174       Hash::Util::FieldHash::Compat.
175
176       "Magic Virtual Tables" in perlguts.
177
178       Class::Std describes the inside-out technique.
179

AUTHOR

181       Fuji, Goro (gfx) <gfuji(at)cpan.org>.
182
184       Copyright (c) 2009-2010, Fuji, Goro. All rights reserved.
185
186       This library is free software; you can redistribute it and/or modify it
187       under the same terms as Perl itself.
188
189
190
191perl v5.30.1                      2020-01-30                Hash::FieldHash(3)
Impressum