blib/lib/Venus/Data.pm

filter: Statementstmt 96.9% 64 / 66 Branchbran 83.3% 10 / 12 Conditioncond 66.6% 2 / 3 MC/DCmcdc 0.0% 0 / 2 Subroutinesub 100% 11 / 11 Podpod 85.7% 6 / 7 totaltotal 92.0% 93 / 101 CC 9 SCAR 10.3
CC
9
Cov
94%
validate
5.0
build_self
4.1
valid
2.0
CRAP 2.8
« blib/lib/Venus/Unpack.pm ↑ Summary blib/lib/Venus/Role/Printable.pm »
1 package Venus::Data;
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 'base', 'mask';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 2 base 'Venus::Kind::Utility';
15  
16 # ATTRIBUTES
17  
18 2 mask 'issues';
19 2 mask 'ruleset';
20 2 mask 'validated';
21 2 mask 'value';
22  
23 # BUILDERS
24  
25 27 ▶sub build_self {
Subroutine build_self: called CC=4 SCAR=14.1
Pod undocumented
26 27 my ($self, $data) = @_;
27  
28 27 my $value = delete $data->{value};
29  
30 27 my $ruleset = delete $data->{ruleset};
31  
32 0 ▶ $value = {%{$data}} if !$value && keys %{$data};
Branch: 1 branch
BranchTrueFalseTotal
if not $value and keys %{$data;} 0 27 27
Condition66%2/3
not $value and keys %{$data;}
!ll&&!rl&&r
2520
MC/DC0%0/2
not $value and keys %{$data;}
not $value keys %{$data;}
Truth table66%2/3
not(A) and B
A= not $valueB= keys %{$data;}
ABresult
0X0
100
111
33  
34 27 require Venus;
35  
36 27 $self->value(Venus::clone($value));
37  
38 27 $self->ruleset(Venus::clone($ruleset));
39  
40 27 delete $self->{$_} for keys %{$self};
41  
42 27 return $self;
43 }
44  
45 # METHODS
46  
47 3 ▶sub error {
Subroutine error: called CC=1 SCAR=0.0
Pod documented
48 3 my ($self) = @_;
49  
50 3 my $errors = $self->errors;
51  
52 3 return $errors->[0];
53 }
54  
55 7 ▶sub errors {
Subroutine errors: called CC=1 SCAR=0.0
Pod documented
56 7 my ($self) = @_;
57  
58 7 require Venus;
59  
60 7 my $issues = $self->issues;
61  
62 7 return Venus::clone($issues);
63 }
64  
65 2 ▶sub renew {
Subroutine renew: called CC=1 SCAR=0.0
Pod documented
66 2 my ($self, @args) = @_;
67  
68 2 my $data = $self->ARGS(@args);
69  
70 2 $data->{ruleset} = $self->ruleset;
71  
72 2 return $self->class->new($data);
73 }
74  
75 6 ▶sub shorthand {
Subroutine shorthand: called CC=1 SCAR=0.0
Pod documented
76 6 my ($self, $data) = @_;
77  
78 6 require Venus::Schema;
79  
80 6 my $ruleset = Venus::Schema->shorthand($data);
81  
82 6 $self->ruleset($ruleset);
83  
84 6 return $self;
85 }
86  
87 9 ▶sub valid {
Subroutine valid: called CC=2 SCAR=6.9
Pod documented
88 9 my ($self) = @_;
89  
90 9 ▶ $self->validate if !defined $self->validated;
Branch: 1 branch
BranchTrueFalseTotal
unless defined $self->validated 8 1 9
91  
92 9 return $self->validated;
93 }
94  
95 24 ▶sub validate {
Subroutine validate: called CC=5 SCAR=16.1
Pod documented
96 24 my ($self) = @_;
97  
98 24 require Venus;
99  
100 24 ▶ return $self->validated
Branch: 2 branches
BranchTrueFalseTotal
if defined $self->validated 1 23 24
$self->validated ? : 1 0 1
101 ? Venus::clone($self->value)
102 : undef
103 if defined $self->validated;
104  
105 23 require Venus::Schema;
106  
107 my $schema = Venus::Schema->new->rules(
108 $self->ruleset
109 23 ▶ ? @{$self->ruleset}
Branch: 1 branch
BranchTrueFalseTotal
$self->ruleset ? : 22 1 23
110 : ()
111 );
112  
113 23 my ($errors, $value) = $schema->validate($self->value);
114  
115 23 ▶ if (@{$errors}) {
Branch: 1 branch
BranchTrueFalseTotal
if (@{$errors;}) { } 9 14 23
116 9 $self->validated(false);
117 9 $self->issues($errors);
118 9 $self->value($value);
119 9 return undef;
120 }
121 else {
122 14 $self->validated(true);
123 14 $self->issues([]);
124 14 $self->value($value);
125 14 return Venus::clone($value);
126 }
127  
128 0 return $self;
129 }
130  
131 2 1;
132  
133  
134 =head1 NAME
135  
136 Venus::Data - Data Class
137  
138 =cut
139  
140 =head1 ABSTRACT
141  
142 Data Class for Perl 5
143  
144 =cut
145  
146 =head1 SYNOPSIS
147  
148 package main;
149  
150 use Venus::Data;
151  
152 my $data = Venus::Data->new;
153  
154 # bless({}, 'Venus::Data')
155  
156 =cut
157  
158 =head1 DESCRIPTION
159  
160 This package provides a value object for encapsulating data validation. It
161 represents a single immutable validation attempt, ensuring unvalidated data
162 cannot be observed. Validation runs at most once per instance, with all
163 observable outcomes flowing from that validation. The big idea is that the
164 schema (or ruleset) is a contract, and if the validate was success you can be
165 certain that the data (or value) is valid and conforms with the schema.
166  
167 =cut
168  
169 =head1 INHERITS
170  
171 This package inherits behaviors from:
172  
173 L<Venus::Kind::Utility>
174  
175 =cut
176  
177 =head1 METHODS
178  
179 This package provides the following methods:
180  
181 =cut
182  
183 =head2 error
184  
185 error() (arrayref)
186  
187 The error method returns the first validation error as an arrayref in the
188 format C<[path, [error_type, args]]>, or undef if no errors exist. This is a
189 convenience method for accessing the first error when you don't need the
190 complete error list. Call C</validate> or C</valid> first to ensure validation
191 has run.
192  
193 I<Since C<4.15>>
194  
195 =over 4
196  
197 =item error example 1
198  
199 package main;
200  
201 use Venus::Data;
202  
203 my $data = Venus::Data->new(
204 value => {
205 name => undef,
206 },
207 ruleset => [
208 {
209 selector => 'name',
210 presence => 'required',
211 executes => ['string']
212 },
213 ],
214 );
215  
216 $data->validate;
217  
218 my $error = $data->error;
219  
220 # ['name', ['required', []]]
221  
222 =back
223  
224 =over 4
225  
226 =item error example 2
227  
228 package main;
229  
230 use Venus::Data;
231  
232 my $data = Venus::Data->new(
233 value => {
234 name => 'Example',
235 },
236 ruleset => [
237 {
238 selector => 'name',
239 presence => 'required',
240 executes => ['string']
241 },
242 ],
243 );
244  
245 $data->validate;
246  
247 my $error = $data->error;
248  
249 # undef
250  
251 =back
252  
253 =over 4
254  
255 =item error example 3
256  
257 package main;
258  
259 use Venus::Data;
260  
261 my $data = Venus::Data->new(
262 value => {
263 name => 123,
264 },
265 ruleset => [
266 {
267 selector => 'name',
268 presence => 'required',
269 executes => [['type', 'string']]
270 },
271 ],
272 );
273  
274 $data->validate;
275  
276 my $error = $data->error;
277  
278 # ['name', ['type', ['string']]]
279  
280 =back
281  
282 =cut
283  
284 =head2 errors
285  
286 errors() (within[arrayref, arrayref])
287  
288 The errors method returns an arrayref of all validation errors. Each error is
289 an arrayref with the format C<[path, [error_type, args]]> where path indicates
290 which field failed and C<error_type> describes the failure (e.g., 'required',
291 'type', etc). Returns an empty arrayref if validation succeeded or hasn't run
292 yet.
293  
294 I<Since C<4.15>>
295  
296 =over 4
297  
298 =item errors example 1
299  
300 package main;
301  
302 use Venus::Data;
303  
304 my $data = Venus::Data->new(
305 value => {
306 name => undef,
307 age => 'invalid'
308 },
309 ruleset => [
310 {
311 selector => 'name',
312 presence => 'required',
313 executes => ['string']
314 },
315 {
316 selector => 'age',
317 presence => 'required',
318 executes => ['number']
319 },
320 ],
321 );
322  
323 $data->validate;
324  
325 my $errors = $data->errors;
326  
327 # [
328 # ['name', ['required', []]],
329 # ['age', ['number', []]],
330 # ]
331  
332 =back
333  
334 =over 4
335  
336 =item errors example 2
337  
338 package main;
339  
340 use Venus::Data;
341  
342 my $data = Venus::Data->new(
343 value => {
344 name => 'Example',
345 age => 25
346 },
347 ruleset => [
348 {
349 selector => 'name',
350 presence => 'required',
351 executes => ['string']
352 },
353 {
354 selector => 'age',
355 presence => 'required',
356 executes => ['number']
357 },
358 ],
359 );
360  
361 $data->validate;
362  
363 my $errors = $data->errors;
364  
365 # []
366  
367 =back
368  
369 =over 4
370  
371 =item errors example 3
372  
373 package main;
374  
375 use Venus::Data;
376  
377 my $data = Venus::Data->new(
378 value => {
379 name => 123,
380 email => undef
381 },
382 ruleset => [
383 {
384 selector => 'name',
385 presence => 'required',
386 executes => [['type', 'string']]
387 },
388 {
389 selector => 'email',
390 presence => 'required',
391 executes => ['string']
392 },
393 ],
394 );
395  
396 $data->validate;
397  
398 my $errors = $data->errors;
399  
400 # [
401 # ['name', ['type', ['string']]],
402 # ['email', ['required', []]],
403 # ]
404  
405 =back
406  
407 =cut
408  
409 =head2 new
410  
411 new(any @args) (Venus::Data)
412  
413 The new method constructs an instance of the package.
414  
415 I<Since C<4.15>>
416  
417 =over 4
418  
419 =item new example 1
420  
421 package main;
422  
423 use Venus::Data;
424  
425 my $data = Venus::Data->new;
426  
427 # bless({}, 'Venus::Data')
428  
429 =back
430  
431 =cut
432  
433 =head2 renew
434  
435 renew(any @args) (object)
436  
437 The renew method creates a new instance with updated arguments while preserving
438 the ruleset from the current instance. This is the best way to "update" the
439 value while maintaining the ruleset. The new instance will have its validation
440 state reset and will need to be validated again.
441  
442 I<Since C<4.15>>
443  
444 =over 4
445  
446 =item renew example 1
447  
448 package main;
449  
450 use Venus::Data;
451  
452 my $data = Venus::Data->new(
453 value => {
454 name => 'Example',
455 },
456 ruleset => [
457 {
458 selector => 'name',
459 presence => 'required',
460 executes => ['string']
461 },
462 ],
463 );
464  
465 my $renewed = $data->renew(value => {name => 'Updated'});
466  
467 # bless({...}, 'Venus::Data')
468  
469 =back
470  
471 =over 4
472  
473 =item renew example 2
474  
475 package main;
476  
477 use Venus::Data;
478  
479 my $data = Venus::Data->new(
480 value => {
481 name => 'Example',
482 age => 25
483 },
484 ruleset => [
485 {
486 selector => 'name',
487 presence => 'required',
488 executes => ['string']
489 },
490 {
491 selector => 'age',
492 presence => 'required',
493 executes => ['number']
494 },
495 ],
496 );
497  
498 $data->validate;
499  
500 my $renewed = $data->renew({value => {name => 'Updated', age => 30}});
501  
502 # bless({}, 'Venus::Data')
503  
504 =back
505  
506 =cut
507  
508 =head2 shorthand
509  
510 shorthand(arrayref | hashref $data) (Venus::Data)
511  
512 The shorthand method accepts an arrayref or hashref of shorthand notation and
513 sets the ruleset on the instance using L<Venus::Schema/shorthand>. This
514 provides a concise way to define validation rules. Keys can have suffixes to
515 indicate presence: C<!> for (explicit) required, C<?> (explicit) for optional,
516 C<*> for (explicit) present (i.e., must exist but can be null), and no suffix
517 means (implicit) required. Keys using dot notation (e.g., C<website.url>)
518 result in arrayref selectors for nested path validation. Returns the invocant
519 for method chaining.
520  
521 I<Since C<4.15>>
522  
523 =over 4
524  
525 =item shorthand example 1
526  
527 package main;
528  
529 use Venus::Data;
530  
531 my $data = Venus::Data->new(
532 value => {
533 fname => 'Elliot',
534 lname => 'Alderson',
535 },
536 );
537  
538 $data->shorthand([
539 'fname!' => 'string',
540 'lname!' => 'string',
541 ]);
542  
543 my $valid = $data->valid;
544  
545 # 1
546  
547 =back
548  
549 =over 4
550  
551 =item shorthand example 2
552  
553 package main;
554  
555 use Venus::Data;
556  
557 my $data = Venus::Data->new(
558 value => {
559 fname => 'Elliot',
560 },
561 );
562  
563 $data->shorthand([
564 'fname!' => 'string',
565 'lname!' => 'string',
566 ]);
567  
568 my $valid = $data->valid;
569  
570 # 0
571  
572 =back
573  
574 =over 4
575  
576 =item shorthand example 3
577  
578 package main;
579  
580 use Venus::Data;
581  
582 my $data = Venus::Data->new(
583 value => {
584 fname => 'Elliot',
585 lname => 'Alderson',
586 login => 'mrrobot',
587 },
588 );
589  
590 $data->shorthand([
591 'fname!' => 'string',
592 'lname!' => 'string',
593 'email?' => 'string',
594 'login' => 'string',
595 ]);
596  
597 my $validated = $data->validate;
598  
599 # {fname => 'Elliot', lname => 'Alderson', login => 'mrrobot'}
600  
601 =back
602  
603 =over 4
604  
605 =item shorthand example 4
606  
607 package main;
608  
609 use Venus::Data;
610  
611 my $data = Venus::Data->new(
612 value => {
613 user => {
614 name => 'Elliot',
615 },
616 },
617 );
618  
619 $data->shorthand([
620 'user.name' => 'string',
621 ]);
622  
623 my $validated = $data->validate;
624  
625 # {user => {name => 'Elliot'}}
626  
627 =back
628  
629 =cut
630  
631 =head2 valid
632  
633 valid() (boolean)
634  
635 The valid method returns a boolean indicating whether the data is valid. Triggers
636 validation on first call if not already validated. Subsequent calls return the
637 cached validation state without re-validating. This is the primary way to check
638 if data passed validation.
639  
640 I<Since C<4.15>>
641  
642 =over 4
643  
644 =item valid example 1
645  
646 package main;
647  
648 use Venus::Data;
649  
650 my $data = Venus::Data->new(
651 value => {
652 name => 'Example',
653 },
654 ruleset => [
655 {
656 selector => 'name',
657 presence => 'required',
658 executes => ['string']
659 },
660 ],
661 );
662  
663 my $valid = $data->valid;
664  
665 # 1
666  
667 =back
668  
669 =over 4
670  
671 =item valid example 2
672  
673 package main;
674  
675 use Venus::Data;
676  
677 my $data = Venus::Data->new(
678 value => {
679 name => undef,
680 },
681 ruleset => [
682 {
683 selector => 'name',
684 presence => 'required',
685 executes => ['string']
686 },
687 ],
688 );
689  
690 my $valid = $data->valid;
691  
692 # 0
693  
694 =back
695  
696 =over 4
697  
698 =item valid example 3
699  
700 package main;
701  
702 use Venus::Data;
703  
704 my $data = Venus::Data->new(
705 value => {
706 name => 'Example',
707 },
708 ruleset => [
709 {
710 selector => 'name',
711 presence => 'required',
712 executes => ['string']
713 },
714 ],
715 );
716  
717 my $check_1 = $data->valid;
718  
719 # true
720  
721 my $check_2 = $data->valid;
722  
723 # true (cached)
724  
725 =back
726  
727 =cut
728  
729 =head2 validate
730  
731 validate() (any)
732  
733 The validate method performs validation of the value against the ruleset and
734 returns the validated (and potentially modified) value on success, or undef on
735 failure. Validation runs at most once per instance, and subsequent calls return
736 cached results. The returned value may differ from the original due to
737 transformations applied during validation (e.g., "trim", "strip", "lowercase",
738 etc). After validation, check C</valid> to determine success/failure and
739 C</errors> to get validation errors.
740  
741 I<Since C<4.15>>
742  
743 =over 4
744  
745 =item validate example 1
746  
747 package main;
748  
749 use Venus::Data;
750  
751 my $data = Venus::Data->new(
752 value => {
753 name => ' Example ',
754 },
755 ruleset => [
756 {
757 selector => 'name',
758 presence => 'required',
759 executes => ['string', 'trim']
760 },
761 ],
762 );
763  
764 my $validated = $data->validate;
765  
766 # {name => 'Example'}
767  
768 =back
769  
770 =over 4
771  
772 =item validate example 2
773  
774 package main;
775  
776 use Venus::Data;
777  
778 my $data = Venus::Data->new(
779 value => {
780 name => undef,
781 },
782 ruleset => [
783 {
784 selector => 'name',
785 presence => 'required',
786 executes => ['string']
787 },
788 ],
789 );
790  
791 my $validated = $data->validate;
792  
793 # undef
794  
795 =back
796  
797 =over 4
798  
799 =item validate example 3
800  
801 package main;
802  
803 use Venus::Data;
804  
805 my $data = Venus::Data->new(
806 value => {
807 name => 'Example',
808 },
809 ruleset => [
810 {
811 selector => 'name',
812 presence => 'required',
813 executes => ['string']
814 },
815 ],
816 );
817  
818 my $validated_1 = $data->validate;
819  
820 # {name => 'Example'}
821  
822 my $validated_2 = $data->validate;
823  
824 # {name => 'Example'} (cached)
825  
826 =back
827  
828 =over 4
829  
830 =item validate example 4
831  
832 package main;
833  
834 use Venus::Data;
835  
836 my $data = Venus::Data->new(
837 value => {
838 fname => 'Elliot',
839 },
840 ruleset => [
841 {
842 selector => 'fname',
843 presence => 'required',
844 executes => ['string', 'trim', 'strip'],
845 },
846 {
847 selector => 'lname',
848 presence => 'required',
849 executes => ['string', 'trim', 'strip'],
850 },
851 {
852 selector => 'skills',
853 presence => 'present',
854 },
855 {
856 selector => 'handles',
857 presence => 'required',
858 executes => [['type', 'arrayref']],
859 },
860 {
861 selector => ['handles', 'name'],
862 presence => 'required',
863 executes => ['string', 'trim', 'strip'],
864 },
865 {
866 selector => ['level'],
867 presence => 'required',
868 executes => ['number', 'trim', 'strip'],
869 },
870 ],
871 );
872  
873 my $validated = $data->validate;
874  
875 # undef
876  
877 my $errors = $data->errors;
878  
879 # [
880 # ['lname', ['required', []]],
881 # ['skills', ['present', []]],
882 # ['handles', ['required', []]],
883 # ['handles.name', ['required', []]],
884 # ['level', ['required', []]],
885 # ]
886  
887 =back
888  
889 =cut
890  
891 =head1 AUTHORS
892  
893 Awncorp, C<awncorp@cpan.org>
894  
895 =cut
896  
897 =head1 LICENSE
898  
899 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
900  
901 This program is free software, you can redistribute it and/or modify it under
902 the terms of the Apache license version 2.0.
903  
904 =cut
« blib/lib/Venus/Unpack.pm ↑ Summary blib/lib/Venus/Role/Printable.pm »