1Hash::FieldHash(3) User Contributed Perl Documentation Hash::FieldHash(3)
2[](https://travis-ci.org/gfx/p5-Hash-FieldHash)
7
9 Hash::FieldHash - Lightweight field hash for inside-out objects
10
12 This document describes Hash::FieldHash version 0.15.
13
15 use Hash::FieldHash qw(:all);
16 fieldhash my %foo;
18 fieldhashes \my(%bar, %baz);
20 {
22 my $o = Something->new();
23 $foo{$o} = 42;
25 print $foo{$o}; # => 42
27 }
28 # when $o is released, $foo{$o} is also deleted,
29 # so %foo is empty in here.
30 # in a class
32 {
33 package Foo;
34 use Hash::FieldHash qw(:all);
35 fieldhash my %bar, 'bar'; # make an accessor
37 }
38 my $obj = bless {}, 'Foo';
40 $obj->bar(10); # does $bar{$obj} = 10
41
43 "Hash::FieldHash" provides the field hash mechanism which supports the
44 inside-out technique.
45 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 This is a better alternative to "H::U::F" with following features:
51 Simpler interface
53 "Hash::FieldHash" provides a few functions: "fieldhash()" and
54 "fieldhashes()". That's enough.
55 Higher performance
57 "Hash::FieldHash" is faster than "Hash::Util::FieldHash", because
58 its internals use simpler structures.
59 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
67 Exportable functions
68 "fieldhash(%hash, ?$name, ?$package)"
69 Creates a field hash. The first argument must be a hash.
70 Optional $name and $package indicate the name of the field, which
72 will create rw-accessors, using the same name as $name.
73 Returns nothing.
75 "fieldhashes(@hash_refs)"
77 Creates a number of field hashes. All the arguments must be hash
78 references.
79 Returns nothing.
81 "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 Returns $object.
87 "to_hash($object, ?-fully_qualify)"
89 Serializes $object into a hash reference.
90 If the "-fully_qualify" option is supplied , field keys are fully
92 qualified.
93 For example:
95 package MyClass;
97 use FieldHash qw(:all);
98 fieldhash my %foo => 'foo';
100 sub new{
102 my $class = shift;
103 my $self = bless {}, $class;
104 return from_hash($self, @_);
105 }
106 package MyDerivedClass;
108 use parent -norequire => 'MyClass';
109 use FieldHash qw(:all);
110 fieldhash my %bar => 'bar';
112 package main;
114 my $o = MyDerivedClass->new(foo => 10, bar => 20);
116 my $p = MyDerivedClass->new('MyClass::foo' => 10, 'MyDerivedClass::bar' => 20);
117 use Data::Dumper;
119 print Dumper($o->to_hash());
120 # $VAR1 = { foo => 10, bar => 20 }
121 print Dumper($o->to_hash(-fully_qualify));
123 # $VAR1 = { 'MyClass::foo' => 10, 'MyDerived::bar' => 20 }
124
126 Thread support
127 As "Hash::Util::FieldHash" does, "Hash::FieldHash" fully supports
128 threading using the "CLONE" method.
129 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
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 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 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 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 For example:
158 my $o = YourClass->new();
160 $o->foo(42); # returns $o itself
161 my $value = $o->foo(); # retuns 42
162
164 Perl 5.8.5 or later, and a C compiler.
165
167 No bugs have been reported.
168 Please report any bugs or feature requests to the author.
170
172 Hash::Util::FieldHash.
173 Hash::Util::FieldHash::Compat.
175 "Magic Virtual Tables" in perlguts.
177 Class::Std describes the inside-out technique.
179
181 Fuji, Goro (gfx) <gfuji(at)cpan.org>.
182
184 Copyright (c) 2009-2010, Fuji, Goro. All rights reserved.
185 This library is free software; you can redistribute it and/or modify it
187 under the same terms as Perl itself.
188perl v5.32.1 2021-01-27 Hash::FieldHash(3)
