blib/lib/Class/Ref.pm

filter: Statementstmt 99.3% 152 / 153 Branchbran 100% 36 / 36 Conditioncond 100% 15 / 15 MC/DCmcdc 100% 10 / 10 Subroutinesub 97.9% 48 / 49 Podpod 100% 1 / 1 totaltotal 99.2% 262 / 264 CC 24 SCAR 10.0
CC
24
Cov
100%
AUTOLOAD
8.0
AUTOLOAD
6.0
__ANON__
5.0
CRAP 2.7
↑ Summary
1 package Class::Ref;
2 8 $Class::Ref::VERSION = '0.06';
3 # ABSTRACT: Automatic OO wrapping of container references
4  
5 =head1 NAME
6  
7 Class::Ref - Automatic OO wrapping of container references
8  
9 =head1 SYNOPSIS
10  
11 $o = Class::Ref->new({ foo => { bar => 'Hello World!' } });
12 $o->foo->bar; # returns "Hello World!"
13 $o->baz({ blah => 123 });
14 $o->baz->blah; # returns 123
15  
16 $o = Class::Ref->new({ foo => [{ bar => 'Hello Again!' }] });
17 $o->foo->[0]->bar; # returns "Hello Again!"
18  
19 =head1 DESCRIPTION
20  
21 L<Class::Ref> provides an OO wrapping layer around Hash and Array references.
22 Part of the magic is that it does this deeply and across array/hash boundaries.
23  
24 =cut
25  
26 8 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
27 8 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
28  
29 8 ▶use Scalar::Util ();
Subroutine BEGIN: called CC=1 SCAR=0.0
30 8 ▶use Carp ();
Subroutine BEGIN: called CC=1 SCAR=0.0
31  
32 =head1 OPTIONS
33  
34 Some of the behavior of the encapsulation can be modified by the following options:
35  
36 =over 4
37  
38 =item B<$raw_access> (Default: 0)
39  
40 $o = Class::Ref->new({ foo => { bar => 1 } });
41 {
42 $Class::Ref::raw_access = 1;
43 $o->foo; # returns { bar => 1 }
44 }
45  
46 Should you ever need to work with the raw contents of the data structure,
47 setting C<$raw_access> with cause every member retrieval to just the referenced
48 data rather than a wrapped form of it.
49  
50 The observant reader will note that this does not provide access to the base
51 data. In order to access that, you must dereference the object:
52  
53 $$o; # returns { foo => { bar => 1 } } unblessed
54  
55 See L<GUTS|/GUTS> for more information.
56  
57 =cut
58  
59 # bypass wrapping and access the raw data structure
60 8 our $raw_access = 0;
61  
62 =item B<$allow_undef> (Default: 0)
63  
64 $o = Class::Ref->new({ foo => { bar => 1 } });
65 {
66 local $Class::Ref::allow_undef = 1;
67 $o->not_here; # returns undef
68 }
69 $o->not_here; # raises exception
70  
71 By default, an exception will be raised if you try to read from a HASH key that is
72 non-existent.
73  
74 =back
75  
76 =cut
77  
78 # instead of raising an exception when accessing a non-existent value,
79 # return 'undef' instead
80 8 our $allow_undef = 0;
81  
82 # disable defaults at your peril
83 8 our %nowrap = map { ($_ => 1) } (
84 'Regexp', 'CODE', 'SCALAR', 'REF', 'LVALUE', 'VSTRING',
85 'GLOB', 'IO', 'FORMAT'
86 );
87  
88 24 ▶my $bless = sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
89 24 my ($class, $ref) = @_;
90 24 ▶ return $ref if $raw_access;
Branch: 1 branch
BranchTrueFalseTotal
if $Class::Ref::raw_access 1 23 24
91 23 my $type = ref $ref;
92 23 return bless \$ref => "$class\::$type";
93 8 };
94  
95 74 ▶my $test = sub {
Subroutine __ANON__: called CC=5 SCAR=16.1
96 74 ▶ return unless $_[0] and ref $_[0];
Branch: 1 branch
BranchTrueFalseTotal
unless $_[0] and ref $_[0] 26 48 74
Condition100%3/3
$_[0] and ref $_[0]
!ll&&!rl&&r
22448
MC/DC100%2/2
$_[0] and ref $_[0]
$_[0] ref $_[0]
Truth table100%3/3
A and B
A= $_[0]B= ref $_[0]
ABresult
0X0
100
111
97 48 ▶ return if Scalar::Util::blessed $_[0];
Branch: 1 branch
BranchTrueFalseTotal
if builtin::blessed($_[0]) 3 45 48
98 45 ▶ return if $nowrap{ ref $_[0] };
Branch: 1 branch
BranchTrueFalseTotal
if $Class::Ref::nowrap{ref $_[0]} 21 24 45
99 24 1;
100 8 };
101  
102 59 ▶my $assign = sub {
Subroutine __ANON__: called CC=3 SCAR=11.0
103 59 my $v = shift;
104 59 ▶ $$v = shift if @_;
Branch: 1 branch
BranchTrueFalseTotal
if @_ 13 46 59
105 59 ▶ return $test->($$v) ? \__PACKAGE__->$bless($$v) : $v;
Branch: 1 branch
BranchTrueFalseTotal
&$test($$v) ? : 17 42 59
106 8 };
107  
108 =head1 METHODS
109  
110 There is only the constructor.
111  
112 =over 4
113  
114 =item B<new>
115  
116 $o = Class::Ref->new({...});
117 $o = Class::Ref->new([...]);
118  
119 Wrap the provided reference in OO getters and setters.
120  
121 =back
122  
123 =cut
124  
125 15 ▶sub new {
Subroutine new: called CC=2 SCAR=6.9
Pod documented
126 15 my ($class, $ref) = @_;
127 15 ▶ Carp::croak "not a valid reference for $class" unless $test->($ref);
Branch: 1 branch
BranchTrueFalseTotal
unless &$test($ref) 8 7 15
128 7 return $class->$bless($ref);
129 }
130  
131 =head1 PHILOSOPHY
132  
133 A lot of effort has been made to ensure that the only code that changes your
134 wrapped data is your code. There is no blessing of any of the data wrapped
135 by L<Class::Ref>.
136  
137 With that being said, the goal has been to reduce the syntax need to access
138 values deep inside a HASH/ARRAY reference.
139  
140 =head1 HASH Refs
141  
142 Wrapping a HASH is a fairly straightforward process. All keys of the hash will
143 be made available as a method call.
144  
145 There is a bit more here however. If, for example, you accessed the actual hash,
146 L<Class::Ref> will still encapsulate the return value if that value is a HASH or
147 an ARRAY:
148  
149 $o = Class::Ref->new({ foo => { bar => 1 } });
150 $o->{foo}->bar; # works
151  
152 But all without modifying, blessing, or otherwise messing with the value. The
153 data referenced with C<$o> remains the same as when it originally wrapped.
154  
155 =cut
156  
157 package Class::Ref::HASH;
158 8 $Class::Ref::HASH::VERSION = '0.06';
159 8 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
160 8 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
161  
162 8 ▶use overload '%{}' => sub {
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=2 SCAR=6.9
163 14 ▶ return ${ $_[0] } if $raw_access;
Branch: 1 branch
BranchTrueFalseTotal
if $Class::Ref::raw_access 1 13 14
164 13 tie my %h, __PACKAGE__ . '::Tie', ${ $_[0] };
165 13 \%h;
166 },
167 8 fallback => 1;
168  
169 8 our $AUTOLOAD;
170  
171 48 ▶sub AUTOLOAD {
Subroutine AUTOLOAD: called CC=6 SCAR=17.9
172 # enable access to $h->{AUTOLOAD}
173 48 ▶ my $name
Branch: 1 branch
BranchTrueFalseTotal
defined $Class::Ref::HASH::AUTOLOAD ? : 46 2 48
174 = defined $AUTOLOAD
175 ? substr($AUTOLOAD, 1 + rindex $AUTOLOAD, ':')
176 : 'AUTOLOAD';
177  
178 # undef so that we can detect if next call is for $h->{AUTOLOAD}
179 # - needed cause $AUTOLOAD stays set to previous value until next call
180 48 undef $AUTOLOAD;
181  
182 # NOTE must do this after AUTOLOAD check
183 # - weird things happen when a wrapped HASH is an element of a wrapped
184 # ARRAY. tie'd ARRAYs have some lvalue magic on their FETCHed values.
185 # As a result, this call to shift triggers the tie object call to FETCH
186 # to ensure the lvalue is still valid.
187 48 my $self = shift;
188  
189 # simulate a fetch for a non-existent key without autovivification
190 48 ▶ unless (exists $$self->{$name} or @_) {
Branch: 1 branch
BranchTrueFalseTotal
unless (exists $$self->{$name} or @_) 14 34 48
Condition100%3/3
exists $$self->{$name} or @_
l!l&&r!l&&!r
31314
MC/DC100%2/2
exists $$self->{$name} or @_
exists $$self->{$name} @_
Truth table100%3/3
A or B
A= exists $$self->{$name}B= @_
ABresult
1X1
011
000
191 14 ▶ return undef if $allow_undef or $name eq 'DESTROY';
Branch: 1 branch
BranchTrueFalseTotal
if $Class::Ref::allow_undef or $name eq "DESTROY" 13 1 14
Condition100%3/3
$Class::Ref::allow_undef or $name eq "DESTROY"
l!l&&r!l&&!r
1121
MC/DC100%2/2
$Class::Ref::allow_undef or $name eq "DESTROY"
$Class::Ref::allow_undef $name eq "DESTROY"
Truth table100%3/3
A or B
A= $Class::Ref::allow_undefB= $name eq "DESTROY"
ABresult
1X1
011
000
192 1 Carp::croak sprintf 'Can\'t locate object method "%s" via package "%s"',
193 $name,
194 ref $self;
195 }
196  
197 # keep this broken up in case I decide to implement lvalues
198 34 my $o = $assign->(\$$self->{$name}, @_);
199 34 $$o;
200 }
201  
202 package Class::Ref::HASH::Tie;
203 8 $Class::Ref::HASH::Tie::VERSION = '0.06';
204 8 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
205 8 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
206  
207 # borrowed from Tie::StdHash (in Tie::Hash)
208  
209 #<<< ready... steady... cross-eyed!!
210 13 ▶sub TIEHASH { bless [$_[1]], $_[0] }
Subroutine TIEHASH: called CC=1 SCAR=0.0
211 1 ▶sub STORE { $_[0][0]->{ $_[1] } = $_[2] }
Subroutine STORE: called CC=1 SCAR=0.0
212 2 ▶sub FETCH { ${ $assign->(\$_[0][0]->{ $_[1] }) } } # magic
Subroutine FETCH: called CC=1 SCAR=0.0
213 2 ▶sub FIRSTKEY { my $a = scalar keys %{ $_[0][0] }; each %{ $_[0][0] } }
Subroutine FIRSTKEY: called CC=1 SCAR=0.0
214 2 ▶sub NEXTKEY { each %{ $_[0][0] } }
Subroutine NEXTKEY: called CC=1 SCAR=0.0
215 2 ▶sub EXISTS { exists $_[0][0]->{ $_[1] } }
Subroutine EXISTS: called CC=1 SCAR=0.0
216 1 ▶sub DELETE { delete $_[0][0]->{ $_[1] } }
Subroutine DELETE: called CC=1 SCAR=0.0
217 1 ▶sub CLEAR { %{ $_[0][0] } = () }
Subroutine CLEAR: called CC=1 SCAR=0.0
218 1 ▶sub SCALAR { scalar %{ $_[0][0] } }
Subroutine SCALAR: called CC=1 SCAR=0.0
219 #>>>
220  
221 =head1 ARRAY Refs
222  
223 Wrapping ARRAYs is much less straightforward. Using an C<AUTOLOAD> method
224 doesn't help because perl symbols cannot begin with a number. Makes it a
225 little difficult to do the following:
226  
227 $o->0; # compile error
228  
229 So for the purpose of this module, wrapped ARRAYs exactly like an ARRAY
230 reference:
231  
232 $o->[0]; # ahh, much better
233  
234 The tricky part comes in wanting to make sure that values returned from such a
235 call would still be wrapped:
236  
237 $o->[0]->foo; # $o = [{ foo => 'bar' }]
238  
239 See L<GUTS|/GUTS> for more discussion on how this is done.
240  
241 I am still debating if adding formal accessor methods would be helpful in
242 this context.
243  
244 =cut
245  
246 package Class::Ref::ARRAY;
247 8 $Class::Ref::ARRAY::VERSION = '0.06';
248 8 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
249 8 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
250  
251 # tie a proxy array around the real one
252 8 ▶use overload '@{}' => sub {
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine __ANON__: called CC=2 SCAR=6.9
253 33 ▶ return ${ $_[0] } if $raw_access;
Branch: 1 branch
BranchTrueFalseTotal
if $Class::Ref::raw_access 2 31 33
254 31 tie my @a, __PACKAGE__ . '::Tie', ${ $_[0] };
255 31 \@a;
256 },
257 8 fallback => 1;
258  
259 2 ▶sub index {
Subroutine index: called CC=2 SCAR=6.9
260 2 my $self = shift;
261 2 ▶ defined(my $i = shift) or Carp::croak "No index given";
Branch: 1 branch
BranchTrueFalseTotal
defined(my $i = shift()) or Carp::croak("No index given") 1 1 2
262 1 ${ $assign->(\$$self->[$i], @_) };
263 }
264  
265 1 ▶sub iterator {
Subroutine iterator: called CC=1 SCAR=0.0
266 1 my $self = shift;
267 1 my $raw = $raw_access;
268 1 my $i = 0;
269 1 ▶ return sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
270 # preserve access mode for the life of the iterator
271 1 local $raw_access = $raw;
272 1 ${ $assign->(\$$self->[$i++]) } ;
273 1 };
274 }
275  
276 8 our $AUTOLOAD;
277  
278 20 ▶sub AUTOLOAD {
Subroutine AUTOLOAD: called CC=8 SCAR=20.8
279 # enable access to $o->caller::AUTOLOAD
280 20 ▶ my $name
Branch: 1 branch
BranchTrueFalseTotal
defined $Class::Ref::ARRAY::AUTOLOAD ? : 19 1 20
281 = defined $AUTOLOAD
282 ? substr($AUTOLOAD, 1 + rindex $AUTOLOAD, ':')
283 : 'AUTOLOAD';
284  
285 # undef so that we can detect if next call is for $o->caller::AUTOLOAD
286 # - needed cause $AUTOLOAD stays set to previous value until next call
287 20 undef $AUTOLOAD;
288  
289 20 ▶ return if $name eq 'DESTROY';
Branch: 1 branch
BranchTrueFalseTotal
if $name eq "DESTROY" 11 9 20
290  
291 # NOTE must do this after AUTOLOAD check
292 # - weird things happen when a wrapped ARRAY is an element of a wrapped
293 # ARRAY. tie'd ARRAYs have some lvalue magic on their FETCHed values.
294 # As a result, this call to shift triggers the tie object call to FETCH
295 # to ensure the lvalue is still valid.
296 9 my $self = shift;
297  
298 # honor @ISA if the caller is using it
299 9 my $pkg = caller;
300 9 ▶ my $idx = $pkg->can($name) ? $pkg->$name : undef;
Branch: 1 branch
BranchTrueFalseTotal
$pkg->can($name) ? : 8 1 9
301  
302 {
303 8 ▶ no warnings 'numeric';
Subroutine BEGIN: called CC=1 SCAR=0.0
304 9 ▶ defined $idx and $idx eq int($idx)
Branch: 1 branch
BranchTrueFalseTotal
defined $idx and $idx eq int $idx or Carp::croak("'${name}' is not a numeric constant in '${pkg}'") 7 2 9
Condition100%3/3
defined $idx and $idx eq int $idx
!ll&&!rl&&r
117
MC/DC100%2/2
defined $idx and $idx eq int $idx
defined $idx $idx eq int $idx
Truth table100%3/3
A and B
A= defined $idxB= $idx eq int $idx
ABresult
0X0
100
111
305 or Carp::croak "'$name' is not a numeric constant in '$pkg'";
306 }
307  
308 # simulate a fetch for a non-existent index without autovivification
309 7 ▶ return undef unless exists $$self->[$idx] or @_;
Branch: 1 branch
BranchTrueFalseTotal
unless exists $$self->[$idx] or @_ 1 6 7
Condition100%3/3
exists $$self->[$idx] or @_
l!l&&r!l&&!r
511
MC/DC100%2/2
exists $$self->[$idx] or @_
exists $$self->[$idx] @_
Truth table100%3/3
A or B
A= exists $$self->[$idx]B= @_
ABresult
1X1
011
000
310  
311 # keep this broken up in case I decide to implement lvalues
312 6 my $o = $assign->(\$$self->[$idx], @_);
313 6 $$o;
314 }
315  
316 package Class::Ref::ARRAY::Tie;
317 8 $Class::Ref::ARRAY::Tie::VERSION = '0.06';
318 8 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
319 8 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
320  
321 # borrowed from Tie::StdArray (in Tie::Array)
322  
323 #<<< ready... steady... cross-eyed!!
324 31 ▶sub TIEARRAY { bless [$_[1]] => $_[0] }
Subroutine TIEARRAY: called CC=1 SCAR=0.0
325 3 ▶sub FETCHSIZE { scalar @{ $_[0][0] } }
Subroutine FETCHSIZE: called CC=1 SCAR=0.0
326 1 ▶sub STORESIZE { $#{ $_[0][0] } = $_[1] - 1 }
Subroutine STORESIZE: called CC=1 SCAR=0.0
327 1 ▶sub STORE { $_[0][0]->[$_[1]] = $_[2] }
Subroutine STORE: called CC=1 SCAR=0.0
328 15 ▶sub FETCH { ${ $assign->(\$_[0][0][$_[1]]) } } # magic
Subroutine FETCH: called CC=1 SCAR=0.0
329 1 ▶sub CLEAR { @{ $_[0][0] } = () }
Subroutine CLEAR: called CC=1 SCAR=0.0
330 1 ▶sub POP { pop @{ $_[0][0] } }
Subroutine POP: called CC=1 SCAR=0.0
331 2 ▶sub PUSH { my $o = shift->[0]; push @$o, @_ }
Subroutine PUSH: called CC=1 SCAR=0.0
332 1 ▶sub SHIFT { shift @{ $_[0][0] } }
Subroutine SHIFT: called CC=1 SCAR=0.0
333 1 ▶sub UNSHIFT { my $o = shift->[0]; unshift @$o, @_ }
Subroutine UNSHIFT: called CC=1 SCAR=0.0
334 1 ▶sub EXISTS { exists $_[0][0]->[$_[1]] }
Subroutine EXISTS: called CC=1 SCAR=0.0
335 1 ▶sub DELETE { delete $_[0][0]->[$_[1]] }
Subroutine DELETE: called CC=1 SCAR=0.0
336 0 ▶sub EXTEND { $_[0]->STORESIZE($_[1]) }
Subroutine EXTEND: not called CC=1 SCAR=6.9
337 1 ▶sub SPLICE { splice @{ shift->[0] }, shift, shift, @_ }
Subroutine SPLICE: called CC=1 SCAR=0.0
338 #>>>
339  
340 =head1 GUTS
341  
342 All objects created and returned by L<Class::Ref> are blessed REF types. This
343 is what protects the original reference from being blessed into an unwanted
344 package. The C<ref> type of the given value is what determines what package the
345 REF is blessed into. HASHes go into C<Class::Ref::HASH> and ARRAYs go into
346 C<Class::Ref::ARRAY>.
347  
348 The use of the L<overload> pragma to overload the dereference operators allows
349 the REF object to still be accessed as HASH refs and ARRAY refs. When these REFs
350 are coerced into their appropriate type, they are wrapped in a tie mechanism to
351 retain control over the return of member values.
352  
353 The only way to fully bypass all of this is to manually dereference the REF
354 object:
355  
356 $o = Class::Ref->new({ foo => 1 });
357 $$o->{foo};
358  
359 =head1 CAVEATS
360  
361 When dealing with a wrapped HASH, there is no way to access keys named C<isa>
362 and C<can>. They are core methods perl uses to interact with OO values.
363  
364 Accessing HASH members with invalid perl symbols is possible with a little work:
365  
366 my $method = '0) key';
367 $o->$method; # access $o->{'0) key'};
368  
369 =head1 SEE ALSO
370  
371 I've always wanted to have this kind of functionality for hashes that really
372 needed a more formal interface. However, I found myself wanting more from the
373 existing modules out there in the wild. So I borrowed some the great ideas out
374 there and brewed my own implementation to have the level of flexibility that I
375 desire. And if it helps others, that's awesome too.
376  
377 =over 4
378  
379 =item * L<Class::Hash>
380  
381 Probably the de facto module for creating accessors to a hash. However, it only
382 provides a single layer of encapsulation.
383  
384 =item * L<Class::ConfigHash>
385  
386 Provides a deeper implementation but takes (avoids) steps to make the hash
387 read-only.
388  
389 =item * L<Hash::AsObject>
390  
391 Also provides a deep implementation. Goes further to provide access to methods
392 like C<AUTOLOAD> and C<DESTROY>.
393  
394 =back
395  
396 =head1 AUTHOR
397  
398 William Cox <mydimension@gmail.com>
399  
400 =head1 LICENSE
401  
402 This program is free software; you can redistribute it and/or modify it under
403 the same terms as Perl itself.
404  
405 See L<http://dev.perl.org/licenses/>
406  
407 =cut
408  
409 8 1;
↑ Summary