blib/lib/Venus/Result.pm

filter: Statementstmt 100% 62 / 62 Branchbran 100% 16 / 16 Conditioncond 100% 14 / 14 MC/DCmcdc 100% 8 / 8 Subroutinesub 100% 14 / 14 Podpod 90.0% 9 / 10 totaltotal 99.1% 123 / 124 CC 15 SCAR 9.7
CC
15
Cov
100%
on_invalid
4.0
on_valid
4.0
attest
3.0
CRAP 2.6
« blib/lib/Venus/Vars.pm ↑ Summary blib/lib/Venus/Number.pm »
1 package Venus::Result;
2  
3 2 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 2 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 2 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 2 ▶use Venus::Class 'attr', 'base', 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 2 base 'Venus::Kind::Utility';
15  
16 # INTEGRATES
17  
18 2 with 'Venus::Role::Buildable';
19 2 with 'Venus::Role::Tryable';
20 2 with 'Venus::Role::Catchable';
21  
22 # ATTRIBUTES
23  
24 2 attr 'issue';
25 2 attr 'value';
26  
27 # BUILDERS
28  
29 52 ▶sub build_self {
Subroutine build_self: called CC=1 SCAR=0.0
Pod undocumented
30 52 my ($self, $data) = @_;
31  
32 52 return $self;
33 }
34  
35 # METHODS
36  
37 5 ▶sub attest {
Subroutine attest: called CC=3 SCAR=11.0
Pod documented
38 5 my ($self, $from, $accept) = @_;
39  
40 5 ▶ $from ||= 'value';
Condition100%2/2
$from ||= "value"
l!l
41
MC/DC100%1/1
$from ||= "value"
$from
Truth table100%2/2
A
A= $from
Aresult
11
00
41  
42 5 my $value = $self->$from;
43  
44 5 require Venus::Assert;
45  
46 5 my $assert = Venus::Assert->new;
47  
48 5 $assert->name("Venus::Result#$from");
49  
50 5 ▶ $assert->expression($accept || 'any');
Condition100%2/2
$accept || 'any'
l!l
41
MC/DC100%1/1
$accept || 'any'
$accept
Truth table100%2/2
A
A= $accept
Aresult
11
00
51  
52 5 return $assert->result($value);
53 }
54  
55 5 ▶sub check {
Subroutine check: called CC=3 SCAR=11.0
Pod documented
56 5 my ($self, $from, $accept) = @_;
57  
58 5 ▶ $from ||= 'value';
Condition100%2/2
$from ||= "value"
l!l
41
MC/DC100%1/1
$from ||= "value"
$from
Truth table100%2/2
A
A= $from
Aresult
11
00
59  
60 5 my $value = $self->$from;
61  
62 5 require Venus::Assert;
63  
64 5 my $assert = Venus::Assert->new;
65  
66 5 $assert->name("Venus::Result#$from");
67  
68 5 ▶ $assert->expression($accept || 'any');
Condition100%2/2
$accept || 'any'
l!l
41
MC/DC100%1/1
$accept || 'any'
$accept
Truth table100%2/2
A
A= $accept
Aresult
11
00
69  
70 5 return $assert->valid($value);
71 }
72  
73 1 ▶sub invalid {
Subroutine invalid: called CC=1 SCAR=0.0
Pod documented
74 1 my ($self, $issue) = @_;
75  
76 1 my $result = $self->class->new(issue => $issue);
77  
78 1 return $result;
79 }
80  
81 4 ▶sub is_invalid {
Subroutine is_invalid: called CC=2 SCAR=6.9
Pod documented
82 4 my ($self) = @_;
83  
84 4 ▶ my $invalid = $self->is_valid ? false : true;
Branch: 1 branch
BranchTrueFalseTotal
$self->is_valid ? : 2 2 4
85  
86 4 return $invalid;
87 }
88  
89 12 ▶sub is_valid {
Subroutine is_valid: called CC=2 SCAR=6.9
Pod documented
90 12 my ($self) = @_;
91  
92 12 ▶ my $valid = $self->issue ? false : true;
Branch: 1 branch
BranchTrueFalseTotal
$self->issue ? : 3 9 12
93  
94 12 return $valid;
95 }
96  
97 5 ▶sub on_invalid {
Subroutine on_invalid: called CC=4 SCAR=13.9
Pod documented
98 5 my ($self, $code, @args) = @_;
99  
100 5 ▶ return $self if !$code || !$self->issue;
Branch: 1 branch
BranchTrueFalseTotal
unless $code and $self->issue 2 3 5
Condition100%3/3
$code and $self->issue
!ll&&!rl&&r
113
MC/DC100%2/2
$code and $self->issue
$code $self->issue
Truth table100%3/3
A and B
A= $codeB= $self->issue
ABresult
0X0
100
111
101  
102 3 my ($issue, $value) = $self->catch($code, @args);
103  
104 3 ▶ my $result = $self->class->new($issue ? (issue => $issue) : (value => $value));
Branch: 1 branch
BranchTrueFalseTotal
$issue ? : 1 2 3
105  
106 3 return $result;
107 }
108  
109 9 ▶sub on_valid {
Subroutine on_valid: called CC=4 SCAR=13.9
Pod documented
110 9 my ($self, $code, @args) = @_;
111  
112 9 ▶ return $self if !$code || $self->issue;
Branch: 1 branch
BranchTrueFalseTotal
if not $code or $self->issue 2 7 9
Condition100%3/3
not $code or $self->issue
l!l&&r!l&&!r
117
MC/DC100%2/2
not $code or $self->issue
not $code $self->issue
Truth table100%3/3
not(A) or B
A= not $codeB= $self->issue
ABresult
1X1
011
000
113  
114 7 my ($issue, $value) = $self->catch($code, @args);
115  
116 7 ▶ my $result = $self->class->new($issue ? (issue => $issue) : (value => $value));
Branch: 1 branch
BranchTrueFalseTotal
$issue ? : 4 3 7
117  
118 7 return $result;
119 }
120  
121 7 ▶sub then {
Subroutine then: called CC=3 SCAR=11.0
Pod documented
122 7 my ($self, $code, @args) = @_;
123  
124 7 ▶ return $self if !$code;
Branch: 1 branch
BranchTrueFalseTotal
unless $code 1 6 7
125  
126 6 ▶ my $method = $self->issue ? 'on_invalid' : 'on_valid';
Branch: 1 branch
BranchTrueFalseTotal
$self->issue ? : 1 5 6
127  
128 6 return $self->$method($code, @args);
129 }
130  
131 1 ▶sub valid {
Subroutine valid: called CC=1 SCAR=0.0
Pod documented
132 1 my ($self, $value) = @_;
133  
134 1 my $result = $self->class->new(value => $value);
135  
136 1 return $result;
137 }
138  
139 2 1;
140  
141  
142  
143 =head1 NAME
144  
145 Venus::Result - Result Class
146  
147 =cut
148  
149 =head1 ABSTRACT
150  
151 Result Class for Perl 5
152  
153 =cut
154  
155 =head1 SYNOPSIS
156  
157 package main;
158  
159 use Venus::Result;
160  
161 my $result = Venus::Result->new;
162  
163 # $result->is_valid;
164  
165 # true
166  
167 =cut
168  
169 =head1 DESCRIPTION
170  
171 This package provides a container for representing success and error states in
172 a more structured and predictable way, and a mechanism for chaining subsequent
173 operations.
174  
175 =cut
176  
177 =head1 ATTRIBUTES
178  
179 This package has the following attributes:
180  
181 =cut
182  
183 =head2 issue
184  
185 issue(any $issue) (any)
186  
187 The issue attribute is read/write, accepts C<(any)> values, and is optional.
188  
189 I<Since C<4.15>>
190  
191 =over 4
192  
193 =item issue example 1
194  
195 # given: synopsis;
196  
197 my $issue = $result->issue("Failed!");
198  
199 # "Failed!"
200  
201 =back
202  
203 =over 4
204  
205 =item issue example 2
206  
207 # given: synopsis;
208  
209 # given: example-1 issue;
210  
211 $issue = $result->issue;
212  
213 # "Failed!"
214  
215 =back
216  
217 =cut
218  
219 =head2 value
220  
221 value(any $value) (any)
222  
223 The valid attribute is read/write, accepts C<(any)> values, and is optional.
224  
225 I<Since C<4.15>>
226  
227 =over 4
228  
229 =item value example 1
230  
231 # given: synopsis;
232  
233 my $value = $result->value("Success!");
234  
235 # "Success!"
236  
237 =back
238  
239 =over 4
240  
241 =item value example 2
242  
243 # given: synopsis;
244  
245 # given: example-1 value;
246  
247 $value = $result->value;
248  
249 # "Success!"
250  
251 =back
252  
253 =cut
254  
255 =head1 INHERITS
256  
257 This package inherits behaviors from:
258  
259 L<Venus::Kind::Utility>
260  
261 =cut
262  
263 =head1 INTEGRATES
264  
265 This package integrates behaviors from:
266  
267 L<Venus::Role::Buildable>
268  
269 L<Venus::Role::Tryable>
270  
271 L<Venus::Role::Catchable>
272  
273 =cut
274  
275 =head1 METHODS
276  
277 This package provides the following methods:
278  
279 =cut
280  
281 =head2 attest
282  
283 attest(string $name, string $expr) (any)
284  
285 The attest method validates the value of the attribute named, i.e. L</issue> or
286 L</value>, using the L<Venus::Assert> expression provided and returns the
287 result.
288  
289 I<Since C<4.15>>
290  
291 =over 4
292  
293 =item attest example 1
294  
295 # given: synopsis
296  
297 package main;
298  
299 my $attest = $result->attest;
300  
301 # undef
302  
303 =back
304  
305 =over 4
306  
307 =item attest example 2
308  
309 # given: synopsis
310  
311 package main;
312  
313 $result->value("Success!");
314  
315 my $attest = $result->attest('value', 'number | string');
316  
317 # "Success!"
318  
319 =back
320  
321 =over 4
322  
323 =item attest example 3
324  
325 # given: synopsis
326  
327 package main;
328  
329 my $attest = $result->attest('value', 'number | string');
330  
331 # Exception! (isa Venus::Check::Error)
332  
333 =back
334  
335 =over 4
336  
337 =item attest example 4
338  
339 # given: synopsis
340  
341 package main;
342  
343 $result->issue("Failed!");
344  
345 my $attest = $result->attest('issue', 'number | string');
346  
347 # "Failed!"
348  
349 =back
350  
351 =over 4
352  
353 =item attest example 5
354  
355 # given: synopsis
356  
357 package main;
358  
359 my $attest = $result->attest('issue', 'number | string');
360  
361 # Exception! (isa Venus::Check::Error)
362  
363 =back
364  
365 =cut
366  
367 =head2 check
368  
369 check(string $name, string $expr) (boolean)
370  
371 The check method validates the value of the attribute named, i.e. L</issue> or
372 L</value>, using the L<Venus::Assert> expression provided and returns the
373 true if the value is valid, and false otherwise.
374  
375 I<Since C<4.15>>
376  
377 =over 4
378  
379 =item check example 1
380  
381 # given: synopsis
382  
383 package main;
384  
385 my $check = $result->check;
386  
387 # true
388  
389 =back
390  
391 =over 4
392  
393 =item check example 2
394  
395 # given: synopsis
396  
397 package main;
398  
399 $result->value("Success!");
400  
401 my $check = $result->check('value', 'number | string');
402  
403 # true
404  
405 =back
406  
407 =over 4
408  
409 =item check example 3
410  
411 # given: synopsis
412  
413 package main;
414  
415 my $check = $result->check('value', 'number | string');
416  
417 # false
418  
419 =back
420  
421 =over 4
422  
423 =item check example 4
424  
425 # given: synopsis
426  
427 package main;
428  
429 $result->issue("Failed!");
430  
431 my $check = $result->check('issue', 'number | string');
432  
433 # true
434  
435 =back
436  
437 =over 4
438  
439 =item check example 5
440  
441 # given: synopsis
442  
443 package main;
444  
445 my $check = $result->check('issue', 'number | string');
446  
447 # false
448  
449 =back
450  
451 =cut
452  
453 =head2 invalid
454  
455 invalid(any $error) (Venus::Result)
456  
457 The invalid method returns a L<Venus::Result> object representing an issue and
458 error state.
459  
460 I<Since C<4.15>>
461  
462 =over 4
463  
464 =item invalid example 1
465  
466 package main;
467  
468 use Venus::Result;
469  
470 my $invalid = Venus::Result->invalid("Failed!");
471  
472 # bless(..., "Venus::Result")
473  
474 =back
475  
476 =cut
477  
478 =head2 is_invalid
479  
480 is_invalid() (boolean)
481  
482 The is_invalid method returns true if an error exists, and false otherwise.
483  
484 I<Since C<4.15>>
485  
486 =over 4
487  
488 =item is_invalid example 1
489  
490 # given: synopsis;
491  
492 my $is_invalid = $result->is_invalid;
493  
494 # false
495  
496 =back
497  
498 =over 4
499  
500 =item is_invalid example 2
501  
502 # given: synopsis;
503  
504 $result->value("Success!");
505  
506 my $is_invalid = $result->is_invalid;
507  
508 # false
509  
510 =back
511  
512 =over 4
513  
514 =item is_invalid example 3
515  
516 # given: synopsis;
517  
518 $result->issue("Failed!");
519  
520 my $is_invalid = $result->is_invalid;
521  
522 # true
523  
524 =back
525  
526 =cut
527  
528 =head2 is_valid
529  
530 is_valid() (boolean)
531  
532 The is_valid method returns true if no error exists, and false otherwise.
533  
534 I<Since C<4.15>>
535  
536 =over 4
537  
538 =item is_valid example 1
539  
540 # given: synopsis;
541  
542 my $is_valid = $result->is_valid;
543  
544 # true
545  
546 =back
547  
548 =over 4
549  
550 =item is_valid example 2
551  
552 # given: synopsis;
553  
554 $result->value("Success!");
555  
556 my $is_valid = $result->is_valid;
557  
558 # true
559  
560 =back
561  
562 =over 4
563  
564 =item is_valid example 3
565  
566 # given: synopsis;
567  
568 $result->issue("Failed!");
569  
570 my $is_valid = $result->is_valid;
571  
572 # false
573  
574 =back
575  
576 =cut
577  
578 =head2 new
579  
580 new(hashref $data) (Venus::Result)
581  
582 The new method returns a L<Venus::Result> object.
583  
584 I<Since C<4.15>>
585  
586 =over 4
587  
588 =item new example 1
589  
590 package main;
591  
592 use Venus::Result;
593  
594 my $new = Venus::Result->new;
595  
596 # bless(..., "Venus::Result")
597  
598 =back
599  
600 =over 4
601  
602 =item new example 2
603  
604 package main;
605  
606 use Venus::Result;
607  
608 my $new = Venus::Result->new(value => "Success!");
609  
610 # bless(..., "Venus::Result")
611  
612 =back
613  
614 =over 4
615  
616 =item new example 3
617  
618 package main;
619  
620 use Venus::Result;
621  
622 my $new = Venus::Result->new({value => "Success!"});
623  
624 # bless(..., "Venus::Result")
625  
626 =back
627  
628 =cut
629  
630 =head2 on_invalid
631  
632 on_invalid(coderef $callback) (Venus::Result)
633  
634 The on_invalid method chains an operations by passing the issue value of the
635 result to the callback provided and returns a L<Venus::Result> object.
636  
637 I<Since C<4.15>>
638  
639 =over 4
640  
641 =item on_invalid example 1
642  
643 # given: synopsis;
644  
645 my $on_invalid = $result->on_invalid;
646  
647 # bless(..., "Venus::Result")
648  
649 =back
650  
651 =over 4
652  
653 =item on_invalid example 2
654  
655 # given: synopsis;
656  
657 my $on_invalid = $result->on_invalid(sub{
658 return "New success!";
659 });
660  
661 # bless(..., "Venus::Result")
662  
663 =back
664  
665 =over 4
666  
667 =item on_invalid example 3
668  
669 # given: synopsis;
670  
671 $result->issue("Failed!");
672  
673 my $on_invalid = $result->on_invalid(sub{
674 return "New success!";
675 });
676  
677 # bless(..., "Venus::Result")
678  
679 =back
680  
681 =over 4
682  
683 =item on_invalid example 4
684  
685 # given: synopsis;
686  
687 $result->issue("Failed!");
688  
689 my $on_invalid = $result->on_invalid(sub{
690 die "New failure!";
691 });
692  
693 # bless(..., "Venus::Result")
694  
695 =back
696  
697 =cut
698  
699 =head2 on_valid
700  
701 on_valid(coderef $callback) (Venus::Result)
702  
703 The on_valid method chains an operations by passing the success value of the
704 result to the callback provided and returns a L<Venus::Result> object.
705  
706 I<Since C<4.15>>
707  
708 =over 4
709  
710 =item on_valid example 1
711  
712 # given: synopsis;
713  
714 my $on_valid = $result->on_valid;
715  
716 # bless(..., "Venus::Result")
717  
718 =back
719  
720 =over 4
721  
722 =item on_valid example 2
723  
724 # given: synopsis;
725  
726 my $on_valid = $result->on_valid(sub{
727 return "New success!";
728 });
729  
730 # bless(..., "Venus::Result")
731  
732 =back
733  
734 =over 4
735  
736 =item on_valid example 3
737  
738 # given: synopsis;
739  
740 $result->issue("Failed!");
741  
742 my $on_valid = $result->on_valid(sub{
743 return "New success!";
744 });
745  
746 # bless(..., "Venus::Result")
747  
748 =back
749  
750 =over 4
751  
752 =item on_valid example 4
753  
754 # given: synopsis;
755  
756 my $on_valid = $result->on_valid(sub{
757 die "New failure!";
758 });
759  
760 # bless(..., "Venus::Result")
761  
762 =back
763  
764 =cut
765  
766 =head2 then
767  
768 then(string | coderef $callback, any @args) (Venus::Result)
769  
770 The then method chains an operations by passing the value or issue of the
771 result to the callback provided and returns a L<Venus::Result> object.
772  
773 I<Since C<4.15>>
774  
775 =over 4
776  
777 =item then example 1
778  
779 # given: synopsis;
780  
781 my $then = $result->then;
782  
783 # bless(..., "Venus::Result")
784  
785 =back
786  
787 =over 4
788  
789 =item then example 2
790  
791 # given: synopsis;
792  
793 my $then = $result->then(sub{
794 return "New success!";
795 });
796  
797 # bless(..., "Venus::Result")
798  
799 =back
800  
801 =over 4
802  
803 =item then example 3
804  
805 # given: synopsis;
806  
807 $result->issue("Failed!");
808  
809 my $then = $result->then(sub{
810 return "New success!";
811 });
812  
813 # bless(..., "Venus::Result")
814  
815 =back
816  
817 =over 4
818  
819 =item then example 4
820  
821 # given: synopsis;
822  
823 my $then = $result->then(sub{
824 die "New failure!";
825 });
826  
827 # bless(..., "Venus::Result")
828  
829 =back
830  
831 =cut
832  
833 =head2 valid
834  
835 valid(any $value) (Venus::Result)
836  
837 The valid method returns a L<Venus::Result> object representing a value and
838 success state.
839  
840 I<Since C<4.15>>
841  
842 =over 4
843  
844 =item valid example 1
845  
846 package main;
847  
848 use Venus::Result;
849  
850 my $valid = Venus::Result->valid("Success!");
851  
852 # bless(..., "Venus::Result")
853  
854 =back
855  
856 =cut
857  
858 =head1 AUTHORS
859  
860 Awncorp, C<awncorp@cpan.org>
861  
862 =cut
863  
864 =head1 LICENSE
865  
866 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
867  
868 This program is free software, you can redistribute it and/or modify it under
869 the terms of the Apache license version 2.0.
870  
871 =cut
« blib/lib/Venus/Vars.pm ↑ Summary blib/lib/Venus/Number.pm »