File Coverage

blib/lib/Venus/Role/Assertable.pm
Criterion Covered Total %
statement 24 25 96.0
branch 3 4 75.0
condition 3 6 50.0
subroutine 10 10 100.0
pod 4 6 66.6
total 44 51 86.2


line stmt bran cond sub pod time code
1             package Venus::Role::Assertable;
2              
3 87     87   1534 use 5.018;
  87         322  
4              
5 87     87   479 use strict;
  87         182  
  87         1705  
6 87     87   401 use warnings;
  87         211  
  87         2813  
7              
8 87     87   481 use Venus::Role 'fault';
  87         197  
  87         582  
9              
10             # AUDIT
11              
12             sub AUDIT {
13 100     100 0 278 my ($self, $from) = @_;
14              
15 100   33     623 my $name = ref $self || $self;
16              
17 100 50       858 if (!$from->can('assertion')) {
18 0         0 fault "${from} requires 'assertion' to consume ${name}";
19             }
20              
21 100         305 return $self;
22             }
23              
24             # METHODS
25              
26             sub assert {
27 53     53 1 173 my ($self, $data) = @_;
28              
29 53         273 return $self->assertion->validate($data);
30             }
31              
32             sub check {
33 3     3 1 11 my ($self, $data) = @_;
34              
35 3         51 return $self->assertion->check($data);
36             }
37              
38             sub coerce {
39 50     50 1 131 my ($self, $data) = @_;
40              
41 50         202 return $self->assertion->coerce($data);
42             }
43              
44             sub make {
45 52     52 1 137 my ($self, $data) = @_;
46              
47 52 100 66     537 return UNIVERSAL::isa($data, ref $self || $self)
48             ? $data
49             : $self->new($self->assert($self->coerce($data)));
50             }
51              
52             # EXPORTS
53              
54             sub EXPORT {
55 100     100 0 421 ['assert', 'check', 'coerce', 'make']
56             }
57              
58             1;
59              
60              
61              
62             =head1 NAME
63              
64             Venus::Role::Assertable - Assertable Role
65              
66             =cut
67              
68             =head1 ABSTRACT
69              
70             Assertable Role for Perl 5
71              
72             =cut
73              
74             =head1 SYNOPSIS
75              
76             package Example;
77              
78             use Venus::Class;
79             use Venus::Assert;
80              
81             with 'Venus::Role::Assertable';
82              
83             sub assertion {
84             Venus::Assert->new('Example')->constraint('object', sub{
85             $_->value->isa('Example')
86             })
87             }
88              
89             package main;
90              
91             my $example = Example->new;
92              
93             # $example->check;
94              
95             =cut
96              
97             =head1 DESCRIPTION
98              
99             This package modifies the consuming package and requires methods for making the
100             object assertable.
101              
102             =cut
103              
104             =head1 METHODS
105              
106             This package provides the following methods:
107              
108             =cut
109              
110             =head2 assert
111              
112             assert(Any $data) (Any)
113              
114             The assert method returns the data provided if it passes the registered type
115             constraints, or throws an exception.
116              
117             I>
118              
119             =over 4
120              
121             =item assert example 1
122              
123             # given: synopsis
124              
125             package main;
126              
127             my $assert = $example->assert;
128              
129             # Exception! (isa Venus::Assert::Error)
130              
131             =back
132              
133             =over 4
134              
135             =item assert example 2
136              
137             # given: synopsis
138              
139             package main;
140              
141             my $assert = $example->assert({});
142              
143             # Exception! (isa Venus::Assert::Error)
144              
145             =back
146              
147             =over 4
148              
149             =item assert example 3
150              
151             # given: synopsis
152              
153             package main;
154              
155             my $assert = $example->assert($example);
156              
157             # bless({}, "Example")
158              
159             =back
160              
161             =cut
162              
163             =head2 assertion
164              
165             assertion() (Assert)
166              
167             The assertion method receives no arguments and should returns a
168             L object.
169              
170             I>
171              
172             =over 4
173              
174             =item assertion example 1
175              
176             package main;
177              
178             my $example = Example->new;
179              
180             my $assertion = $example->assertion;
181              
182             # bless({name => "Example"}, "Venus::Assert")
183              
184             =back
185              
186             =cut
187              
188             =head2 check
189              
190             check(Any $data) (Bool)
191              
192             The check method returns true if the data provided passes the registered type
193             constraints, or returns false.
194              
195             I>
196              
197             =over 4
198              
199             =item check example 1
200              
201             # given: synopsis
202              
203             package main;
204              
205             my $check = $example->check;
206              
207             # 0
208              
209             =back
210              
211             =over 4
212              
213             =item check example 2
214              
215             # given: synopsis
216              
217             package main;
218              
219             my $check = $example->check({});
220              
221             # 0
222              
223             =back
224              
225             =over 4
226              
227             =item check example 3
228              
229             # given: synopsis
230              
231             package main;
232              
233             my $check = $example->check($example);
234              
235             # 1
236              
237             =back
238              
239             =cut
240              
241             =head2 coerce
242              
243             coerce(Any $data) (Any)
244              
245             The coerce method returns a coerced value if the data provided matches any of
246             the registered type coercions, or returns the data provided.
247              
248             I>
249              
250             =over 4
251              
252             =item coerce example 1
253              
254             # given: synopsis
255              
256             package main;
257              
258             my $assertion = $example->assertion;
259              
260             $assertion->coercion('string', sub{ucfirst(lc($_->value))});
261              
262             my $coerce = $assertion->coerce;
263              
264             # undef
265              
266             =back
267              
268             =over 4
269              
270             =item coerce example 2
271              
272             # given: synopsis
273              
274             package main;
275              
276             my $assertion = $example->assertion;
277              
278             $assertion->coercion('string', sub{ucfirst(lc($_->value))});
279              
280             my $coerce = $assertion->coerce({});
281              
282             # {}
283              
284             =back
285              
286             =over 4
287              
288             =item coerce example 3
289              
290             # given: synopsis
291              
292             package main;
293              
294             my $assertion = $example->assertion;
295              
296             $assertion->coercion('string', sub{ucfirst(lc($_->value))});
297              
298             my $coerce = $assertion->coerce('hello');
299              
300             # "Hello"
301              
302             =back
303              
304             =cut
305              
306             =head2 make
307              
308             make(Any $data) (Object)
309              
310             The make method returns an instance of the invocant, if the data provided
311             passes the registered type constraints, allowing for any coercion, or throws an
312             exception. If the data provided is itself an instance of the invocant it will
313             be returned unaltered.
314              
315             I>
316              
317             =over 4
318              
319             =item make example 1
320              
321             # given: synopsis
322              
323             package main;
324              
325             my $make = $example->make;
326              
327             # Exception! (isa Venus::Assert::Error)
328              
329             =back
330              
331             =over 4
332              
333             =item make example 2
334              
335             # given: synopsis
336              
337             package main;
338              
339             my $make = $example->make($example);
340              
341             # bless({}, "Example")
342              
343             =back
344              
345             =over 4
346              
347             =item make example 3
348              
349             # given: synopsis
350              
351             package main;
352              
353             my $make = $example->make({});
354              
355             # Exception! (isa Venus::Assert::Error)
356              
357             =back
358              
359             =cut
360              
361             =head1 AUTHORS
362              
363             Awncorp, C
364              
365             =cut
366              
367             =head1 LICENSE
368              
369             Copyright (C) 2000, Al Newkirk.
370              
371             This program is free software, you can redistribute it and/or modify it under
372             the terms of the Apache license version 2.0.
373              
374             =cut