blib/lib/Venus/Assert.pm

filter: Statementstmt 83.8% 119 / 142 Branchbran 73.0% 38 / 52 Conditioncond 47.9% 23 / 48 MC/DCmcdc 10.0% 3 / 30 Subroutinesub 84.3% 27 / 32 Podpod 72.7% 16 / 22 totaltotal 69.3% 226 / 326 CC 45 SCAR 31.8
CC
45
Cov
74%
received
76.0
expression
6.4
validate
5.0
CRAP 24.0
« blib/lib/Venus/Factory.pm ↑ Summary blib/lib/Venus/Role.pm »
1 package Venus::Assert;
2  
3 11 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 11 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 11 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 11 ▶use Venus::Class 'attr', 'base', 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # INHERITS
13  
14 11 base 'Venus::Kind::Utility';
15  
16 # INTEGRATES
17  
18 11 with 'Venus::Role::Buildable';
19  
20 # OVERLOADS
21  
22 11 ▶use overload (
Subroutine BEGIN: called CC=1 SCAR=0.2
23 0 ▶ '&{}' => sub{$_[0]->validator},
Subroutine __ANON__: not called CC=1 SCAR=6.9
24 11 fallback => 1,
25 11 );
26  
27 # ATTRIBUTES
28  
29 11 attr 'name';
30  
31 # BUILDERS
32  
33 147 ▶sub build_arg {
Subroutine build_arg: called CC=1 SCAR=0.0
Pod undocumented
34 147 my ($self, $name) = @_;
35  
36 return {
37 147 name => $name,
38 };
39 }
40  
41 254 ▶sub build_self {
Subroutine build_self: called CC=1 SCAR=0.0
Pod undocumented
42 254 my ($self, $data) = @_;
43  
44 254 $self->conditions;
45  
46 254 return $self;
47 }
48  
49 # METHODS
50  
51 224 ▶sub accept {
Subroutine accept: called CC=2 SCAR=7.0
Pod documented
52 224 my ($self, $name, @args) = @_;
53  
54 224 ▶ return $self if !$name;
Branch: 1 branch
BranchTrueFalseTotal
unless $name 0 224 224
55  
56 224 $self->check->accept($name, @args);
57  
58 224 return $self;
59 }
60  
61 499 ▶sub check {
Subroutine check: called CC=3 SCAR=11.0
Pod documented
62 499 my ($self, @args) = @_;
63  
64 499 require Venus::Check;
65  
66 499 ▶ $self->{check} = $args[0] if @args;
Branch: 1 branch
BranchTrueFalseTotal
if @args 2 497 499
67  
68 499 ▶ $self->{check} ||= Venus::Check->new;
Condition66%2/3
$self->{"check"} ||= "Venus::Check"->new
l!l&&r!l&&!r
2752240
MC/DC0%0/2
$self->{"check"} ||= "Venus::Check"->new
$self->{"check"} "Venus::Check"->new
Truth table66%2/3
A ||= B
A= $self->{"check"}B= "Venus::Check"->new
ABresult
1X1
011
000
69  
70 499 return $self->{check};
71 }
72  
73 1 ▶sub clear {
Subroutine clear: called CC=1 SCAR=0.0
Pod documented
74 1 my ($self) = @_;
75  
76 1 $self->check->clear;
77 1 $self->constraint->clear;
78 1 $self->coercion->clear;
79  
80 1 return $self;
81 }
82  
83 32 ▶sub coerce {
Subroutine coerce: called CC=1 SCAR=0.0
Pod documented
84 32 my ($self, $data) = @_;
85  
86 32 return $self->coercion->result($self->value($data));
87 }
88  
89 42 ▶sub coercion {
Subroutine coercion: called CC=3 SCAR=11.0
Pod documented
90 42 my ($self, @args) = @_;
91  
92 42 require Venus::Coercion;
93  
94 42 ▶ $self->{coercion} = $args[0] if @args;
Branch: 1 branch
BranchTrueFalseTotal
if @args 2 40 42
95  
96 42 ▶ $self->{coercion} ||= Venus::Coercion->new->do('check', $self->check);
Condition66%2/3
$self->{"coercion"} ||= "Venus::Coercion"->new->do("check", $self->check)
l!l&&r!l&&!r
10320
MC/DC0%0/2
$self->{"coercion"} ||= "Venus::Coercion"->new->do("check", $self->check)
$self->{"coercion"} "Venus::Coercion"->new->do("check", $self->check)
Truth table66%2/3
A ||= B
A= $self->{"coercion"}B= "Venus::Coercion"->new->do("check", $self->check)
ABresult
1X1
011
000
97  
98 42 return $self->{coercion};
99 }
100  
101 254 ▶sub conditions {
Subroutine conditions: called CC=1 SCAR=0.0
Pod documented
102 254 my ($self) = @_;
103  
104 254 return $self;
105 }
106  
107 257 ▶sub constraint {
Subroutine constraint: called CC=3 SCAR=11.0
Pod documented
108 257 my ($self, @args) = @_;
109  
110 257 require Venus::Constraint;
111  
112 257 ▶ $self->{constraint} = $args[0] if @args;
Branch: 1 branch
BranchTrueFalseTotal
if @args 2 255 257
113  
114 257 ▶ $self->{constraint} ||= Venus::Constraint->new->do('check', $self->check);
Condition66%2/3
$self->{"constraint"} ||= "Venus::Constraint"->new->do("check", $self->check)
l!l&&r!l&&!r
372200
MC/DC0%0/2
$self->{"constraint"} ||= "Venus::Constraint"->new->do("check", $self->check)
$self->{"constraint"} "Venus::Constraint"->new->do("check", $self->check)
Truth table66%2/3
A ||= B
A= $self->{"constraint"}B= "Venus::Constraint"->new->do("check", $self->check)
ABresult
1X1
011
000
115  
116 257 return $self->{constraint};
117 }
118  
119 3 ▶sub ensure {
Subroutine ensure: called CC=1 SCAR=0.0
Pod documented
120 3 my ($self, @code) = @_;
121  
122 3 $self->constraint->ensure(@code);
123  
124 3 return $self;
125 }
126  
127 188 ▶sub expression {
Subroutine expression: called CC=6 SCAR=18.5
Pod documented
128 188 my ($self, $data) = @_;
129  
130 188 ▶ return $self if !$data;
Branch: 1 branch
BranchTrueFalseTotal
unless $data 0 188 188
131  
132 188 $data =
133 $data =~ s/\s*\n+\s*/ /gr =~ s/^\s+|\s+$//gr =~ s/\[\s+/[/gr =~ s/\s+\]/]/gr;
134  
135 188 require Venus::Type;
136  
137 188 ▶ $self->name($data) if !$self->name;
Branch: 1 branch
BranchTrueFalseTotal
unless $self->name 92 96 188
138  
139 188 my $parsed = Venus::Type->new->expression($data);
140  
141 188 ▶ $parsed = [$parsed] if !ref $parsed;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $parsed 142 46 188
142  
143 $self->accept(
144 188 ▶ @{$parsed} > 0
Branch: 1 branch
BranchTrueFalseTotal
ref $parsed->[0] eq 'ARRAY' ? : 0 188 188
145 0 ? ((ref $parsed->[0] eq 'ARRAY') ? @{$parsed->[0]} : @{$parsed})
146 0 ▶ : @{$parsed}
Branch: 1 branch
BranchTrueFalseTotal
@{$parsed;} > 0 ? : 188 0 188
147 );
148  
149 188 return $self;
150 }
151  
152 5 ▶sub format {
Subroutine format: called CC=1 SCAR=0.0
Pod documented
153 5 my ($self, @code) = @_;
154  
155 5 $self->coercion->format(@code);
156  
157 5 return $self;
158 }
159  
160 0 ▶sub match {
Subroutine match: not called CC=1 SCAR=6.9
Pod undocumented
161 0 my ($self, @args) = @_;
162  
163 0 require Venus::Coercion;
164 0 my $match = Venus::Coercion->new->accept(@args);
165  
166 0 ▶ push @{$self->matches}, sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
167 0 my ($source, $value) = @_;
168 0 local $_ = $value;
169 0 return $match->result($value);
170 0 };
171  
172 0 return $match;
173 }
174  
175 313 ▶sub matches {
Subroutine matches: called CC=3 SCAR=11.0
Pod undocumented
176 313 my ($self) = @_;
177  
178 313 ▶ my $matches = $self->{'matches'} ||= [];
Condition100%2/2
$self->{"matches"} ||= []
l!l
91222
MC/DC100%1/1
$self->{"matches"} ||= []
$self->{"matches"}
Truth table100%2/2
A
A= $self->{"matches"}
Aresult
11
00
179  
180 313 ▶ return wantarray ? (@{$matches}) : $matches;
Branch: 1 branch
BranchTrueFalseTotal
wantarray ? : 313 0 313
181 }
182  
183 24 ▶sub parse {
Subroutine parse: called CC=3 SCAR=11.0
Pod documented
184 24 my ($self, $expr) = @_;
185  
186 24 ▶ $expr ||= '';
Condition100%2/2
$expr ||= ""
l!l
231
MC/DC100%1/1
$expr ||= ""
$expr
Truth table100%2/2
A
A= $expr
Aresult
11
00
187  
188 24 $expr =
189 $expr =~ s/\s*\n+\s*/ /gr =~ s/^\s+|\s+$//gr =~ s/\[\s+/[/gr =~ s/\s+\]/]/gr;
190  
191 24 require Venus::Type;
192  
193 24 my $parsed = Venus::Type->new->expression($expr);
194  
195 24 ▶ $parsed = [$parsed] if !ref $parsed;
Branch: 1 branch
BranchTrueFalseTotal
unless ref $parsed 4 20 24
196  
197 24 return $parsed;
198 }
199  
200 18 ▶sub received {
Subroutine received: called CC=22 SCAR=43.3
Pod undocumented
201 18 my ($self, $data) = @_;
202  
203 18 require Scalar::Util;
204  
205 18 ▶ if (!defined $data) {
Branch: 1 branch
BranchTrueFalseTotal
unless (defined $data) 3 15 18
206 3 return '';
207 }
208  
209 15 my $blessed = Scalar::Util::blessed($data);
210 15 ▶ my $isvenus = $blessed && $data->isa('Venus::Core') && $data->can('does');
Condition33%2/6
$blessed && $data->isa('Venus::Core') && $data->can('does')
!ll&&!rl&&r
1500
$blessed and $data->isa("Venus::Core")
!ll&&!rl&&r
1500
MC/DC0%0/3
$blessed && $data->isa('Venus::Core') && $data->can('does')
$blessed $data->isa("Venus::Core") $data->can('does')
Truth table25%1/4
A and B && C
A= $blessedB= $data->isa("Venus::Core")C= $data->can('does')
ABCresult
0XX0
10X0
1100
1111
211  
212 15 ▶ if (!$blessed && !ref $data) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($blessed or ref $data) 13 2 15
Condition66%2/3
$blessed or ref $data
l!l&&r!l&&!r
0213
MC/DC50%1/2
$blessed or ref $data
$blessed ref $data
Truth table66%2/3
A or B
A= $blessedB= ref $data
ABresult
1X1
011
000
213 13 return $data;
214 }
215 2 ▶ if ($blessed && ref($data) eq 'Regexp') {
Branch: 1 branch
BranchTrueFalseTotal
if ($blessed and ref $data eq "Regexp") 0 2 2
Condition33%1/3
$blessed and ref $data eq "Regexp"
!ll&&!rl&&r
200
MC/DC0%0/2
$blessed and ref $data eq "Regexp"
$blessed ref $data eq "Regexp"
Truth table33%1/3
A and B
A= $blessedB= ref $data eq "Regexp"
ABresult
0X0
100
111
216 0 return "$data";
217 }
218 2 ▶ if ($isvenus && $data->does('Venus::Role::Explainable')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($isvenus and $data->does("Venus::Role::Explainable")) 0 2 2
Condition33%1/3
$isvenus and $data->does("Venus::Role::Explainable")
!ll&&!rl&&r
200
MC/DC0%0/2
$isvenus and $data->does("Venus::Role::Explainable")
$isvenus $data->does("Venus::Role::Explainable")
Truth table33%1/3
A and B
A= $isvenusB= $data->does("Venus::Role::Explainable")
ABresult
0X0
100
111
219 0 ▶ return $self->dump(sub{$data->explain});
Subroutine __ANON__: not called CC=1 SCAR=6.9
220 }
221 2 ▶ if ($isvenus && $data->does('Venus::Role::Valuable')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($isvenus and $data->does("Venus::Role::Valuable")) 0 2 2
Condition33%1/3
$isvenus and $data->does("Venus::Role::Valuable")
!ll&&!rl&&r
200
MC/DC0%0/2
$isvenus and $data->does("Venus::Role::Valuable")
$isvenus $data->does("Venus::Role::Valuable")
Truth table33%1/3
A and B
A= $isvenusB= $data->does("Venus::Role::Valuable")
ABresult
0X0
100
111
222 0 ▶ return $self->dump(sub{$data->value});
Subroutine __ANON__: not called CC=1 SCAR=6.9
223 }
224 2 ▶ if ($isvenus && $data->does('Venus::Role::Dumpable')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($isvenus and $data->does("Venus::Role::Dumpable")) 0 2 2
Condition33%1/3
$isvenus and $data->does("Venus::Role::Dumpable")
!ll&&!rl&&r
200
MC/DC0%0/2
$isvenus and $data->does("Venus::Role::Dumpable")
$isvenus $data->does("Venus::Role::Dumpable")
Truth table33%1/3
A and B
A= $isvenusB= $data->does("Venus::Role::Dumpable")
ABresult
0X0
100
111
225 0 return $data->dump;
226 }
227 2 ▶ if ($blessed && overload::Method($data, '""')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($blessed and overload::Method($data, "\"\"")) 0 2 2
Condition33%1/3
$blessed and overload::Method($data, "\"\"")
!ll&&!rl&&r
200
MC/DC0%0/2
$blessed and overload::Method($data, "\"\"")
$blessed overload::Method($data, "\"\"")
Truth table33%1/3
A and B
A= $blessedB= overload::Method($data, "\"\"")
ABresult
0X0
100
111
228 0 return "$data";
229 }
230 2 ▶ if ($blessed && $data->can('as_string')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($blessed and $data->can("as_string")) 0 2 2
Condition33%1/3
$blessed and $data->can("as_string")
!ll&&!rl&&r
200
MC/DC0%0/2
$blessed and $data->can("as_string")
$blessed $data->can("as_string")
Truth table33%1/3
A and B
A= $blessedB= $data->can("as_string")
ABresult
0X0
100
111
231 0 return $data->as_string;
232 }
233 2 ▶ if ($blessed && $data->can('to_string')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($blessed and $data->can("to_string")) 0 2 2
Condition33%1/3
$blessed and $data->can("to_string")
!ll&&!rl&&r
200
MC/DC0%0/2
$blessed and $data->can("to_string")
$blessed $data->can("to_string")
Truth table33%1/3
A and B
A= $blessedB= $data->can("to_string")
ABresult
0X0
100
111
234 0 return $data->to_string;
235 }
236 2 ▶ if ($blessed && $data->isa('Venus::Kind')) {
Branch: 1 branch
BranchTrueFalseTotal
if ($blessed and $data->isa('Venus::Kind')) { } 0 2 2
Condition33%1/3
$blessed and $data->isa("Venus::Kind")
!ll&&!rl&&r
200
MC/DC0%0/2
$blessed and $data->isa("Venus::Kind")
$blessed $data->isa("Venus::Kind")
Truth table33%1/3
A and B
A= $blessedB= $data->isa("Venus::Kind")
ABresult
0X0
100
111
237 0 return $data->stringified;
238 }
239 else {
240 2 ▶ return $self->dump(sub{$data});
Subroutine __ANON__: called CC=1 SCAR=0.0
241 }
242 }
243  
244 5 ▶sub render {
Subroutine render: called CC=3 SCAR=11.0
Pod documented
245 5 my ($self, $into, $data) = @_;
246  
247 5 require Venus::Type;
248  
249 5 ▶ return Venus::Type->new->expression([!$into ? $data : ($into, ref $data eq 'ARRAY' ? @{$data} : $data)]);
Branch: 2 branches
BranchTrueFalseTotal
!$into ? : 2 3 5
ref $data eq 'ARRAY' ? : 1 2 3
250 }
251  
252 32 ▶sub result {
Subroutine result: called CC=1 SCAR=0.0
Pod documented
253 32 my ($self, $data) = @_;
254  
255 32 return $self->coerce($self->validate($self->value($data)));
256 }
257  
258 249 ▶sub valid {
Subroutine valid: called CC=1 SCAR=0.0
Pod documented
259 249 my ($self, $data) = @_;
260  
261 249 return $self->constraint->result($self->value($data));
262 }
263  
264 103 ▶sub validate {
Subroutine validate: called CC=5 SCAR=16.2
Pod documented
265 103 my ($self, $data) = @_;
266  
267 103 my $valid = $self->valid($data);
268  
269 103 ▶ return $data if $valid;
Branch: 1 branch
BranchTrueFalseTotal
if $valid 85 18 103
270  
271 18 my $error = $self->check->catch('result');
272  
273 18 my $received = $self->received($data);
274  
275 18 ▶ my $message = join("\n\n",
Branch: 2 branches
BranchTrueFalseTotal
defined $data ? : 15 3 18
$received eq '' ? : 0 15 15
Condition50%1/2
$self->name || 'Unknown'
l!l
180
MC/DC0%0/1
$self->name || 'Unknown'
$self->name
Truth table50%1/2
A
A= $self->name
Aresult
11
00
276 'Type:',
277 ($self->name || 'Unknown'),
278 'Failure:',
279 $error->message,
280 'Received:',
281 (defined $data ? ($received eq '' ? '""' : $received) : ('(undefined)')),
282 );
283  
284 18 $error->message($message);
285  
286 18 return $error->throw;
287 }
288  
289 2 ▶sub validator {
Subroutine validator: called CC=1 SCAR=0.0
Pod documented
290 2 my ($self) = @_;
291  
292 2 return $self->defer('validate');
293 }
294  
295 313 ▶sub value {
Subroutine value: called CC=2 SCAR=7.1
Pod undocumented
296 313 my ($self, $data) = @_;
297  
298 313 my $result = $data;
299  
300 313 for my $match ($self->matches) {
301 0 $result = $match->($self, $result);
302 }
303  
304 313 return $result;
305 }
306  
307 11 1;
308  
309  
310  
311 =head1 NAME
312  
313 Venus::Assert - Assert Class
314  
315 =cut
316  
317 =head1 ABSTRACT
318  
319 Assert Class for Perl 5
320  
321 =cut
322  
323 =head1 SYNOPSIS
324  
325 package main;
326  
327 use Venus::Assert;
328  
329 my $assert = Venus::Assert->new('Float');
330  
331 # $assert->accept('float');
332  
333 # $assert->format(sub{sprintf('%.2f', $_)});
334  
335 # $assert->result(123.456);
336  
337 # 123.46
338  
339 =cut
340  
341 =head1 DESCRIPTION
342  
343 This package provides a mechanism for asserting type constraints and coercions
344 on data. Type constraints are handled via L<Venus::Constraint>, and coercions
345 are handled via L<Venus::Coercion>, using L<Venus::Check> to perform data type
346 validations.
347  
348 =cut
349  
350 =head1 ATTRIBUTES
351  
352 This package has the following attributes:
353  
354 =cut
355  
356 =head2 name
357  
358 name(string $data) (string)
359  
360 The name attribute is read-write, accepts C<(string)> values, and is
361 optional.
362  
363 I<Since C<1.40>>
364  
365 =over 4
366  
367 =item name example 1
368  
369 # given: synopsis
370  
371 package main;
372  
373 my $set_name = $assert->name("Example");
374  
375 # "Example"
376  
377 =back
378  
379 =over 4
380  
381 =item name example 2
382  
383 # given: synopsis
384  
385 # given: example-1 name
386  
387 package main;
388  
389 my $get_name = $assert->name;
390  
391 # "Example"
392  
393 =back
394  
395 =cut
396  
397 =head1 INHERITS
398  
399 This package inherits behaviors from:
400  
401 L<Venus::Kind::Utility>
402  
403 =cut
404  
405 =head1 INTEGRATES
406  
407 This package integrates behaviors from:
408  
409 L<Venus::Role::Buildable>
410  
411 =cut
412  
413 =head1 METHODS
414  
415 This package provides the following methods:
416  
417 =cut
418  
419 =head2 accept
420  
421 accept(string $name, any @args) (Venus::Assert)
422  
423 The accept method registers a condition via L</check> based on the arguments
424 provided. The built-in types are defined as methods in L<Venus::Check>.
425  
426 I<Since C<1.40>>
427  
428 =over 4
429  
430 =item accept example 1
431  
432 # given: synopsis
433  
434 package main;
435  
436 $assert = $assert->accept('float');
437  
438 # bless(..., "Venus::Assert")
439  
440 # $assert->valid;
441  
442 # false
443  
444 # $assert->valid(1.01);
445  
446 # true
447  
448 =back
449  
450 =over 4
451  
452 =item accept example 2
453  
454 # given: synopsis
455  
456 package main;
457  
458 $assert = $assert->accept('number');
459  
460 # bless(..., "Venus::Assert")
461  
462 # $assert->valid(1.01);
463  
464 # false
465  
466 # $assert->valid(1_01);
467  
468 # true
469  
470 =back
471  
472 =over 4
473  
474 =item accept example 3
475  
476 # given: synopsis
477  
478 package Example1;
479  
480 sub new {
481 bless {};
482 }
483  
484 package Example2;
485  
486 sub new {
487 bless {};
488 }
489  
490 package main;
491  
492 $assert = $assert->accept('object');
493  
494 # bless(..., "Venus::Assert")
495  
496 # $assert->valid;
497  
498 # false
499  
500 # $assert->valid(qr//);
501  
502 # false
503  
504 # $assert->valid(Example1->new);
505  
506 # true
507  
508 # $assert->valid(Example2->new);
509  
510 # true
511  
512 =back
513  
514 =over 4
515  
516 =item accept example 4
517  
518 # given: synopsis
519  
520 package Example1;
521  
522 sub new {
523 bless {};
524 }
525  
526 package Example2;
527  
528 sub new {
529 bless {};
530 }
531  
532 package main;
533  
534 $assert = $assert->accept('Example1');
535  
536 # bless(..., "Venus::Assert")
537  
538 # $assert->valid;
539  
540 # false
541  
542 # $assert->valid(qr//);
543  
544 # false
545  
546 # $assert->valid(Example1->new);
547  
548 # true
549  
550 # $assert->valid(Example2->new);
551  
552 # false
553  
554 =back
555  
556 =cut
557  
558 =head2 check
559  
560 check(Venus::Check $data) (Venus::Check)
561  
562 The check method gets or sets the L<Venus::Check> object used for performing
563 runtime data type validation.
564  
565 I<Since C<3.55>>
566  
567 =over 4
568  
569 =item check example 1
570  
571 # given: synopsis
572  
573 package main;
574  
575 my $check = $assert->check(Venus::Check->new);
576  
577 # bless(..., 'Venus::Check')
578  
579 =back
580  
581 =over 4
582  
583 =item check example 2
584  
585 # given: synopsis
586  
587 package main;
588  
589 $assert->check(Venus::Check->new);
590  
591 my $check = $assert->check;
592  
593 # bless(..., 'Venus::Check')
594  
595 =back
596  
597 =cut
598  
599 =head2 clear
600  
601 clear() (Venus::Assert)
602  
603 The clear method resets the L</check>, L</constraint>, and L</coercion>
604 attributes and returns the invocant.
605  
606 I<Since C<1.40>>
607  
608 =over 4
609  
610 =item clear example 1
611  
612 # given: synopsis
613  
614 package main;
615  
616 $assert->accept('string');
617  
618 $assert = $assert->clear;
619  
620 # bless(..., "Venus::Assert")
621  
622 =back
623  
624 =cut
625  
626 =head2 coerce
627  
628 coerce(any $data) (any)
629  
630 The coerce method dispatches to the L</coercion> object and returns the result
631 of the L<Venus::Coercion/result> operation.
632  
633 I<Since C<3.55>>
634  
635 =over 4
636  
637 =item coerce example 1
638  
639 # given: synopsis
640  
641 package main;
642  
643 $assert->accept('float');
644  
645 $assert->format(sub{sprintf('%.2f', $_)});
646  
647 my $coerce = $assert->coerce(123.456);
648  
649 # 123.46
650  
651 =back
652  
653 =over 4
654  
655 =item coerce example 2
656  
657 # given: synopsis
658  
659 package main;
660  
661 $assert->accept('string');
662  
663 $assert->format(sub{ucfirst lc $_});
664  
665 my $coerce = $assert->coerce('heLLo');
666  
667 # "Hello"
668  
669 =back
670  
671 =cut
672  
673 =head2 coercion
674  
675 coercion(Venus::Coercion $data) (Venus::Coercion)
676  
677 The coercion method gets or sets the L<Venus::Coercion> object used for
678 performing runtime data type coercions.
679  
680 I<Since C<3.55>>
681  
682 =over 4
683  
684 =item coercion example 1
685  
686 # given: synopsis
687  
688 package main;
689  
690 my $coercion = $assert->coercion(Venus::Coercion->new);
691  
692 # bless(..., 'Venus::Coercion')
693  
694 =back
695  
696 =over 4
697  
698 =item coercion example 2
699  
700 # given: synopsis
701  
702 package main;
703  
704 $assert->coercion(Venus::Coercion->new);
705  
706 my $coercion = $assert->coercion;
707  
708 # bless(..., 'Venus::Coercion')
709  
710 =back
711  
712 =cut
713  
714 =head2 conditions
715  
716 conditions() (Venus::Assert)
717  
718 The conditions method is an object construction hook that allows subclasses to
719 configure the object on construction setting up constraints and coercions and
720 returning the invocant.
721  
722 I<Since C<1.40>>
723  
724 =over 4
725  
726 =item conditions example 1
727  
728 # given: synopsis
729  
730 package main;
731  
732 $assert = $assert->conditions;
733  
734 # bless(..., 'Venus::Assert')
735  
736 =back
737  
738 =over 4
739  
740 =item conditions example 2
741  
742 package Example::Type::PositveNumber;
743  
744 use base 'Venus::Assert';
745  
746 sub conditions {
747 my ($self) = @_;
748  
749 $self->accept('number', sub {
750 $_ >= 0
751 });
752  
753 return $self;
754 }
755  
756 package main;
757  
758 my $assert = Example::Type::PositveNumber->new;
759  
760 # $assert->valid(0);
761  
762 # true
763  
764 # $assert->valid(1);
765  
766 # true
767  
768 # $assert->valid(-1);
769  
770 # false
771  
772 =back
773  
774 =cut
775  
776 =head2 constraint
777  
778 constraint(Venus::Constraint $data) (Venus::Constraint)
779  
780 The constraint method gets or sets the L<Venus::Constraint> object used for
781 performing runtime data type constraints.
782  
783 I<Since C<3.55>>
784  
785 =over 4
786  
787 =item constraint example 1
788  
789 # given: synopsis
790  
791 package main;
792  
793 my $constraint = $assert->constraint(Venus::Constraint->new);
794  
795 # bless(..., 'Venus::Constraint')
796  
797 =back
798  
799 =over 4
800  
801 =item constraint example 2
802  
803 # given: synopsis
804  
805 package main;
806  
807 $assert->constraint(Venus::Constraint->new);
808  
809 my $constraint = $assert->constraint;
810  
811 # bless(..., 'Venus::Constraint')
812  
813 =back
814  
815 =cut
816  
817 =head2 ensure
818  
819 ensure(coderef $code) (Venus::Assert)
820  
821 The ensure method registers a custom (not built-in) constraint condition and
822 returns the invocant.
823  
824 I<Since C<3.55>>
825  
826 =over 4
827  
828 =item ensure example 1
829  
830 # given: synopsis
831  
832 package main;
833  
834 $assert->accept('number');
835  
836 my $ensure = $assert->ensure(sub {
837 $_ >= 0
838 });
839  
840 # bless(.., "Venus::Assert")
841  
842 =back
843  
844 =cut
845  
846 =head2 expression
847  
848 expression(string $expr) (Venus::Assert)
849  
850 The expression method parses a string representation of an type assertion,
851 registers the subexpressions using the L</accept> method, and returns the
852 invocant.
853  
854 I<Since C<1.71>>
855  
856 =over 4
857  
858 =item expression example 1
859  
860 # given: synopsis
861  
862 package main;
863  
864 $assert = $assert->expression('string');
865  
866 # bless(..., 'Venus::Assert')
867  
868 # $assert->valid('hello');
869  
870 # true
871  
872 # $assert->valid(['goodbye']);
873  
874 # false
875  
876 =back
877  
878 =over 4
879  
880 =item expression example 2
881  
882 # given: synopsis
883  
884 package main;
885  
886 $assert = $assert->expression('string | coderef');
887  
888 # bless(..., 'Venus::Assert')
889  
890 # $assert->valid('hello');
891  
892 # true
893  
894 # $assert->valid(sub{'hello'});
895  
896 # true
897  
898 # $assert->valid(['goodbye']);
899  
900 # false
901  
902 =back
903  
904 =over 4
905  
906 =item expression example 3
907  
908 # given: synopsis
909  
910 package main;
911  
912 $assert = $assert->expression('string | coderef | Venus::Assert');
913  
914 # bless(..., 'Venus::Assert')
915  
916 # $assert->valid('hello');
917  
918 # true
919  
920 # $assert->valid(sub{'hello'});
921  
922 # true
923  
924 # $assert->valid($assert);
925  
926 # true
927  
928 # $assert->valid(['goodbye']);
929  
930 # false
931  
932 =back
933  
934 =over 4
935  
936 =item expression example 4
937  
938 # given: synopsis
939  
940 package main;
941  
942 $assert = $assert->expression('Venus::Assert | within[arrayref, Venus::Assert]');
943  
944 # bless(..., 'Venus::Assert')
945  
946 # $assert->valid('hello');
947  
948 # false
949  
950 # $assert->valid(sub{'hello'});
951  
952 # false
953  
954 # $assert->valid($assert);
955  
956 # true
957  
958 # $assert->valid(['goodbye']);
959  
960 # false
961  
962 # $assert->valid([$assert]);
963  
964 # true
965  
966 =back
967  
968 =over 4
969  
970 =item expression example 5
971  
972 # given: synopsis
973  
974 package main;
975  
976 $assert = $assert->expression('
977 string
978 | within[
979 arrayref, within[
980 hashref, string
981 ]
982 ]
983 ');
984  
985 # bless(..., 'Venus::Assert')
986  
987 # $assert->valid('hello');
988  
989 # true
990  
991 # $assert->valid(sub{'hello'});
992  
993 # false
994  
995 # $assert->valid($assert);
996  
997 # false
998  
999 # $assert->valid([]);
1000  
1001 # false
1002  
1003 # $assert->valid([{'test' => ['okay']}]);
1004  
1005 # false
1006  
1007 # $assert->valid([{'test' => 'okay'}]);
1008  
1009 # true
1010  
1011 =back
1012  
1013 =cut
1014  
1015 =head2 format
1016  
1017 format(coderef $code) (Venus::Assert)
1018  
1019 The format method registers a custom (not built-in) coercion condition and
1020 returns the invocant.
1021  
1022 I<Since C<3.55>>
1023  
1024 =over 4
1025  
1026 =item format example 1
1027  
1028 # given: synopsis
1029  
1030 package main;
1031  
1032 $assert->accept('number');
1033  
1034 my $format = $assert->format(sub {
1035 sprintf '%.2f', $_
1036 });
1037  
1038 # bless(.., "Venus::Assert")
1039  
1040 =back
1041  
1042 =cut
1043  
1044 =head2 new
1045  
1046 new(any @args) (Venus::Assert)
1047  
1048 The new method constructs an instance of the package.
1049  
1050 I<Since C<4.15>>
1051  
1052 =over 4
1053  
1054 =item new example 1
1055  
1056 package main;
1057  
1058 use Venus::Assert;
1059  
1060 my $new = Venus::Assert->new;
1061  
1062 # bless(..., "Venus::Assert")
1063  
1064 =back
1065  
1066 =over 4
1067  
1068 =item new example 2
1069  
1070 package main;
1071  
1072 use Venus::Assert;
1073  
1074 my $new = Venus::Assert->new('Float');
1075  
1076 # bless(..., "Venus::Assert")
1077  
1078 =back
1079  
1080 =over 4
1081  
1082 =item new example 3
1083  
1084 package main;
1085  
1086 use Venus::Assert;
1087  
1088 my $new = Venus::Assert->new(name => 'Float');
1089  
1090 # bless(..., "Venus::Assert")
1091  
1092 =back
1093  
1094 =cut
1095  
1096 =head2 parse
1097  
1098 parse(string $expr) (any)
1099  
1100 The parse method accepts a string representation of a type assertion and
1101 returns a data structure representing one or more method calls to be used for
1102 validating the assertion signature.
1103  
1104 I<Since C<2.01>>
1105  
1106 =over 4
1107  
1108 =item parse example 1
1109  
1110 # given: synopsis
1111  
1112 package main;
1113  
1114 my $parsed = $assert->parse('');
1115  
1116 # ['']
1117  
1118 =back
1119  
1120 =over 4
1121  
1122 =item parse example 2
1123  
1124 # given: synopsis
1125  
1126 package main;
1127  
1128 my $parsed = $assert->parse('any');
1129  
1130 # ['any']
1131  
1132 =back
1133  
1134 =over 4
1135  
1136 =item parse example 3
1137  
1138 # given: synopsis
1139  
1140 package main;
1141  
1142 my $parsed = $assert->parse('string | number');
1143  
1144 # ['either', 'string', 'number']
1145  
1146 =back
1147  
1148 =over 4
1149  
1150 =item parse example 4
1151  
1152 # given: synopsis
1153  
1154 package main;
1155  
1156 my $parsed = $assert->parse('enum[up,down,left,right]');
1157  
1158 # ['enum', 'up', 'down', 'left', 'right']
1159  
1160 =back
1161  
1162 =over 4
1163  
1164 =item parse example 5
1165  
1166 # given: synopsis
1167  
1168 package main;
1169  
1170 my $parsed = $assert->parse('number | float | boolean');
1171  
1172 # ['either', 'number', 'float', 'boolean']
1173  
1174 =back
1175  
1176 =over 4
1177  
1178 =item parse example 6
1179  
1180 # given: synopsis
1181  
1182 package main;
1183  
1184 my $parsed = $assert->parse('Example');
1185  
1186 # ['Example']
1187  
1188 =back
1189  
1190 =over 4
1191  
1192 =item parse example 7
1193  
1194 # given: synopsis
1195  
1196 package main;
1197  
1198 my $parsed = $assert->parse('coderef | Venus::Code');
1199  
1200 # ['either', 'coderef', 'Venus::Code']
1201  
1202 =back
1203  
1204 =over 4
1205  
1206 =item parse example 8
1207  
1208 # given: synopsis
1209  
1210 package main;
1211  
1212 my $parsed = $assert->parse('tuple[number, arrayref, coderef]');
1213  
1214 # ['tuple', 'number', 'arrayref', 'coderef']
1215  
1216 =back
1217  
1218 =over 4
1219  
1220 =item parse example 9
1221  
1222 # given: synopsis
1223  
1224 package main;
1225  
1226 my $parsed = $assert->parse('tuple[number, within[arrayref, hashref], coderef]');
1227  
1228 # ['tuple', 'number', ['within', 'arrayref', 'hashref'], 'coderef']
1229  
1230 =back
1231  
1232 =over 4
1233  
1234 =item parse example 10
1235  
1236 # given: synopsis
1237  
1238 package main;
1239  
1240 my $parsed = $assert->parse(
1241 'tuple[number, within[arrayref, hashref] | arrayref, coderef]'
1242 );
1243  
1244 # ['tuple', 'number', ['either', ['within', 'arrayref', 'hashref'], 'arrayref'], 'coderef']
1245  
1246 =back
1247  
1248 =over 4
1249  
1250 =item parse example 11
1251  
1252 # given: synopsis
1253  
1254 package main;
1255  
1256 my $parsed = $assert->parse(
1257 'hashkeys["id", number | float, "upvotes", within[arrayref, boolean]]'
1258 );
1259  
1260 # [
1261 # 'hashkeys',
1262 # 'id',
1263 # ['either', 'number', 'float'],
1264 # 'upvotes',
1265 # ['within', 'arrayref', 'boolean']
1266 # ]
1267  
1268 =back
1269  
1270 =cut
1271  
1272 =head2 render
1273  
1274 render(string $into, string $expression) (string)
1275  
1276 The render method builds and returns a type expressions suitable for providing
1277 to L</expression> based on the data provided.
1278  
1279 I<Since C<4.15>>
1280  
1281 =over 4
1282  
1283 =item render example 1
1284  
1285 # given: synopsis
1286  
1287 package main;
1288  
1289 $assert = $assert->render;
1290  
1291 # ""
1292  
1293 =back
1294  
1295 =over 4
1296  
1297 =item render example 2
1298  
1299 # given: synopsis
1300  
1301 package main;
1302  
1303 $assert = $assert->render(undef, 'string');
1304  
1305 # "string"
1306  
1307 =back
1308  
1309 =over 4
1310  
1311 =item render example 3
1312  
1313 # given: synopsis
1314  
1315 package main;
1316  
1317 $assert = $assert->render('routines', ['say', 'say_pretty']);
1318  
1319 # 'routines[say, say_pretty]'
1320  
1321 =back
1322  
1323 =over 4
1324  
1325 =item render example 4
1326  
1327 # given: synopsis
1328  
1329 package main;
1330  
1331 $assert = $assert->render('hashkeys', {id => 'number', name => 'string'});
1332  
1333 # 'hashkeys[id, number, name, string]'
1334  
1335 =back
1336  
1337 =over 4
1338  
1339 =item render example 5
1340  
1341 # given: synopsis
1342  
1343 package main;
1344  
1345 $assert = $assert->render('hashkeys', {
1346 id => 'number',
1347 profile => {
1348 hashkeys => {
1349 level => 'string',
1350 },
1351 },
1352 });
1353  
1354 # 'hashkeys[id, number, profile, hashkeys[level, string]]'
1355  
1356 =back
1357  
1358 =cut
1359  
1360 =head2 result
1361  
1362 result(any $data) (any)
1363  
1364 The result method validates the value provided against the registered
1365 constraints and if valid returns the result of the value having any registered
1366 coercions applied. If the value is invalid an exception from L<Venus::Check>
1367 will be thrown.
1368  
1369 I<Since C<3.55>>
1370  
1371 =over 4
1372  
1373 =item result example 1
1374  
1375 # given: synopsis
1376  
1377 package main;
1378  
1379 $assert->accept('number')->format(sub{sprintf '%.2f', $_});
1380  
1381 my $result = $assert->result(1);
1382  
1383 # "1.00"
1384  
1385 =back
1386  
1387 =over 4
1388  
1389 =item result example 2
1390  
1391 # given: synopsis
1392  
1393 package main;
1394  
1395 $assert->accept('number')->format(sub{sprintf '%.2f', $_});
1396  
1397 my $result = $assert->result('hello');
1398  
1399 # Exception! (isa Venus::Check::Error) (see error_on_coded)
1400  
1401 =back
1402  
1403 =cut
1404  
1405 =head2 valid
1406  
1407 valid(any $data) (any)
1408  
1409 The valid method dispatches to the L</constraint> object and returns the result
1410 of the L<Venus::Constraint/result> operation.
1411  
1412 I<Since C<3.55>>
1413  
1414 =over 4
1415  
1416 =item valid example 1
1417  
1418 # given: synopsis
1419  
1420 package main;
1421  
1422 $assert->accept('float');
1423  
1424 $assert->ensure(sub{$_ >= 1});
1425  
1426 my $valid = $assert->valid('1.00');
1427  
1428 # true
1429  
1430 =back
1431  
1432 =over 4
1433  
1434 =item valid example 2
1435  
1436 # given: synopsis
1437  
1438 package main;
1439  
1440 $assert->accept('float');
1441  
1442 $assert->ensure(sub{$_ >= 1});
1443  
1444 my $valid = $assert->valid('0.99');
1445  
1446 # false
1447  
1448 =back
1449  
1450 =cut
1451  
1452 =head2 validate
1453  
1454 validate(any $data) (any)
1455  
1456 The validate method validates the value provided against the registered
1457 constraints and if valid returns the value. If the value is invalid an
1458 exception from L<Venus::Check> will be thrown.
1459  
1460 I<Since C<3.55>>
1461  
1462 =over 4
1463  
1464 =item validate example 1
1465  
1466 # given: synopsis
1467  
1468 package main;
1469  
1470 $assert->accept('number');
1471  
1472 my $validate = $assert->validate(1);
1473  
1474 # 1
1475  
1476 =back
1477  
1478 =over 4
1479  
1480 =item validate example 2
1481  
1482 # given: synopsis
1483  
1484 package main;
1485  
1486 $assert->accept('number');
1487  
1488 my $validate = $assert->validate('hello');
1489  
1490 # Exception! (isa Venus::Check::Error) (see error_on_coded)
1491  
1492 =back
1493  
1494 =cut
1495  
1496 =head2 validator
1497  
1498 validator(any @args) (coderef)
1499  
1500 The validator method returns a coderef which calls the L</validate> method with
1501 the invocant when called.
1502  
1503 I<Since C<3.55>>
1504  
1505 =over 4
1506  
1507 =item validator example 1
1508  
1509 # given: synopsis
1510  
1511 package main;
1512  
1513 $assert->accept('string');
1514  
1515 my $validator = $assert->validator;
1516  
1517 # sub{...}
1518  
1519 # my $result = $validator->();
1520  
1521 # Exception! (isa Venus::Check::Error) (see error_on_coded)
1522  
1523 =back
1524  
1525 =over 4
1526  
1527 =item validator example 2
1528  
1529 # given: synopsis
1530  
1531 package main;
1532  
1533 $assert->accept('string');
1534  
1535 my $validator = $assert->validator;
1536  
1537 # sub{...}
1538  
1539 # my $result = $validator->('hello');
1540  
1541 # "hello"
1542  
1543 =back
1544  
1545 =cut
1546  
1547 =head1 AUTHORS
1548  
1549 Awncorp, C<awncorp@cpan.org>
1550  
1551 =cut
1552  
1553 =head1 LICENSE
1554  
1555 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
1556  
1557 This program is free software, you can redistribute it and/or modify it under
1558 the terms of the Apache license version 2.0.
1559  
1560 =cut
« blib/lib/Venus/Factory.pm ↑ Summary blib/lib/Venus/Role.pm »