List/Objects/WithUtils.pm

filter: Statementstmt 100% 69 / 69 Branchbran 92.3% 24 / 26 Conditioncond 71.4% 15 / 21 MC/DCmcdc 41.6% 5 / 12 Subroutinesub 100% 11 / 11 Podpod n/a totaltotal 89.2% 124 / 139 SCAR 30.5
CC
21
Cov
93%
import
21.1
BEGIN
1.0
BEGIN
1.0
CRAP 21.1
« List/Objects/WithUtils/Role/Hash.pm ↑ Summary List/Objects/WithUtils/Hash/Inflated.pm »
1 package List::Objects::WithUtils;
2 208 $List::Objects::WithUtils::VERSION = '2.028002';
3 209 ▶use Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 208 ▶use strictures 2;
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 208 our %ImportMap = (
7 array => 'Array',
8 immarray => 'Array::Immutable',
9 array_of => 'Array::Typed',
10 immarray_of => 'Array::Immutable::Typed',
11 hash => 'Hash',
12 immhash => 'Hash::Immutable',
13 hash_of => 'Hash::Typed',
14 immhash_of => 'Hash::Immutable::Typed',
15 );
16  
17 208 our @DefaultImport = keys %ImportMap;
18  
19 sub import {
20 213 ▶ my ($class, @funcs) = @_;
Subroutine import: called CC=21 SCAR=30.5
21  
22 213 my $pkg;
23 213 ▶ if (ref $funcs[0]) {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $funcs[0]) 96 117 213
24 96 ▶ croak 'Expected a list of imports or a HASH but got '.$funcs[0]
Branch: 1 branch
BranchTrueFalseTotal
unless ref $funcs[0] eq "HASH" 1 95 96
25 unless ref $funcs[0] eq 'HASH';
26 95 my %opts = %{ $funcs[0] };
27 95 ▶ @funcs = @{ $opts{import} || [ 'all' ] };
Branch: 1 branch
BranchTrueFalseTotal
$opts{"import"} or ["all"] 0 95 95
28 95 ▶ $pkg = $opts{to} || caller;
Condition66%2/3
$opts{'to'} || caller
l!l&&r!l&&!r
9410
MC/DC0%0/2
$opts{'to'} || caller
$opts{'to'} caller
Truth table66%2/3
A || B
A= $opts{'to'}B= caller
ABresult
1X1
011
000
29 }
30  
31 212 ▶ @funcs = @DefaultImport unless @funcs;
Branch: 1 branch
BranchTrueFalseTotal
unless @funcs 7 205 212
32 212 my %fmap = map {;
33 269 ▶ lc( substr($_, 0, 1) eq ':' ? substr($_, 1) : $_ ) => 1
Branch: 1 branch
BranchTrueFalseTotal
substr($_, 0, 1) eq ':' ? : 2 267 269
34 } @funcs;
35  
36 212 ▶ if (defined $fmap{all} || defined $fmap{-all}) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined $fmap{'all'} or defined $fmap{'-all'}) { } 90 122 212
elsif (defined $fmap{'functions'} or defined $fmap{'funcs'}) { } 1 121 122
Condition100%3/3
defined $fmap{"all"} or defined $fmap{"-all"}
l!l&&r!l&&!r
891122
MC/DC100%2/2
defined $fmap{"all"} or defined $fmap{"-all"}
defined $fmap{"all"} defined $fmap{"-all"}
Truth table100%3/3
A or B
A= defined $fmap{"all"}B= defined $fmap{"-all"}
ABresult
1X1
011
000
37 90 @funcs = (
38 @DefaultImport,
39 'autobox'
40 )
41 ▶ } elsif (defined $fmap{functions} || defined $fmap{funcs}) {
Condition66%2/3
defined $fmap{"functions"} or defined $fmap{"funcs"}
l!l&&r!l&&!r
10121
MC/DC50%1/2
defined $fmap{"functions"} or defined $fmap{"funcs"}
defined $fmap{"functions"} defined $fmap{"funcs"}
Truth table66%2/3
A or B
A= defined $fmap{"functions"}B= defined $fmap{"funcs"}
ABresult
1X1
011
000
42 # Legacy import tag, tested but not documented
43 1 @funcs = @DefaultImport
44 }
45  
46 212 my @mods;
47 212 for my $function (@funcs) {
48 996 ▶ if ($function eq 'autobox' || $function eq '-autobox') {
Branch: 1 branch
BranchTrueFalseTotal
if ($function eq "autobox" or $function eq "-autobox") 93 903 996
Condition100%3/3
$function eq "autobox" or $function eq "-autobox"
l!l&&r!l&&!r
921903
MC/DC100%2/2
$function eq "autobox" or $function eq "-autobox"
$function eq "autobox" $function eq "-autobox"
Truth table100%3/3
A or B
A= $function eq "autobox"B= $function eq "-autobox"
ABresult
1X1
011
000
49 93 require List::Objects::WithUtils::Autobox;
50 93 List::Objects::WithUtils::Autobox::import($class);
51 next
52 93 }
53 903 ▶ if (my $thismod = $ImportMap{$function}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $thismod = $List::Objects::WithUtils::ImportMap{$function}) 902 1 903
54 902 push @mods, 'List::Objects::WithUtils::'.$thismod;
55 next
56 902 }
57 1 croak "Unknown import parameter '$function'"
58 }
59  
60 211 ▶ $pkg = caller unless defined $pkg;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $pkg 116 95 211
61 211 my @failed;
62 211 for my $mod (@mods) {
63 901 my $c = "package $pkg; use $mod; 1;";
64 901 local $@;
65 206 ▶ eval $c and not $@ or carp $@ and push @failed, $mod;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Branch: 1 branch
BranchTrueFalseTotal
eval $c and not $@ or carp($@) and push @failed, $mod 25 876 901
Condition55%5/9
eval $c && !$@ || carp($@) && push(@failed, $mod)
l!l
876250
eval $c and not $@
!ll&&!rl&&r
250876
carp($@) and push @failed, $mod
!ll&&!rl&&r
0250
MC/DC0%0/4
eval $c && !$@ || carp($@) && push(@failed, $mod)
eval $c not $@ carp($@) push @failed, $mod
Truth table14%1/7
A and not(B) || C and D
A= eval $cB= not $@C= carp($@)D= push @failed, $mod
ABCDresult
11XX1
0X111
10111
0X0X0
0X100
100X0
10100
66 }
67  
68 211 ▶ if (@failed) {
Branch: 1 branch
BranchTrueFalseTotal
if (@failed) 7 204 211
69 7 croak 'Failed to import ' . join ', ', @failed
70 }
71  
72 1
73 204 }
74  
75 208 ▶print <<'_EOB'
Branch: 1 branch
BranchTrueFalseTotal
unless caller 0 208 208
76 (CLASS)
77 + (ROLES)
78 -> (SUBCLASS)
79 + (ROLES)
80 List::Objects::WithUtils::
81 Array (array)
82 + Role::Array
83 + Role::Array::WithJunctions
84 -> Array::Immutable (immarray)
85 + Role::Array::Immutable
86 -> Array::Immutable::Typed (immarray_of)
87 + Role::Array::Immutable
88 + Role::Array::Typed
89 -> Array::Junction (array->{any,all}_items)
90 -> Array::Typed (array_of)
91 + Role::Array::Typed
92 Hash (hash)
93 + Role::Hash
94 -> Hash::Immutable (immhash)
95 + Role::Hash::Immutable
96 -> Hash::Immutable::Typed (immhash_of)
97 + Role::Hash::Immutable
98 + Role::Hash::Typed
99 -> Hash::Typed (hash_of)
100 + Role::Array::Typed
101
102 Hash::Inflated (hash->inflate)
103 -> Hash::Inflated::RW (hash->inflate(rw => 1))
104 _EOB
105 unless caller;
106  
107 208 1;
108  
109 =pod
110  
111 =for Pod::Coverage import
112  
113 =head1 NAME
114  
115 List::Objects::WithUtils - List objects, kitchen sink included
116  
117 =head1 SYNOPSIS
118  
119 ## A small sample; consult the description, below, for links to
120 ## extended documentation
121  
122 # Import all object constructor functions:
123 # array immarray array_of immarray_of
124 # hash immhash hash_of immhash_of
125 use List::Objects::WithUtils;
126  
127 # Import all of the above plus autoboxing:
128 use List::Objects::WithUtils ':all';
129 # Same as above, but shorter:
130 use Lowu;
131  
132 # Most methods returning lists return new objects; chaining is easy:
133 array(qw/ aa Ab bb Bc bc /)
134 ->grep(sub { /^b/i })
135 ->map(sub { uc })
136 ->uniq
137 ->all; # ( 'BB', 'BC' )
138  
139 # Useful utilities from other list modules are available:
140 my $want_idx = array(
141 +{ id => '400', user => 'bob' },
142 +{ id => '600', user => 'suzy' },
143 +{ id => '700', user => 'fred' },
144 )->first_index(sub { $_->{id} > 500 });
145  
146 my $itr = array( 1 .. 7 )->natatime(3);
147 while ( my @nextset = $itr->() ) {
148 ...
149 }
150  
151 my $meshed = array(qw/ a b c d /)
152 ->mesh( array(1 .. 4) )
153 ->all; # ( 'a', 1, 'b', 2, 'c', 3, 'd', 4 )
154
155 my ($evens, $odds) = array( 1 .. 20 )
156 ->part(sub { $_[0] & 1 })
157 ->all;
158  
159 my $sorted = array(
160 +{ name => 'bob', acct => 1 },
161 +{ name => 'fred', acct => 2 },
162 +{ name => 'suzy', acct => 3 },
163 )->sort_by(sub { $_->{name} });
164  
165 # array() objects are mutable:
166 my $mutable = array(qw/ foo bar baz /);
167 $mutable->insert(1, 'quux');
168 $mutable->delete(2);
169  
170 # ... or use immarray() immutable arrays:
171 my $static = immarray( qw/ foo bar baz / );
172 $static->set(0, 'quux'); # dies
173 $static->[0] = 'quux'; # dies
174 push @$static, 'quux'; # dies
175  
176 # Construct a hash:
177 my $hash = hash( foo => 'bar', snacks => 'cake' );
178
179 # You can set multiple keys in one call:
180 $hash->set( foobar => 'baz', pie => 'cherry' );
181  
182 # ... which is useful for merging in another (plain) hash:
183 my %foo = ( pie => 'pumpkin', snacks => 'cheese' );
184 $hash->set( %foo );
185  
186 # ... or another hash object:
187 my $second = hash( pie => 'key lime' );
188 $hash->set( $second->export );
189  
190 # Retrieve one value as a simple scalar:
191 my $snacks = $hash->get('snacks');
192  
193 # ... or retrieve multiple values as an array-type object:
194 my $vals = $hash->get('foo', 'foobar');
195  
196 # Take a hash slice of keys, return a new hash object
197 # consisting of the retrieved key/value pairs:
198 my $slice = $hash->sliced('foo', 'pie');
199  
200 # Arrays inflate to hash objects:
201 my $items = array( qw/ foo bar baz/ )->map(sub { $_ => 1 })->inflate;
202 if ($items->exists('foo')) {
203 # ...
204 }
205  
206 # Hashes inflate to simple objects with accessors:
207 my $obj = $hash->inflate;
208 $snacks = $obj->snacks;
209  
210 # Methods returning multiple values typically return new array-type objects:
211 my @match_keys = $hash->keys->grep(sub { m/foo/ })->all;
212 my @match_vals = $hash->values->grep(sub { m/bar/ })->all;
213
214 my @sorted_pairs = hash( foo => 2, bar => 3, baz => 1)
215 ->kv
216 ->sort_by(sub { $_->[1] })
217 ->all; # ( [ baz => 1 ], [ foo => 2 ], [ bar => 3 ] )
218  
219 # Perl6-inspired Junctions:
220 if ( $hash->keys->any_items == qr/snacks/ ) {
221 # ... hash has key(s) matching /snacks/ ...
222 }
223 if ( $hash->values->all_items > 10 ) {
224 # ... all hash values greater than 10 ...
225 }
226  
227 # Type-checking arrays via Type::Tiny:
228 use Types::Standard -all;
229 my $int_arr = array_of Int() => 1 .. 10;
230  
231 # Type-checking hashes:
232 use Types::Standard -all;
233 my $int_hash = hash_of Int() => (foo => 1, bar => 2);
234  
235 # Native list types can be autoboxed:
236 use List::Objects::WithUtils 'autobox';
237 my $foo = [ qw/foo baz bar foo quux/ ]->uniq->sort;
238 my $bar = +{ a => 1, b => 2, c => 3 }->values->sort;
239  
240 # Autoboxing is lexically scoped like normal:
241 { no List::Objects::WithUtils::Autobox;
242 [ 1 .. 10 ]->shuffle; # dies
243 }
244  
245  
246 =head1 DESCRIPTION
247  
248 A set of roles and classes defining an object-oriented interface to Perl
249 hashes and arrays with useful utility methods, junctions, type-checking
250 ability, and optional autoboxing. Originally derived from L<Data::Perl>.
251  
252 =head2 Uses
253  
254 The included objects are useful as-is but are largely intended for use as data
255 container types for attributes. This lends a more natural object-oriented
256 syntax; these are particularly convenient in combination with delegated
257 methods, as in this example:
258  
259 package Some::Thing;
260 use List::Objects::WithUtils;
261 use Moo;
262  
263 has items => (
264 is => 'ro',
265 builder => sub { array },
266 handles => +{
267 add_items => 'push',
268 get_items => 'all',
269 items_where => 'grep',
270 },
271 );
272  
273 # ... later ...
274 my $thing = Some::Thing->new;
275 $thing->add_items(@more_items);
276 # Operate on all positive items:
277 for my $item ($thing->items_where(sub { $_ > 0 })->all) {
278 ...
279 }
280  
281 L<List::Objects::Types> provides L<Type::Tiny>-based types & coercions
282 matching the list objects provided by this distribution. These integrate
283 nicely with typed or untyped list objects:
284  
285 package Accounts;
286 use List::Objects::Types -types;
287 use Moo 2;
288  
289 has usergroups => (
290 is => 'ro',
291 # +{ $group => [ [ $usr => $id ], ... ] }
292 # Coerced to objects all the way down:
293 isa => TypedHash[ TypedArray[ArrayObj] ],
294 coerce => 1,
295 builder => sub { +{} },
296 );
297  
298 # ... later ...
299 my $users_in_grp = $accts->usergroups
300 ->get($some_group)
301 ->grep(sub { $_[0]->get(0) });
302
303  
304 =head2 Objects
305  
306 =head3 Arrays
307  
308 B<array> (L<List::Objects::WithUtils::Array>) provides basic mutable
309 ARRAY-type objects. Behavior is defined by
310 L<List::Objects::WithUtils::Role::Array>; look there for documentation on
311 available methods.
312  
313 B<immarray> is imported from L<List::Objects::WithUtils::Array::Immutable> and
314 operates much like an B<array>, except methods that mutate the list are not
315 available; using immutable arrays promotes safer programming patterns.
316  
317 B<array_of> provides L<Type::Tiny>-compatible type-checking array objects
318 that can coerce and check their values as they are added; see
319 L<List::Objects::WithUtils::Array::Typed>.
320  
321 B<immarray_of> provides immutable type-checking arrays; see
322 L<List::Objects::WithUtils::Array::Immutable::Typed>.
323  
324 =head3 Hashes
325  
326 B<hash> is the basic mutable HASH-type object imported from
327 L<List::Objects::WithUtils::Hash>; see
328 L<List::Objects::WithUtils::Role::Hash> for documentation.
329  
330 B<immhash> provides immutable (restricted) hashes; see
331 L<List::Objects::WithUtils::Hash::Immutable>.
332  
333 B<hash_of> provides L<Type::Tiny>-compatible type-checking hash
334 objects; see L<List::Objects::WithUtils::Hash::Typed>.
335  
336 B<immhash_of> provides immutable type-checking hashes; see
337 L<List::Objects::WithUtils::Hash::Immutable::Typed>.
338  
339 =head2 Importing
340  
341 A bare import list (C<use List::Objects::WithUtils;>) will import all of the
342 object constructor functions described above; they can also be selectively
343 imported, e.g.:
344  
345 use List::Objects::WithUtils 'array_of', 'hash_of';
346  
347 Importing B<autobox> lexically enables L<List::Objects::WithUtils::Autobox>,
348 which provides L<List::Objects::WithUtils::Array> or
349 L<List::Objects::WithUtils::Hash> methods for native ARRAY and HASH types.
350  
351 Importing B<all> or B<:all> will import all of the object constructors and
352 additionally turn B<autobox> on; C<use Lowu;> is a shortcut for importing
353 B<all>.
354  
355 =head2 Debugging
356  
357 Most methods belonging to these objects are heavily micro-optimized -- at the
358 cost of useful error handling.
359  
360 Since there are few built-in argument checks, a mistake in your code can
361 frequently lead to slightly cryptic errors from the perl side:
362  
363 > my $pos; # whoops, I'm still undefined later:
364 > if ($arr->exists($pos)) { ... }
365 Use of uninitialized value in numeric le (<=) at $useless_lib_lineno
366  
367 ... in which case L<Devel::Confess> is likely to improve your quality of life
368 by providing a real backtrace:
369  
370 $ perl -d:Confess my_app.pl
371 Use of uninitialized value in numeric le (<=) at ...
372 [...]::Array::exists(ARRAY(0x8441068), undef) called at ...
373  
374 =head2 Subclassing
375  
376 The importer for this package is somewhat flexible; a subclass can override
377 import to pass import tags and a target package by feeding this package's
378 C<import()> a HASH:
379  
380 # Subclass and import to target packages (see Lowu.pm f.ex):
381 package My::Defaults;
382 use parent 'List::Objects::WithUtils';
383 sub import {
384 my ($class, @params) = @_;
385 $class->SUPER::import(
386 +{
387 import => [ 'autobox', 'array', 'hash' ],
388 to => scalar(caller)
389 }
390 )
391 }
392  
393 Functionality is mostly defined by Roles.
394 For example, it's easy to create your own array class with new methods:
395  
396 package My::Array::Object;
397 use Role::Tiny::With;
398 # Act like List::Objects::WithUtils::Array:
399 with 'List::Objects::WithUtils::Role::Array',
400 'List::Objects::WithUtils::Role::Array::WithJunctions';
401  
402 # One way to add your own functional interface:
403 use Exporter 'import'; our @EXPORT = 'my_array';
404 sub my_array { __PACKAGE__->new(@_) }
405  
406 # ... add/override methods ...
407  
408 ... in which case you may want to also define your own hash subclass that
409 overrides C<array_type> to produce your preferred arrays:
410  
411 package My::Hash::Object;
412 use Role::Tiny::With;
413 with 'List::Objects::WithUtils::Role::Hash';
414  
415 use Exporter 'import'; our @EXPORT = 'my_hash';
416 sub my_hash { __PACKAGE__->new(@_) }
417
418 sub array_type { 'My::Array::Object' }
419  
420 # ... add/override methods ...
421
422 =head1 SEE ALSO
423  
424 L<List::Objects::WithUtils::Role::Array> for documentation on the basic set of
425 C<array()> methods.
426  
427 L<List::Objects::WithUtils::Role::Array::WithJunctions> for documentation on C<array()>
428 junction-returning methods.
429  
430 L<List::Objects::WithUtils::Array::Immutable> for more on C<immarray()>
431 immutable arrays.
432  
433 L<List::Objects::WithUtils::Array::Typed> for more on C<array_of()>
434 type-checking arrays.
435  
436 L<List::Objects::WithUtils::Array::Immutable::Typed> for more on
437 C<immarray_of()> immutable type-checking arrays.
438  
439 L<List::Objects::WithUtils::Role::Hash> for documentation regarding C<hash()>
440 methods.
441  
442 L<List::Objects::WithUtils::Hash::Immutable> for more on C<immhash()>
443 immutable hashes.
444  
445 L<List::Objects::WithUtils::Hash::Typed> for more on C<hash_of()>
446 type-checking hashes.
447  
448 L<List::Objects::WithUtils::Hash::Immutable::Typed> for more on
449 C<immhash_of()> immutable type-checking hashes.
450  
451 L<List::Objects::WithUtils::Autobox> for details on autoboxing.
452  
453 The L<Lowu> module for a convenient importer shortcut.
454  
455 L<List::Objects::Types> for relevant L<Type::Tiny> types.
456  
457 L<MoopsX::ListObjects> for integration with L<Moops> class-building sugar.
458  
459 =head1 AUTHOR
460  
461 Jon Portnoy <avenj@cobaltirc.org>
462  
463 Licensed under the same terms as Perl.
464  
465 The original Array and Hash roles were derived from L<Data::Perl> by Matthew
466 Phillips (CPAN: MATTP), haarg, and others.
467  
468 Immutable array objects were originally inspired by L<Const::Fast> by Leon
469 Timmermans (CPAN: LEONT), but now use C<tie>.
470  
471 Junctions are adapted from L<Perl6::Junction> by Carl Franks (CPAN: CFRANKS)
472  
473 Most of the type-checking code and other useful additions were contributed by
474 Toby Inkster (CPAN: TOBYINK)
475  
476 A significant portion of this code simply wraps other widely-used modules, especially:
477  
478 L<List::Util>
479  
480 L<List::UtilsBy>
481  
482 L<Type::Tiny>
483  
484 Inspiration for a few pieces comes from the "classic" (version 0.33)
485 L<List::MoreUtils>.
486  
487 =cut
« List/Objects/WithUtils/Role/Hash.pm ↑ Summary List/Objects/WithUtils/Hash/Inflated.pm »