blib/lib/Venus/Role/Encaseable.pm

filter: Statementstmt 98.4% 64 / 65 Branchbran 96.4% 27 / 28 Conditioncond 79.1% 19 / 24 MC/DCmcdc 43.7% 7 / 16 Subroutinesub 100% 11 / 11 Podpod 71.4% 5 / 7 totaltotal 88.0% 133 / 151 CC 23 SCAR 16.2
CC
23
Cov
94%
encase
7.0
uncase
6.0
encased
6.0
CRAP 5.1
« blib/lib/Venus/Task.pm ↑ Summary blib/lib/Venus/Hook.pm »
1 package Venus::Role::Encaseable;
2  
3 119 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 119 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 119 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 119 ▶use Venus::Role 'fault', 'mask';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # ATTRIBUTES
13  
14 119 mask 'private';
15  
16 # AUDITS
17  
18 214 ▶sub AUDIT {
Subroutine AUDIT: called CC=2 SCAR=7.6
Pod undocumented
19 214 my ($self, $from) = @_;
20  
21 214 ▶ if (!$from->isa('Venus::Core')) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($from->isa("Venus::Core")) 0 214 214
22 0 fault "${self} requires ${from} to derive from Venus::Core";
23 }
24  
25 214 return $self;
26 }
27  
28 # METHODS
29  
30 3 ▶sub clone {
Subroutine clone: called CC=1 SCAR=0.0
Pod documented
31 3 my ($self) = @_;
32  
33 3 return $self->CLONE;
34 }
35  
36 23066 ▶sub encase {
Subroutine encase: called CC=7 SCAR=19.5
Pod documented
37 23066 my ($self, $key, $value) = @_;
38  
39 23066 ▶ return if !$key;
Branch: 1 branch
BranchTrueFalseTotal
unless $key 1 23065 23066
40  
41 23065 my $caller = caller;
42  
43 23065 require Scalar::Util;
44  
45 23065 ▶ if (!Scalar::Util::blessed($self)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 1 23064 23065
46 1 fault "Can't encase variable \"${key}\" without an instance of \"${self}\"";
47 }
48  
49 23064 my $class = ref $self;
50  
51 23064 ▶ if ($caller ne $class && !$class->isa($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($caller ne $class and not $class->isa($caller)) 1 23063 23064
Condition100%3/3
$caller ne $class and not $class->isa($caller)
!ll&&!rl&&r
1363194321
MC/DC100%2/2
$caller ne $class and not $class->isa($caller)
$caller ne $class not $class->isa($caller)
Truth table100%3/3
A and not(B)
A= $caller ne $classB= not $class->isa($caller)
ABresult
0X0
100
111
52 1 fault "Can't encase variable \"${key}\" outside the class or subclass of \"${class}\"";
53 }
54  
55 23063 ▶ my $data = $self->private || $self->private({});
Condition66%2/3
$self->private || $self->private({})
l!l&&r!l&&!r
2164214210
MC/DC0%0/2
$self->private || $self->private({})
$self->private $self->private({})
Truth table66%2/3
A || B
A= $self->privateB= $self->private({})
ABresult
1X1
011
000
56  
57 23063 ▶ return $data->{$key} if exists $data->{$key};
Branch: 1 branch
BranchTrueFalseTotal
if exists $data->{$key} 20546 2517 23063
58  
59 2517 return $data->{$key} = $value;
60 }
61  
62 19431 ▶sub encased {
Subroutine encased: called CC=6 SCAR=17.9
Pod documented
63 19431 my ($self, $key) = @_;
64  
65 19431 ▶ return if !$key;
Branch: 1 branch
BranchTrueFalseTotal
unless $key 1 19430 19431
66  
67 19430 my $caller = caller;
68  
69 19430 require Scalar::Util;
70  
71 19430 ▶ if (!Scalar::Util::blessed($self)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 1 19429 19430
72 1 fault "Can't retrieve encased variable \"${key}\" without an instance of \"${self}\"";
73 }
74  
75 19429 my $class = ref $self;
76  
77 19429 ▶ if ($caller ne $class && !$class->isa($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($caller ne $class and not $class->isa($caller)) 1 19428 19429
Condition100%3/3
$caller ne $class and not $class->isa($caller)
!ll&&!rl&&r
192721561
MC/DC100%2/2
$caller ne $class and not $class->isa($caller)
$caller ne $class not $class->isa($caller)
Truth table100%3/3
A and not(B)
A= $caller ne $classB= not $class->isa($caller)
ABresult
0X0
100
111
78 1 fault "Can't retrieve encased variable \"${key}\" outside the class or subclass of \"${class}\"";
79 }
80  
81 19428 ▶ my $data = $self->private || $self->private({});
Condition66%2/3
$self->private || $self->private({})
l!l&&r!l&&!r
187257030
MC/DC0%0/2
$self->private || $self->private({})
$self->private $self->private({})
Truth table66%2/3
A || B
A= $self->privateB= $self->private({})
ABresult
1X1
011
000
82  
83 19428 return $data->{$key};
84 }
85  
86 901 ▶sub recase {
Subroutine recase: called CC=6 SCAR=17.9
Pod documented
87 901 my ($self, $key, $value) = @_;
88  
89 901 ▶ return if !$key;
Branch: 1 branch
BranchTrueFalseTotal
unless $key 1 900 901
90  
91 900 my $caller = caller;
92  
93 900 require Scalar::Util;
94  
95 900 ▶ if (!Scalar::Util::blessed($self)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 1 899 900
96 1 fault "Can't recase variable \"${key}\" without an instance of \"${self}\"";
97 }
98  
99 899 my $class = ref $self;
100  
101 899 ▶ if ($caller ne $class && !$class->isa($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($caller ne $class and not $class->isa($caller)) 1 898 899
Condition100%3/3
$caller ne $class and not $class->isa($caller)
!ll&&!rl&&r
872261
MC/DC100%2/2
$caller ne $class and not $class->isa($caller)
$caller ne $class not $class->isa($caller)
Truth table100%3/3
A and not(B)
A= $caller ne $classB= not $class->isa($caller)
ABresult
0X0
100
111
102 1 fault "Can't recase variable \"${key}\" outside the class or subclass of \"${class}\"";
103 }
104  
105 898 ▶ my $data = $self->private || $self->private({});
Condition66%2/3
$self->private || $self->private({})
l!l&&r!l&&!r
836620
MC/DC0%0/2
$self->private || $self->private({})
$self->private $self->private({})
Truth table66%2/3
A || B
A= $self->privateB= $self->private({})
ABresult
1X1
011
000
106  
107 898 return $data->{$key} = $value;
108 }
109  
110 21 ▶sub uncase {
Subroutine uncase: called CC=6 SCAR=18.0
Pod documented
111 21 my ($self, $key) = @_;
112  
113 21 ▶ return if !$key;
Branch: 1 branch
BranchTrueFalseTotal
unless $key 1 20 21
114  
115 20 my $caller = caller;
116  
117 20 require Scalar::Util;
118  
119 20 ▶ if (!Scalar::Util::blessed($self)) {
Branch: 1 branch
BranchTrueFalseTotal
unless (builtin::blessed($self)) 1 19 20
120 1 fault "Can't uncase variable \"${key}\" without an instance of \"${self}\"";
121 }
122  
123 19 my $class = ref $self;
124  
125 19 ▶ if ($caller ne $class && !$class->isa($caller)) {
Branch: 1 branch
BranchTrueFalseTotal
if ($caller ne $class and not $class->isa($caller)) 1 18 19
Condition66%2/3
$caller ne $class and not $class->isa($caller)
!ll&&!rl&&r
1801
MC/DC50%1/2
$caller ne $class and not $class->isa($caller)
$caller ne $class not $class->isa($caller)
Truth table66%2/3
A and not(B)
A= $caller ne $classB= not $class->isa($caller)
ABresult
0X0
100
111
126 1 fault "Can't uncase variable \"${key}\" outside the class or subclass of \"${class}\"";
127 }
128  
129 18 ▶ my $data = $self->private || $self->private({});
Condition66%2/3
$self->private || $self->private({})
l!l&&r!l&&!r
1710
MC/DC0%0/2
$self->private || $self->private({})
$self->private $self->private({})
Truth table66%2/3
A || B
A= $self->privateB= $self->private({})
ABresult
1X1
011
000
130  
131 18 return delete $data->{$key};
132 }
133  
134 # EXPORTS
135  
136 214 ▶sub EXPORT {
Subroutine EXPORT: called CC=1 SCAR=0.0
Pod undocumented
137 214 ['clone', 'encase', 'encased', 'private', 'recase', 'uncase']
138 }
139  
140 119 1;
141  
142  
143  
144 =head1 NAME
145  
146 Venus::Role::Encaseable - Encaseable Role
147  
148 =cut
149  
150 =head1 ABSTRACT
151  
152 Encaseable Role for Perl 5
153  
154 =cut
155  
156 =head1 SYNOPSIS
157  
158 package Example;
159  
160 use Venus::Class 'with';
161  
162 with 'Venus::Role::Encaseable';
163  
164 sub execute {
165 my ($self) = @_;
166  
167 return $self->encase('count', 1);
168 }
169  
170 package main;
171  
172 my $example = Example->new;
173  
174 # bless({}, 'Example')
175  
176 # $example->execute;
177  
178 # 1
179  
180 =cut
181  
182 =head1 DESCRIPTION
183  
184 This package modifies the consuming package and provides methods for storing,
185 retrieving, and removing private instance variables, via the C<private>
186 (masked) attribute. B<Note:> A pre-existing attribute or routine named
187 C<private> in the consuming package may cause unexpected issues. This role
188 differs from L<Venus::Role::Stashable> in that it provides getters and setters
189 to help obscure the private instance data, whereas Stashable does not.
190  
191 =cut
192  
193 =head1 METHODS
194  
195 This package provides the following methods:
196  
197 =cut
198  
199 =head2 clone
200  
201 clone() (object)
202  
203 The clone method clones the invocant and returns the result.
204  
205 I<Since C<4.15>>
206  
207 =over 4
208  
209 =item clone example 1
210  
211 # given: synopsis
212  
213 package main;
214  
215 my $clone = $example->clone;
216  
217 # bless(..., "Example")
218  
219 =back
220  
221 =cut
222  
223 =head2 encase
224  
225 encase(string $key, any $value) (any)
226  
227 The encase method associates and stashes the key and value provided with the
228 class instance and returns the value provided. If the key is already associated
229 the value is not overwritten.
230  
231 I<Since C<4.15>>
232  
233 =over 4
234  
235 =item encase example 1
236  
237 package Example;
238  
239 use Venus::Class 'with';
240  
241 with 'Venus::Role::Encaseable';
242  
243 sub execute {
244 my ($self) = @_;
245  
246 return $self->encase;
247 }
248  
249 package main;
250  
251 my $example = Example->new;
252  
253 # bless({}, 'Example')
254  
255 # $example->execute;
256  
257 # undef
258  
259 =back
260  
261 =over 4
262  
263 =item encase example 2
264  
265 package Example;
266  
267 use Venus::Class 'with';
268  
269 with 'Venus::Role::Encaseable';
270  
271 sub execute {
272 my ($self) = @_;
273  
274 return $self->encase('count');
275 }
276  
277 package main;
278  
279 my $example = Example->new;
280  
281 # bless({}, 'Example')
282  
283 # $example->execute;
284  
285 # undef
286  
287 =back
288  
289 =over 4
290  
291 =item encase example 3
292  
293 package Example;
294  
295 use Venus::Class 'with';
296  
297 with 'Venus::Role::Encaseable';
298  
299 sub execute {
300 my ($self) = @_;
301  
302 return $self->encase('count', 1);
303 }
304  
305 package main;
306  
307 my $example = Example->new;
308  
309 # bless({}, 'Example')
310  
311 # $example->execute;
312  
313 # 1
314  
315 =back
316  
317 =over 4
318  
319 =item encase example 4
320  
321 package Example;
322  
323 use Venus::Class 'with';
324  
325 with 'Venus::Role::Encaseable';
326  
327 sub execute {
328 my ($self) = @_;
329  
330 my $count = 1;
331  
332 $count = $self->encase('count', $count);
333  
334 $count = $self->encase('count', $count + 1);
335  
336 $count = $self->encase('count', $count + 1);
337  
338 return $count;
339 }
340  
341 package main;
342  
343 my $example = Example->new;
344  
345 # bless({}, 'Example')
346  
347 # $example->execute;
348  
349 # 1
350  
351 =back
352  
353 =over 4
354  
355 =item encase example 5
356  
357 package Example;
358  
359 use Venus::Class 'with';
360  
361 with 'Venus::Role::Encaseable';
362  
363 sub execute {
364 my ($self) = @_;
365  
366 my $count = 1;
367  
368 $count = $self->encase('count', $count);
369  
370 return $count;
371 }
372  
373 package main;
374  
375 my $execute = Example->execute;
376  
377 # Exception! Venus::Fault
378  
379 =back
380  
381 =over 4
382  
383 =item encase example 6
384  
385 package Example;
386  
387 use Venus::Class 'with';
388  
389 with 'Venus::Role::Encaseable';
390  
391 sub execute {
392 my ($self) = @_;
393  
394 my $count = 1;
395  
396 $count = $self->encase('count', $count);
397  
398 return $count;
399 }
400  
401 package main;
402  
403 my $example = Example->new;
404  
405 $example->encase('count', 1);
406  
407 # Exception! Venus::Fault
408  
409 =back
410  
411 =cut
412  
413 =head2 encased
414  
415 encased(string $key) (any)
416  
417 The encased method retrieves the value associated with the key provided,
418 associated and stashed with the class instance.
419  
420 I<Since C<4.15>>
421  
422 =over 4
423  
424 =item encased example 1
425  
426 package Example;
427  
428 use Venus::Class 'with';
429  
430 with 'Venus::Role::Encaseable';
431  
432 sub execute {
433 my ($self) = @_;
434  
435 return $self->encased;
436 }
437  
438 package main;
439  
440 my $example = Example->new;
441  
442 # bless({}, 'Example')
443  
444 # $example->execute;
445  
446 # undef
447  
448 =back
449  
450 =over 4
451  
452 =item encased example 2
453  
454 package Example;
455  
456 use Venus::Class 'with';
457  
458 with 'Venus::Role::Encaseable';
459  
460 sub execute {
461 my ($self) = @_;
462  
463 return $self->encased('count');
464 }
465  
466 package main;
467  
468 my $example = Example->new;
469  
470 # bless({}, 'Example')
471  
472 # $example->execute;
473  
474 # undef
475  
476 =back
477  
478 =over 4
479  
480 =item encased example 3
481  
482 package Example;
483  
484 use Venus::Class 'with';
485  
486 with 'Venus::Role::Encaseable';
487  
488 sub execute {
489 my ($self) = @_;
490  
491 $self->encase('count', 1);
492  
493 return $self->encased('count');
494 }
495  
496 package main;
497  
498 my $example = Example->new;
499  
500 # bless({}, 'Example')
501  
502 # $example->execute;
503  
504 # 1
505  
506 =back
507  
508 =over 4
509  
510 =item encased example 4
511  
512 package Example;
513  
514 use Venus::Class 'with';
515  
516 with 'Venus::Role::Encaseable';
517  
518 sub execute {
519 my ($self) = @_;
520  
521 my $count = 1;
522  
523 $count = $self->recase('count', $count);
524  
525 $count = $self->recase('count', $count + 1);
526  
527 $count = $self->recase('count', $count + 1);
528  
529 return $self->encased('count');
530 }
531  
532 package main;
533  
534 my $example = Example->new;
535  
536 # bless({}, 'Example')
537  
538 # $example->execute;
539  
540 # 3
541  
542 =back
543  
544 =over 4
545  
546 =item encased example 5
547  
548 package Example;
549  
550 use Venus::Class 'with';
551  
552 with 'Venus::Role::Encaseable';
553  
554 sub execute {
555 my ($self) = @_;
556  
557 return $self->encased('count');
558 }
559  
560 package main;
561  
562 my $execute = Example->execute;
563  
564 # Exception! Venus::Fault
565  
566 =back
567  
568 =over 4
569  
570 =item encased example 6
571  
572 package Example;
573  
574 use Venus::Class 'with';
575  
576 with 'Venus::Role::Encaseable';
577  
578 sub execute {
579 my ($self) = @_;
580  
581 return $self->encased('count');
582 }
583  
584 package main;
585  
586 my $example = Example->new;
587  
588 $example->encased('count');
589  
590 # Exception! Venus::Fault
591  
592 =back
593  
594 =cut
595  
596 =head2 recase
597  
598 recase(string $key, any $value) (any)
599  
600 The recase method associates and stashes the key and value provided with the
601 class instance and returns the value provided. The value is always overwritten.
602  
603 I<Since C<4.15>>
604  
605 =over 4
606  
607 =item recase example 1
608  
609 package Example;
610  
611 use Venus::Class 'with';
612  
613 with 'Venus::Role::Encaseable';
614  
615 sub execute {
616 my ($self) = @_;
617  
618 return $self->recase;
619 }
620  
621 package main;
622  
623 my $example = Example->new;
624  
625 # bless({}, 'Example')
626  
627 # $example->execute;
628  
629 # undef
630  
631 =back
632  
633 =over 4
634  
635 =item recase example 2
636  
637 package Example;
638  
639 use Venus::Class 'with';
640  
641 with 'Venus::Role::Encaseable';
642  
643 sub execute {
644 my ($self) = @_;
645  
646 my $count = 1;
647  
648 $count = $self->encase('count', $count);
649  
650 return $self->recase('count', $count + 1);
651 }
652  
653 package main;
654  
655 my $example = Example->new;
656  
657 # bless({}, 'Example')
658  
659 # $example->execute;
660  
661 # 2
662  
663 =back
664  
665 =over 4
666  
667 =item recase example 3
668  
669 package Example;
670  
671 use Venus::Class 'with';
672  
673 with 'Venus::Role::Encaseable';
674  
675 sub execute {
676 my ($self) = @_;
677  
678 my $count = 1;
679  
680 $count = $self->recase('count', $count);
681  
682 $count = $self->recase('count', $count + 1);
683  
684 $count = $self->recase('count', $count + 1);
685  
686 return $self->recase('count', $count + 1);
687 }
688  
689 package main;
690  
691 my $example = Example->new;
692  
693 # bless({}, 'Example')
694  
695 # $example->execute;
696  
697 # 4
698  
699 =back
700  
701 =over 4
702  
703 =item recase example 5
704  
705 package Example;
706  
707 use Venus::Class 'with';
708  
709 with 'Venus::Role::Encaseable';
710  
711 sub execute {
712 my ($self) = @_;
713  
714 my $count = 1;
715  
716 $count = $self->recase('count', $count);
717  
718 return $count;
719 }
720  
721 package main;
722  
723 my $execute = Example->execute;
724  
725 # Exception! Venus::Fault
726  
727 =back
728  
729 =cut
730  
731 =head2 uncase
732  
733 uncase(string $key) (any)
734  
735 The uncase method dissociatesthe key and its corresponding value from the class
736 instance and returns the value.
737  
738 I<Since C<4.15>>
739  
740 =over 4
741  
742 =item uncase example 1
743  
744 package Example;
745  
746 use Venus::Class 'with';
747  
748 with 'Venus::Role::Encaseable';
749  
750 sub execute {
751 my ($self) = @_;
752  
753 return $self->uncase;
754 }
755  
756 package main;
757  
758 my $example = Example->new;
759  
760 # bless({}, 'Example')
761  
762 # $example->execute;
763  
764 # undef
765  
766 =back
767  
768 =over 4
769  
770 =item uncase example 2
771  
772 package Example;
773  
774 use Venus::Class 'with';
775  
776 with 'Venus::Role::Encaseable';
777  
778 sub execute {
779 my ($self) = @_;
780  
781 return $self->uncase('count');
782 }
783  
784 package main;
785  
786 my $example = Example->new;
787  
788 # bless({}, 'Example')
789  
790 # $example->execute;
791  
792 # undef
793  
794 =back
795  
796 =over 4
797  
798 =item uncase example 3
799  
800 package Example;
801  
802 use Venus::Class 'with';
803  
804 with 'Venus::Role::Encaseable';
805  
806 sub execute {
807 my ($self) = @_;
808  
809 my $count = 1;
810  
811 $self->encase('count', $count);
812  
813 return $self->uncase('count');
814 }
815  
816 package main;
817  
818 my $example = Example->new;
819  
820 # bless({}, 'Example')
821  
822 # $example->execute;
823  
824 # 1
825  
826 =back
827  
828 =over 4
829  
830 =item uncase example 4
831  
832 package Example;
833  
834 use Venus::Class 'with';
835  
836 with 'Venus::Role::Encaseable';
837  
838 sub execute {
839 my ($self) = @_;
840  
841 my $count = 1;
842  
843 $self->encase('count', $count);
844  
845 $count = $self->uncase('count');
846  
847 return $self->uncase('count');
848 }
849  
850 package main;
851  
852 my $example = Example->new;
853  
854 # bless({}, 'Example')
855  
856 # $example->execute;
857  
858 # undef
859  
860 =back
861  
862 =over 4
863  
864 =item uncase example 5
865  
866 package Example;
867  
868 use Venus::Class 'with';
869  
870 with 'Venus::Role::Encaseable';
871  
872 sub execute {
873 my ($self) = @_;
874  
875 return $self->uncase('count');
876 }
877  
878 package main;
879  
880 my $execute = Example->execute;
881  
882 # Exception! Venus::Fault
883  
884 =back
885  
886 =over 4
887  
888 =item uncase example 6
889  
890 package Example;
891  
892 use Venus::Class 'with';
893  
894 with 'Venus::Role::Encaseable';
895  
896 sub execute {
897 my ($self) = @_;
898  
899 return $self->uncase('count');
900 }
901  
902 package main;
903  
904 my $example = Example->new;
905  
906 $example->uncase('count');
907  
908 # Exception! Venus::Fault
909  
910 =back
911  
912 =cut
913  
914 =head1 AUTHORS
915  
916 Awncorp, C<awncorp@cpan.org>
917  
918 =cut
919  
920 =head1 LICENSE
921  
922 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
923  
924 This program is free software, you can redistribute it and/or modify it under
925 the terms of the Apache license version 2.0.
926  
927 =cut
« blib/lib/Venus/Task.pm ↑ Summary blib/lib/Venus/Hook.pm »