blib/lib/Venus/Role/Coercible.pm

filter: Statementstmt 96.8% 61 / 63 Branchbran 85.0% 17 / 20 Conditioncond 55.5% 5 / 9 MC/DCmcdc 0.0% 0 / 6 Subroutinesub 100% 12 / 12 Podpod 75.0% 6 / 8 totaltotal 85.5% 101 / 118 CC 16 SCAR 12.9
CC
16
Cov
90%
coerce_into
6.2
coerce_onto
6.1
coercers
2.1
CRAP 3.7
« blib/lib/Venus/Process.pm ↑ Summary blib/lib/Venus/Task/Venus.pm »
1 package Venus::Role::Coercible;
2  
3 1 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 1 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 1 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 1 ▶use Venus::Role 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # BUILDERS
13  
14 41 ▶sub BUILD {
Subroutine BUILD: called CC=2 SCAR=6.9
Pod undocumented
15 41 my ($self, $data) = @_;
16  
17 41 $data = $self->coercion($data);
18  
19 41 for my $name (keys %$data) {
20 40 $self->{$name} = $data->{$name};
21 }
22  
23 41 return $self;
24 };
25  
26 # METHODS
27  
28 2 ▶sub coercers {
Subroutine coercers: called CC=2 SCAR=7.2
Pod documented
29 2 my ($self) = @_;
30  
31 2 ▶ return $self->can('coerce') ? $self->coerce : {};
Branch: 1 branch
BranchTrueFalseTotal
$self->can('coerce') ? : 0 2 2
32 }
33  
34 43 ▶sub coerce_args {
Subroutine coerce_args: called CC=2 SCAR=6.9
Pod documented
35 43 my ($self, $data, $spec) = @_;
36  
37 43 for my $name (grep exists($data->{$_}), sort keys %$spec) {
38 $data->{$name} = $self->coerce_onto(
39 46 $data, $name, $spec->{$name}, $data->{$name},
40 );
41 }
42  
43 43 return $data;
44 }
45  
46 2 ▶sub coerce_attr {
Subroutine coerce_attr: called CC=2 SCAR=6.9
Pod documented
47 2 my ($self, $name, @args) = @_;
48  
49 2 ▶ return $self->{$name} if !@args;
Branch: 1 branch
BranchTrueFalseTotal
unless @args 1 1 2
50  
51 1 return $self->{$name} = $self->coercion({$name, $args[0]})->{$name};
52 }
53  
54 59 ▶sub coerce_into {
Subroutine coerce_into: called CC=6 SCAR=18.2
Pod documented
55 59 my ($self, $class, $value) = @_;
56  
57 59 require Scalar::Util;
58 59 require Venus::Space;
59  
60 59 $class = (my $space = Venus::Space->new($class))->load;
61  
62 59 my $name = lc $space->label;
63  
64 59 require Venus::Name;
65 59 require Venus::What;
66  
67 59 my $aliases = {
68 array => 'arrayref',
69 code => 'coderef',
70 hash => 'hashref',
71 regexp => 'regexpref',
72 scalar => 'scalarref',
73 };
74  
75 59 my $type = lc Venus::Name->new(scalar Venus::What->new(value => $value)->identify)->label;
76  
77 59 ▶ $type = $aliases->{$type} || $type;
Condition66%2/3
$aliases->{$type} || $type
l!l&&r!l&&!r
21380
MC/DC0%0/2
$aliases->{$type} || $type
$aliases->{$type} $type
Truth table66%2/3
A || B
A= $aliases->{$type}B= $type
ABresult
1X1
011
000
78  
79 59 my $method;
80  
81 59 ▶ if ($method = $self->can("coerce_into_${name}_from_${type}")) {
Branch: 2 branches
BranchTrueFalseTotal
if ($method = $self->can("coerce_into_${name}_from_$type")) { } 3 56 59
elsif ($method = $self->can("coerce_into_$name")) { } 4 52 56
82 3 return $self->$method($class, $value);
83 }
84 elsif ($method = $self->can("coerce_into_${name}")) {
85 4 return $self->$method($class, $value);
86 }
87 52 ▶ if (Scalar::Util::blessed($value) && $value->isa($class)) {
Branch: 1 branch
BranchTrueFalseTotal
if (builtin::blessed($value) and $value->isa($class)) { } 0 52 52
Condition33%1/3
builtin::blessed($value) and $value->isa($class)
!ll&&!rl&&r
5200
MC/DC0%0/2
builtin::blessed($value) and $value->isa($class)
builtin::blessed($value) $value->isa($class)
Truth table33%1/3
A and B
A= builtin::blessed($value)B= $value->isa($class)
ABresult
0X0
100
111
88 0 return $value;
89 }
90 else {
91 52 return $class->new($value);
92 }
93 }
94  
95 50 ▶sub coerce_onto {
Subroutine coerce_onto: called CC=6 SCAR=18.0
Pod documented
96 50 my ($self, $data, $name, $class, $value) = @_;
97  
98 50 require Venus::Space;
99  
100 50 $class = Venus::Space->new($class)->load;
101  
102 50 ▶ $value = $data->{$name} if $#_ < 4;
Branch: 1 branch
BranchTrueFalseTotal
if $#_ < 4 4 46 50
103  
104 50 require Venus::Name;
105 50 require Venus::What;
106  
107 50 my $aliases = {
108 array => 'arrayref',
109 code => 'coderef',
110 hash => 'hashref',
111 regexp => 'regexpref',
112 scalar => 'scalarref',
113 };
114  
115 50 my $type = lc Venus::Name->new(scalar Venus::What->new(value => $value)->identify)->label;
116  
117 50 ▶ $type = $aliases->{$type} || $type;
Condition66%2/3
$aliases->{$type} || $type
l!l&&r!l&&!r
16340
MC/DC0%0/2
$aliases->{$type} || $type
$aliases->{$type} $type
Truth table66%2/3
A || B
A= $aliases->{$type}B= $type
ABresult
1X1
011
000
118  
119 50 my $method;
120  
121 50 ▶ if ($method = $self->can("coerce_onto_${name}_from_${type}")) {
Branch: 3 branches
BranchTrueFalseTotal
if ($method = $self->can("coerce_onto_${name}_from_$type")) { } 2 48 50
elsif ($method = $self->can("coerce_onto_$name")) { } 0 48 48
elsif ($method = $self->can("coerce_$name")) { } 39 9 48
122 2 return $data->{$name} = $self->$method(\&coerce_into, $class, $value);
123 }
124 elsif ($method = $self->can("coerce_onto_${name}")) {
125 0 return $data->{$name} = $self->$method(\&coerce_into, $class, $value);
126 }
127 elsif ($method = $self->can("coerce_${name}")) {
128 39 return $data->{$name} = $self->$method(\&coerce_into, $class, $value);
129 }
130 else {
131 9 return $data->{$name} = $self->coerce_into($class, $value);
132 }
133 }
134  
135 44 ▶sub coercion {
Subroutine coercion: called CC=2 SCAR=6.9
Pod documented
136 44 my ($self, $data) = @_;
137  
138 44 my $spec = $self->coercers;
139  
140 44 ▶ return $data if !%$spec;
Branch: 1 branch
BranchTrueFalseTotal
unless %$spec 2 42 44
141  
142 42 return $self->coerce_args($data, $spec);
143 }
144  
145 # EXPORTS
146  
147 8 ▶sub EXPORT {
Subroutine EXPORT: called CC=1 SCAR=0.0
Pod undocumented
148 [
149 8 'coerce_args',
150 'coerce_attr',
151 'coerce_into',
152 'coerce_onto',
153 'coercers',
154 'coercion',
155 ]
156 }
157  
158 1 1;
159  
160  
161  
162 =head1 NAME
163  
164 Venus::Role::Coercible - Coercible Role
165  
166 =cut
167  
168 =head1 ABSTRACT
169  
170 Coercible Role for Perl 5
171  
172 =cut
173  
174 =head1 SYNOPSIS
175  
176 package Person;
177  
178 use Venus::Class;
179  
180 with 'Venus::Role::Coercible';
181  
182 attr 'name';
183 attr 'father';
184 attr 'mother';
185 attr 'siblings';
186  
187 sub coercers {
188 {
189 father => 'Person',
190 mother => 'Person',
191 name => 'Venus/String',
192 siblings => 'Person',
193 }
194 }
195  
196 sub coerce_name {
197 my ($self, $code, @args) = @_;
198  
199 return $self->$code(@args);
200 }
201  
202 sub coerce_siblings {
203 my ($self, $code, $class, $value) = @_;
204  
205 return [map $self->$code($class, $_), @$value];
206 }
207  
208 package main;
209  
210 my $person = Person->new(
211 name => 'me',
212 father => {name => 'father'},
213 mother => {name => 'mother'},
214 siblings => [{name => 'brother'}, {name => 'sister'}],
215 );
216  
217 # $person
218 # bless({...}, 'Person')
219  
220 # $person->name
221 # bless({...}, 'Venus::String')
222  
223 # $person->father
224 # bless({...}, 'Person')
225  
226 # $person->mother
227 # bless({...}, 'Person')
228  
229 # $person->siblings
230 # [bless({...}, 'Person'), bless({...}, 'Person'), ...]
231  
232 =cut
233  
234 =head1 DESCRIPTION
235  
236 This package modifies the consuming package and provides methods for hooking
237 into object construction and coercing arguments into objects and values.
238  
239 =cut
240  
241 =head1 METHODS
242  
243 This package provides the following methods:
244  
245 =cut
246  
247 =head2 coerce_args
248  
249 coerce_args(hashref $data, hashref $spec) (hashref)
250  
251 The coerce_args method replaces values in the data provided with objects
252 corresponding to the specification provided. The specification should contains
253 key/value pairs where the keys map to class attributes (or input parameters)
254 and the values are L<Venus::Space> compatible package names.
255  
256 I<Since C<0.07>>
257  
258 =over 4
259  
260 =item coerce_args example 1
261  
262 package main;
263  
264 my $person = Person->new;
265  
266 my $data = $person->coerce_args(
267 {
268 father => { name => 'father' }
269 },
270 {
271 father => 'Person',
272 },
273 );
274  
275 # {
276 # father => bless({...}, 'Person'),
277 # }
278  
279 =back
280  
281 =cut
282  
283 =head2 coerce_attr
284  
285 coerce_attr(string $name, any $value) (any)
286  
287 The coerce_attr method is a surrogate accessor and gets and/or sets an instance
288 attribute based on the coercion rules, returning the coerced value.
289  
290 I<Since C<1.23>>
291  
292 =over 4
293  
294 =item coerce_attr example 1
295  
296 # given: synopsis
297  
298 package main;
299  
300 $person = Person->new(
301 name => 'me',
302 );
303  
304 my $coerce_name = $person->coerce_attr('name');
305  
306 # bless({value => "me"}, "Venus::String")
307  
308 =back
309  
310 =over 4
311  
312 =item coerce_attr example 2
313  
314 # given: synopsis
315  
316 package main;
317  
318 $person = Person->new(
319 name => 'me',
320 );
321  
322 my $coerce_name = $person->coerce_attr('name', 'myself');
323  
324 # bless({value => "myself"}, "Venus::String")
325  
326 =back
327  
328 =cut
329  
330 =head2 coerce_into
331  
332 coerce_into(string $class, any $value) (object)
333  
334 The coerce_into method attempts to coerce the value provided into an object of
335 the specified class. If the value is already an object of that class, it is
336 returned as-is. Otherwise, the method tries to find a suitable coercion method
337 to convert the value based on its type. If no specific coercion method is
338 found, it defaults to constructing a new instance of the target class using the
339 provided value.
340  
341 This method supports dynamic coercion by dispatching to a method on the
342 invocant (if present) named in the format C<coerce_into_${class}_from_${type}>
343 or C<coerce_into_${class}>, where C<$class> is the name of the desired object
344 class, and C<$type> is the data type of the value provided. If neither method
345 is found, it defaults to checking if the value is already of the target type or
346 creating a new instance of the target class.
347  
348 The class name used in the method name will be formatted as a lowercase string
349 having underscores in place of any double-semi-colons.
350  
351 For example: Example::Package will be C<example_package> making the method name
352 C<coerce_into_example_package>.
353  
354 The following are the possible values for data types that can be used in the
355 method name:
356  
357 =over 4
358  
359 =item * arrayref
360  
361 =item * boolean
362  
363 =item * coderef
364  
365 =item * float
366  
367 =item * hashref
368  
369 =item * number
370  
371 =item * object
372  
373 =item * regexp
374  
375 =item * scalarref
376  
377 =item * string
378  
379 =item * undef
380  
381 =back
382  
383 For example: Coercing a string into the Example::Package would warrant the
384 method name C<coerce_into_example_package_from_string>.
385  
386 I<Since C<0.07>>
387  
388 =over 4
389  
390 =item coerce_into example 1
391  
392 package main;
393  
394 my $person = Person->new;
395  
396 my $friend = $person->coerce_into('Person', {
397 name => 'friend',
398 });
399  
400 # bless({...}, 'Person')
401  
402 =back
403  
404 =over 4
405  
406 =item coerce_into example 2
407  
408 package Player;
409  
410 use Venus::Class;
411  
412 with 'Venus::Role::Coercible';
413  
414 attr 'name';
415  
416 sub coerce_into_person {
417 my ($self, $class, $value) = @_;
418  
419 return $class->new({name => $value || 'friend'});
420 }
421  
422 package main;
423  
424 my $player = Player->new;
425  
426 my $person = $player->coerce_into('Person');
427  
428 # bless({...}, 'Person')
429  
430 =back
431  
432 =over 4
433  
434 =item coerce_into example 3
435  
436 package Player;
437  
438 use Venus::Class;
439  
440 with 'Venus::Role::Coercible';
441  
442 attr 'name';
443  
444 sub coerce_into_person_from_string {
445 my ($self, $class, $value) = @_;
446  
447 return $class->new({name => $value});
448 }
449  
450 package main;
451  
452 my $player = Player->new;
453  
454 my $person = $player->coerce_into('Person', 'friend');
455  
456 # bless({...}, 'Person')
457  
458 =back
459  
460 =cut
461  
462 =head2 coerce_onto
463  
464 coerce_onto(hashref $data, string $name, string $class, any $value) (object)
465  
466 The coerce_onto method attempts to build and assign an object based on the
467 class name and value provided, as the value corresponding to the name
468 specified, in the data provided. If the C<$value> is omitted, the value
469 corresponding to the name in the C<$data> will be used.
470  
471 The coerce_onto method attempts to coerce the value provided into an object of
472 the specified class, and add it as an item in the data structure provided. If
473 the value is already an object of that class, it is returned as-is. Otherwise,
474 the method tries to find a suitable coercion method to convert the value based
475 on its type. If no specific coercion method is found, it defaults to
476 constructing a new instance of the target class using the provided value.
477  
478 This method supports dynamic coercion by dispatching to a method on the
479 invocant (if present) named in the format C<coerce_onto_${class}_from_${type}>
480 or C<coerce_onto_${class}> or C<coerce_${class}>, where C<$class> is the name
481 of the desired object class, and C<$type> is the data type of the value
482 provided. If neither method is found, it defaults to checking if the value is
483 already of the target type or creating a new instance of the target class.
484  
485 The class name used in the method name will be formatted as a lowercase string
486 having underscores in place of any double-semi-colons.
487  
488 For example: Example::Package will be C<example_package> making the method name
489 C<coerce_into_example_package>.
490  
491 The following are the possible values for data types that can be used in the
492 method name:
493  
494 =over 4
495  
496 =item * arrayref
497  
498 =item * boolean
499  
500 =item * coderef
501  
502 =item * float
503  
504 =item * hashref
505  
506 =item * number
507  
508 =item * object
509  
510 =item * regexp
511  
512 =item * scalarref
513  
514 =item * string
515  
516 =item * undef
517  
518 =back
519  
520 For example: Coercing a string into the Example::Package would warrant the
521 method name C<coerce_onto_example_package_from_string>.
522  
523 I<Since C<0.07>>
524  
525 =over 4
526  
527 =item coerce_onto example 1
528  
529 package main;
530  
531 my $person = Person->new;
532  
533 my $data = { friend => { name => 'friend' } };
534  
535 my $friend = $person->coerce_onto($data, 'friend', 'Person');
536  
537 # bless({...}, 'Person'),
538  
539 # $data was updated
540 #
541 # {
542 # friend => bless({...}, 'Person'),
543 # }
544  
545 =back
546  
547 =over 4
548  
549 =item coerce_onto example 2
550  
551 package Player;
552  
553 use Venus::Class;
554  
555 with 'Venus::Role::Coercible';
556  
557 attr 'name';
558 attr 'teammates';
559  
560 sub coercers {
561 {
562 teammates => 'Person',
563 }
564 }
565  
566 sub coerce_into_person {
567 my ($self, $class, $value) = @_;
568  
569 return $class->new($value);
570 }
571  
572 sub coerce_into_venus_string {
573 my ($self, $class, $value) = @_;
574  
575 return $class->new($value);
576 }
577  
578 sub coerce_teammates {
579 my ($self, $code, $class, $value) = @_;
580  
581 return [map $self->$code($class, $_), @$value];
582 }
583  
584 package main;
585  
586 my $player = Player->new;
587  
588 my $data = { teammates => [{ name => 'player2' }, { name => 'player3' }] };
589  
590 my $teammates = $player->coerce_onto($data, 'teammates', 'Person');
591  
592 # [bless({...}, 'Person'), bless({...}, 'Person')]
593  
594 # $data was updated
595 #
596 # {
597 # teammates => [bless({...}, 'Person'), bless({...}, 'Person')],
598 # }
599  
600 =back
601  
602 =over 4
603  
604 =item coerce_onto example 3
605  
606 package Player;
607  
608 use Venus::Class;
609  
610 with 'Venus::Role::Coercible';
611  
612 attr 'name';
613 attr 'teammates';
614  
615 sub coercers {
616 {
617 teammates => 'Person',
618 }
619 }
620  
621 sub coerce_into_person_from_string {
622 my ($self, $class, $value) = @_;
623  
624 return $class->new({name => $value});
625 }
626  
627 sub coerce_onto_teammates_from_arrayref {
628 my ($self, $code, $class, $value) = @_;
629  
630 return [map $self->$code($class, $_), @$value];
631 }
632  
633 package main;
634  
635 my $player = Player->new;
636  
637 my $data = { teammates => ['player2', 'player3'] };
638  
639 my $teammates = $player->coerce_onto($data, 'teammates', 'Person');
640  
641 # [bless({...}, 'Person'), bless({...}, 'Person')]
642  
643 # $data was updated
644 #
645 # {
646 # teammates => [bless({...}, 'Person'), bless({...}, 'Person')],
647 # }
648  
649 =back
650  
651 =over 4
652  
653 =item coerce_onto example 4
654  
655 package Player;
656  
657 use Venus::Class;
658  
659 with 'Venus::Role::Coercible';
660  
661 attr 'name';
662 attr 'teammates';
663  
664 sub coercers {
665 {
666 teammates => 'Person',
667 }
668 }
669  
670 sub coerce_onto_teammates_from_hashref {
671 my ($self, $code, $class, $value) = @_;
672  
673 return [$self->$code($class, $value)];
674 }
675  
676 package main;
677  
678 my $player = Player->new;
679  
680 my $data = { teammates => {name => 'player2'} };
681  
682 my $teammates = $player->coerce_onto($data, 'teammates', 'Person');
683  
684 # [bless({...}, 'Person'), bless({...}, 'Person')]
685  
686 # $data was updated
687 #
688 # {
689 # teammates => [bless({...}, 'Person'), bless({...}, 'Person')],
690 # }
691  
692 =back
693  
694 =cut
695  
696 =head2 coercers
697  
698 coercers() (hashref)
699  
700 The coercers method, if defined, is called during object construction, or by the
701 L</coercion> method, and returns key/value pairs where the keys map to class
702 attributes (or input parameters) and the values are L<Venus::Space> compatible
703 package names.
704  
705 I<Since C<0.02>>
706  
707 =over 4
708  
709 =item coercers example 1
710  
711 package main;
712  
713 my $person = Person->new(
714 name => 'me',
715 );
716  
717 my $coercers = $person->coercers;
718  
719 # {
720 # father => "Person",
721 # mother => "Person",
722 # name => "Venus/String",
723 # siblings => "Person",
724 # }
725  
726 =back
727  
728 =cut
729  
730 =head2 coercion
731  
732 coercion(hashref $data) (hashref)
733  
734 The coercion method is called automatically during object construction but can
735 be called manually as well, and is passed a hashref to coerce and return.
736  
737 I<Since C<0.02>>
738  
739 =over 4
740  
741 =item coercion example 1
742  
743 package main;
744  
745 my $person = Person->new;
746  
747 my $coercion = $person->coercion({
748 name => 'me',
749 });
750  
751 # $coercion
752 # {...}
753  
754 # $coercion->{name}
755 # bless({...}, 'Venus::String')
756  
757 # $coercion->{father}
758 # undef
759  
760 # $coercion->{mother}
761 # undef
762  
763 # $coercion->{siblings}
764 # undef
765  
766 =back
767  
768 =over 4
769  
770 =item coercion example 2
771  
772 package main;
773  
774 my $person = Person->new;
775  
776 my $coercion = $person->coercion({
777 name => 'me',
778 mother => {name => 'mother'},
779 siblings => [{name => 'brother'}, {name => 'sister'}],
780 });
781  
782 # $coercion
783 # {...}
784  
785 # $coercion->{name}
786 # bless({...}, 'Venus::String')
787  
788 # $coercion->{father}
789 # undef
790  
791 # $coercion->{mother}
792 # bless({...}, 'Person')
793  
794 # $coercion->{siblings}
795 # [bless({...}, 'Person'), bless({...}, 'Person'), ...]
796  
797 =back
798  
799 =cut
800  
801 =head1 AUTHORS
802  
803 Awncorp, C<awncorp@cpan.org>
804  
805 =cut
806  
807 =head1 LICENSE
808  
809 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
810  
811 This program is free software, you can redistribute it and/or modify it under
812 the terms of the Apache license version 2.0.
813  
814 =cut
« blib/lib/Venus/Process.pm ↑ Summary blib/lib/Venus/Task/Venus.pm »