blib/lib/Venus/Schema.pm

filter: Statementstmt 93.9% 78 / 83 Branchbran 80.5% 29 / 36 Conditioncond 84.6% 11 / 13 MC/DCmcdc 42.8% 3 / 7 Subroutinesub 100% 9 / 9 Podpod 100% 5 / 5 totaltotal 88.2% 135 / 153 CC 30 SCAR 24.1
CC
30
Cov
89%
validate
17.2
shorthand
11.1
ruleset
3.0
CRAP 11.1
« blib/lib/Venus/Role/Serializable.pm ↑ Summary blib/lib/Venus/Cli.pm »
1 package Venus::Schema;
2  
3 3 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 3 ▶use Venus::Class 'base', 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 3 base 'Venus::Kind::Utility';
15  
16 # INTEGRATES
17  
18 3 with 'Venus::Role::Encaseable';
19  
20 # METHODS
21  
22 62 ▶sub rule {
Subroutine rule: called CC=2 SCAR=6.9
Pod documented
23 62 my ($self, $data) = @_;
24  
25 62 my $ruleset = $self->ruleset;
26  
27 62 ▶ push @{$ruleset}, $data if ref $data eq 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
if ref $data eq "HASH" 61 1 62
28  
29 62 return $self;
30 }
31  
32 28 ▶sub rules {
Subroutine rules: called CC=2 SCAR=6.9
Pod documented
33 28 my ($self, @data) = @_;
34  
35 28 $self->rule($_) for @data;
36  
37 28 return $self;
38 }
39  
40 102 ▶sub ruleset {
Subroutine ruleset: called CC=3 SCAR=11.0
Pod documented
41 102 my ($self, $data) = @_;
42  
43 102 my $ruleset = $self->encased('ruleset');
44  
45 102 ▶ $ruleset = $self->recase('ruleset', ref $data eq 'ARRAY' ? $data : []) if !$ruleset;
Branch: 2 branches
BranchTrueFalseTotal
unless $ruleset 40 62 102
ref $data eq 'ARRAY' ? : 1 39 40
46  
47 102 return $ruleset;
48 }
49  
50 11 ▶sub shorthand {
Subroutine shorthand: called CC=10 SCAR=24.0
Pod documented
51 11 my ($self, $data) = @_;
52  
53 11 my @pairs;
54  
55 11 ▶ if (ref $data eq 'ARRAY') {
Branch: 2 branches
BranchTrueFalseTotal
if (ref $data eq 'ARRAY') { } 11 0 11
elsif (ref $data eq 'HASH') { } 0 0 0
56 11 ▶ for (my $i = 0; $i < @{$data}; $i += 2) {
Branch: 1 branch
BranchTrueFalseTotal
if ($i < @{$data;}) 23 11 34
57 23 push @pairs, [$data->[$i], $data->[$i + 1]];
58 }
59 }
60 elsif (ref $data eq 'HASH') {
61 0 ▶ while (my ($key, $value) = each %{$data}) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %{$data;}) 0 0 0
62 0 push @pairs, [$key, $value];
63 }
64 }
65 else {
66 0 return [];
67 }
68  
69 11 my @ruleset;
70  
71 11 for my $pair (@pairs) {
72 23 my ($key, $type) = @{$pair};
73  
74 23 my $presence = 'required';
75  
76 23 ▶ if ($key =~ s/!$//) {
Branch: 3 branches
BranchTrueFalseTotal
if ($key =~ s/!$//u) { } 12 11 23
elsif ($key =~ s/\?$//u) { } 3 8 11
elsif ($key =~ s/\*$//u) { } 1 7 8
77 12 $presence = 'required';
78 }
79 elsif ($key =~ s/\?$//) {
80 3 $presence = 'optional';
81 }
82 elsif ($key =~ s/\*$//) {
83 1 $presence = 'present';
84 }
85  
86 23 my $selector;
87  
88 23 ▶ if ($key =~ /\./) {
Branch: 1 branch
BranchTrueFalseTotal
if ($key =~ /\./u) { } 3 20 23
89 3 $selector = [split /\./, $key];
90 }
91 else {
92 20 $selector = $key;
93 }
94  
95 23 push @ruleset, {
96 selector => $selector,
97 presence => $presence,
98 execute => $type,
99 };
100 }
101  
102 11 return \@ruleset;
103 }
104  
105 29 ▶sub validate {
Subroutine validate: called CC=17 SCAR=28.4
Pod documented
106 29 my ($self, $data) = @_;
107  
108 29 require Venus::Validate;
109  
110 29 my $validate = Venus::Validate->new(input => $data);
111  
112 29 my $errors = $validate->errors([]);
113  
114 29 my $ruleset = $self->ruleset;
115  
116 29 for my $rule (@{$ruleset}) {
117 52 my $selector = $rule->{selector};
118 52 ▶ my $presence = $rule->{presence} || 'optional';
Condition50%1/2
$rule->{'presence'} || 'optional'
l!l
520
MC/DC0%0/1
$rule->{'presence'} || 'optional'
$rule->{'presence'}
Truth table50%1/2
A
A= $rule->{'presence'}
Aresult
11
00
119 my $executes = $rule->{executes} || (
120 52 ▶ $rule->{execute} ? [$rule->{execute}] : undef
Branch: 1 branch
BranchTrueFalseTotal
$rule->{'execute'} ? : 15 3 18
Condition100%3/3
$rule->{'executes'} || ($rule->{'execute'} ? [$rule->{'execute'}] : undef)
l!l&&r!l&&!r
34153
MC/DC100%2/2
$rule->{'executes'} || ($rule->{'execute'} ? [$rule->{'execute'}] : undef)
$rule->{'executes'} ($rule->{'execute'} ? [$rule->{'execute'}] : undef)
Truth table100%3/3
A || B
A= $rule->{'executes'}B= ($rule->{'execute'} ? [$rule->{'execute'}] : undef)
ABresult
1X1
011
000
121 );
122  
123 52 ▶ next if $presence ne 'optional' && $presence ne 'present' && $presence ne 'required';
Branch: 1 branch
BranchTrueFalseTotal
if $presence ne "optional" and $presence ne "present" and $presence ne "required" 0 52 52
Condition83%5/6
$presence ne "optional" and $presence ne "present" and $presence ne "required"
!ll&&!rl&&r
4480
$presence ne "optional" and $presence ne "present"
!ll&&!rl&&r
2248
MC/DC0%0/3
$presence ne "optional" and $presence ne "present" and $presence ne "required"
$presence ne "optional" $presence ne "present" $presence ne "required"
Truth table75%3/4
A and B and C
A= $presence ne "optional"B= $presence ne "present"C= $presence ne "required"
ABCresult
0XX0
10X0
1100
1111
124  
125 52 my @nodes;
126  
127 52 ▶ if (defined $selector) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $selector) { } 52 0 52
128 52 ▶ if (ref $selector eq 'ARRAY') {
Branch: 1 branch
BranchTrueFalseTotal
if (ref $selector eq 'ARRAY') { } 5 47 52
129 5 @nodes = ($validate);
130 5 for my $i (0..$#{$selector}) {
131 9 my $path = $selector->[$i];
132 9 ▶ my $method = ($i == $#{$selector}) ? $presence : 'optional';
Branch: 1 branch
BranchTrueFalseTotal
$i == $#{$selector;} ? : 5 4 9
133 9 @nodes = map +($_->each($method, $path)), @nodes;
134 }
135 }
136 else {
137 47 @nodes = ($validate->$presence($selector));
138 }
139 }
140 else {
141 0 @nodes = ($validate->$presence);
142 }
143  
144 52 for my $node (@nodes) {
145 54 ▶ for my $execute (@{$executes || []}) {
Condition100%2/2
$executes || []
l!l
513
MC/DC100%1/1
$executes || []
$executes
Truth table100%2/2
A
A= $executes
Aresult
11
00
146 76 ▶ my ($method, @args) = ref $execute eq 'ARRAY' ? @{$execute} : ($execute);
Branch: 1 branch
BranchTrueFalseTotal
ref $execute eq 'ARRAY' ? : 6 70 76
147  
148 76 $node->$method(@args);
149 }
150 54 $validate->sync($node);
151 }
152 }
153  
154 29 my $value = $validate->value;
155  
156 29 ▶ return wantarray ? ($errors, $value) : $errors;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 23 6 29
157 }
158  
159 3 1;
160  
161  
162  
163 =head1 NAME
164  
165 Venus::Schema - Schema Class
166  
167 =cut
168  
169 =head1 ABSTRACT
170  
171 Schema Class for Perl 5
172  
173 =cut
174  
175 =head1 SYNOPSIS
176  
177 package main;
178  
179 use Venus::Schema;
180  
181 my $schema = Venus::Schema->new;
182  
183 # bless({...}, 'Venus::Schema')
184  
185 # $schema->validate;
186  
187 # ([], undef)
188  
189 =cut
190  
191 =head1 DESCRIPTION
192  
193 This package provides a mechanism for validating complex data structures using
194 data validation rules provided as a ruleset.
195  
196 =cut
197  
198 =head1 INHERITS
199  
200 This package inherits behaviors from:
201  
202 L<Venus::Kind::Utility>
203  
204 =cut
205  
206 =head1 INTEGRATES
207  
208 This package integrates behaviors from:
209  
210 L<Venus::Role::Encaseable>
211  
212 =cut
213  
214 =head1 METHODS
215  
216 This package provides the following methods:
217  
218 =cut
219  
220 =head2 new
221  
222 new(any @args) (Venus::Schema)
223  
224 The new method constructs an instance of the package.
225  
226 I<Since C<4.15>>
227  
228 =over 4
229  
230 =item new example 1
231  
232 package main;
233  
234 use Venus::Schema;
235  
236 my $new = Venus::Schema->new;
237  
238 # bless(..., "Venus::Schema")
239  
240 =back
241  
242 =cut
243  
244 =head2 rule
245  
246 rule(hashref $rule) (Venus::Schema)
247  
248 The rule method appends a new rule to the L</ruleset> to be used during
249 L</validate>, and returns the invocant. A "rule" is a hashref that consists of
250 an optional C<selector> key whose value will be provided to the
251 L<Venus::Validate/select> method, a C<presence> key whose value must be one of
252 the "required", "optional", or "present" L<Venus::Validate> methods, and a
253 C<executes> key whose value must be an arrayref where each element is a
254 L<Venus::Validate> validation method name or an arrayref with a method name and
255 arguments.
256  
257 I<Since C<4.15>>
258  
259 =over 4
260  
261 =item rule example 1
262  
263 # given: synopsis
264  
265 package main;
266  
267 my $rule = $schema->rule;
268  
269 # bless({...}, 'Venus::Schema')
270  
271 =back
272  
273 =over 4
274  
275 =item rule example 2
276  
277 # given: synopsis
278  
279 package main;
280  
281 my $rule = $schema->rule({
282 presence => 'required',
283 executes => ['string'],
284 });
285  
286 # bless({...}, 'Venus::Schema')
287  
288 =back
289  
290 =over 4
291  
292 =item rule example 3
293  
294 # given: synopsis
295  
296 package main;
297  
298 my $rule = $schema->rule({
299 selector => 'name',
300 presence => 'required',
301 executes => ['string'],
302 });
303  
304 # bless({...}, 'Venus::Schema')
305  
306 =back
307  
308 =over 4
309  
310 =item rule example 4
311  
312 # given: synopsis
313  
314 package main;
315  
316 my $rule = $schema->rule({
317 selector => 'name',
318 presence => 'required',
319 executes => [['type', 'string']],
320 });
321  
322 # bless({...}, 'Venus::Schema')
323  
324 =back
325  
326 =cut
327  
328 =head2 rules
329  
330 rules(hashref @rules) (Venus::Schema)
331  
332 The rules method appends new rules to the L</ruleset> using the L</rule> method
333 and returns the invocant.
334  
335 I<Since C<4.15>>
336  
337 =over 4
338  
339 =item rules example 1
340  
341 # given: synopsis
342  
343 package main;
344  
345 my $rules = $schema->rules;
346  
347 # bless(..., "Venus::Schema")
348  
349 =back
350  
351 =over 4
352  
353 =item rules example 2
354  
355 # given: synopsis
356  
357 package main;
358  
359 my $rules = $schema->rules({
360 presence => 'required',
361 executes => ['string'],
362 });
363  
364 # bless(..., "Venus::Schema")
365  
366 =back
367  
368 =over 4
369  
370 =item rules example 3
371  
372 # given: synopsis
373  
374 package main;
375  
376 my $rules = $schema->rules(
377 {
378 selector => 'first_name',
379 presence => 'required',
380 executes => ['string'],
381 },
382 {
383 selector => 'last_name',
384 presence => 'required',
385 executes => ['string'],
386 }
387 );
388  
389 # bless(..., "Venus::Schema")
390  
391 =back
392  
393 =cut
394  
395 =head2 ruleset
396  
397 ruleset(arrayref $ruleset) (arrayref)
398  
399 The ruleset method gets and sets the L<"rules"|/rule> to be used during
400 L<"validation"|/validate>.
401  
402 I<Since C<4.15>>
403  
404 =over 4
405  
406 =item ruleset example 1
407  
408 # given: synopsis
409  
410 package main;
411  
412 my $ruleset = $schema->ruleset;
413  
414 # []
415  
416 =back
417  
418 =over 4
419  
420 =item ruleset example 2
421  
422 # given: synopsis
423  
424 package main;
425  
426 my $ruleset = $schema->ruleset([
427 {
428 selector => 'first_name',
429 presence => 'required',
430 executes => ['string'],
431 },
432 {
433 selector => 'last_name',
434 presence => 'required',
435 executes => ['string'],
436 }
437 ]);
438  
439 # [
440 # {
441 # selector => 'first_name',
442 # presence => 'required',
443 # executes => ['string'],
444 # },
445 # {
446 # selector => 'last_name',
447 # presence => 'required',
448 # executes => ['string'],
449 # }
450 # ]
451  
452 =back
453  
454 =cut
455  
456 =head2 shorthand
457  
458 shorthand(arrayref | hashref $data) (arrayref)
459  
460 The shorthand method accepts an arrayref or hashref of shorthand notation and
461 returns a ruleset arrayref. This provides a concise way to define validation
462 rules. Keys can have suffixes to indicate presence: C<!> for (explicit)
463 required, C<?> (explicit) for optional, C<*> for (explicit) present (i.e., must
464 exist but can be null), and no suffix means (implicit) required. Keys using dot
465 notation (e.g., C<website.url>) result in arrayref selectors for nested path
466 validation.
467  
468 I<Since C<4.15>>
469  
470 =over 4
471  
472 =item shorthand example 1
473  
474 # given: synopsis
475  
476 package main;
477  
478 my $shorthand = $schema->shorthand([
479 'fname!' => 'string',
480 'lname!' => 'string',
481 ]);
482  
483 # [
484 # {
485 # selector => 'fname',
486 # presence => 'required',
487 # execute => 'string',
488 # },
489 # {
490 # selector => 'lname',
491 # presence => 'required',
492 # execute => 'string',
493 # },
494 # ]
495  
496 =back
497  
498 =over 4
499  
500 =item shorthand example 2
501  
502 # given: synopsis
503  
504 package main;
505  
506 my $shorthand = $schema->shorthand([
507 'email?' => 'string',
508 'age*' => 'number',
509 ]);
510  
511 # [
512 # {
513 # selector => 'email',
514 # presence => 'optional',
515 # execute => 'string',
516 # },
517 # {
518 # selector => 'age',
519 # presence => 'present',
520 # execute => 'number',
521 # },
522 # ]
523  
524 =back
525  
526 =over 4
527  
528 =item shorthand example 3
529  
530 # given: synopsis
531  
532 package main;
533  
534 my $shorthand = $schema->shorthand([
535 'login' => 'string',
536 'password' => 'string',
537 ]);
538  
539 # [
540 # {
541 # selector => 'login',
542 # presence => 'required',
543 # execute => 'string',
544 # },
545 # {
546 # selector => 'password',
547 # presence => 'required',
548 # execute => 'string',
549 # },
550 # ]
551  
552 =back
553  
554 =over 4
555  
556 =item shorthand example 4
557  
558 # given: synopsis
559  
560 package main;
561  
562 my $shorthand = $schema->shorthand([
563 'website.url' => 'string',
564 'profile.bio.text' => 'string',
565 ]);
566  
567 # [
568 # {
569 # selector => ['website', 'url'],
570 # presence => 'required',
571 # execute => 'string',
572 # },
573 # {
574 # selector => ['profile', 'bio', 'text'],
575 # presence => 'required',
576 # execute => 'string',
577 # },
578 # ]
579  
580 =back
581  
582 =over 4
583  
584 =item shorthand example 5
585  
586 package main;
587  
588 use Venus::Schema;
589  
590 my $schema = Venus::Schema->new;
591  
592 my $ruleset = $schema->shorthand([
593 'fname!' => 'string',
594 'lname!' => 'string',
595 'email?' => 'string',
596 'login' => 'string',
597 ]);
598  
599 $schema->rules(@{$ruleset});
600  
601 my $input = {
602 fname => 'Elliot',
603 lname => 'Alderson',
604 login => 'mrrobot',
605 };
606  
607 my $errors = $schema->validate($input);
608  
609 # []
610  
611 =back
612  
613 =cut
614  
615 =head2 validate
616  
617 validate(any $data) (arrayref)
618  
619 The validate method validates the data provided using the L</ruleset> and
620 returns an arrayref containing the errors encountered, if any. Returns the
621 errors arrayref, and the data validated in list context.
622  
623 I<Since C<4.15>>
624  
625 =over 4
626  
627 =item validate example 1
628  
629 package main;
630  
631 use Venus::Schema;
632  
633 my $schema = Venus::Schema->new;
634  
635 my $errors = $schema->validate;
636  
637 # []
638  
639 =back
640  
641 =over 4
642  
643 =item validate example 2
644  
645 package main;
646  
647 use Venus::Schema;
648  
649 my $schema = Venus::Schema->new;
650  
651 $schema->rule({
652 selector => 'handles',
653 presence => 'required',
654 executes => [['type', 'arrayref']],
655 });
656  
657 my $errors = $schema->validate;
658  
659 # [['handles', ['required', []]]]
660  
661 =back
662  
663 =over 4
664  
665 =item validate example 3
666  
667 package main;
668  
669 use Venus::Schema;
670  
671 my $schema = Venus::Schema->new;
672  
673 my $input = {
674 fname => 'Elliot',
675 lname => 'Alderson',
676 handles => [
677 {name => 'mrrobot'},
678 {name => 'fsociety'},
679 ],
680 level => 5,
681 skills => undef,
682 role => 'Engineer',
683 };
684  
685 $schema->rule({
686 selector => 'fname',
687 presence => 'required',
688 executes => ['string', 'trim', 'strip'],
689 });
690  
691 $schema->rule({
692 selector => 'lname',
693 presence => 'required',
694 executes => ['string', 'trim', 'strip'],
695 });
696  
697 $schema->rule({
698 selector => 'skills',
699 presence => 'present',
700 });
701  
702 $schema->rule({
703 selector => 'handles',
704 presence => 'required',
705 executes => [['type', 'arrayref']],
706 });
707  
708 $schema->rule({
709 selector => ['handles', 'name'],
710 presence => 'required',
711 executes => ['string', 'trim', 'strip'],
712 });
713  
714 my $errors = $schema->validate($input);
715  
716 # []
717  
718 =back
719  
720 =over 4
721  
722 =item validate example 4
723  
724 package main;
725  
726 use Venus::Schema;
727  
728 my $schema = Venus::Schema->new;
729  
730 my $input = {
731 fname => 'Elliot',
732 lname => 'Alderson',
733 handles => [
734 {name => 'mrrobot'},
735 {name => 'fsociety'},
736 ],
737 level => 5,
738 skills => undef,
739 role => 'Engineer',
740 };
741  
742 $schema->rule({
743 selector => 'fname',
744 presence => 'required',
745 executes => ['string', 'trim', 'strip'],
746 });
747  
748 $schema->rule({
749 selector => 'lname',
750 presence => 'required',
751 executes => ['string', 'trim', 'strip'],
752 });
753  
754 $schema->rule({
755 selector => 'skills',
756 presence => 'required',
757 });
758  
759 $schema->rule({
760 selector => 'handles',
761 presence => 'required',
762 executes => [['type', 'arrayref']],
763 });
764  
765 $schema->rule({
766 selector => ['handles', 'name'],
767 presence => 'required',
768 executes => ['string', 'trim', 'strip'],
769 });
770  
771 my $errors = $schema->validate($input);
772  
773 # [['skills', ['required', []]]]
774  
775 =back
776  
777 =cut
778  
779 =head1 AUTHORS
780  
781 Awncorp, C<awncorp@cpan.org>
782  
783 =cut
784  
785 =head1 LICENSE
786  
787 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
788  
789 This program is free software, you can redistribute it and/or modify it under
790 the terms of the Apache license version 2.0.
791  
792 =cut
« blib/lib/Venus/Role/Serializable.pm ↑ Summary blib/lib/Venus/Cli.pm »