1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
\[!\[Build Status\](https://travis-ci.org/gfx/p5-Hash-FieldHash.svg?branch=master)\](https://travis-ci.org/gfx/p5-Hash-FieldHash)
# 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](https://metacpan.org/pod/Hash::Util::Fieldhash#GUTS),
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](https://metacpan.org/pod/Hash::Util::FieldHash#The-Generic-Object),
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](https://metacpan.org/pod/Hash::Util::FieldHash).
[Hash::Util::FieldHash::Compat](https://metacpan.org/pod/Hash::Util::FieldHash::Compat).
["Magic Virtual Tables" in perlguts](https://metacpan.org/pod/perlguts#Magic-Virtual-Tables).
[Class::Std](https://metacpan.org/pod/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.
|
