blib/lib/Venus/Role/Throwable.pm

filter: Statementstmt 100% 46 / 46 Branchbran 65.7% 25 / 38 Conditioncond 75.0% 9 / 12 MC/DCmcdc 28.5% 2 / 7 Subroutinesub 100% 8 / 8 Podpod 75.0% 3 / 4 totaltotal 80.8% 93 / 115 CC 26 SCAR 21.9
CC
26
Cov
83%
throw
11.8
die
9.6
error
9.1
CRAP 8.9
« blib/lib/Venus/Type.pm ↑ Summary blib/lib/Venus/Role/Comparable.pm »
1 package Venus::Role::Throwable;
2  
3 119 ▶use 5.018;
Subroutine BEGIN: called CC=1 SCAR=0.0
4  
5 119 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
6 119 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7  
8 # IMPORTS
9  
10 119 ▶use Venus::Role 'with';
Subroutine BEGIN: called CC=1 SCAR=0.0
11  
12 # METHODS
13  
14 1 ▶sub die {
Subroutine die: called CC=8 SCAR=22.6
Pod documented
15 1 my ($self, $data) = @_;
16  
17 1 ▶ $data ||= {};
Condition50%1/2
$data ||= {}
l!l
10
MC/DC0%0/1
$data ||= {}
$data
Truth table50%1/2
A
A= $data
Aresult
11
00
18  
19 1 ▶ if (!ref $data) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $data) 1 0 1
20 1 ▶ $data = $self->can($data) ? $self->$data : {package => $data};
Branch: 1 branch
BranchTrueFalseTotal
$self->can($data) ? : 1 0 1
21 }
22  
23 1 ▶ $data = {} if ref $data ne 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
if ref $data ne "HASH" 0 1 1
24  
25 1 ▶ my $args = $data->{throw} ? delete $data->{throw} : $data->{args} ? delete $data->{args} : undef;
Branch: 2 branches
BranchTrueFalseTotal
$data->{'throw'} ? : 0 1 1
$data->{'args'} ? : 0 1 1
26  
27 1 ▶ $data = $self->$args($data) if $args;
Branch: 1 branch
BranchTrueFalseTotal
if $args 0 1 1
28  
29 1 require Venus::Throw;
30  
31 1 my ($throw) = @_ = (
32 Venus::Throw->new(
33 context => (caller(1))[3],
34 package => join('::', map ucfirst, ref($self), 'error'),
35 ),
36 $data,
37 );
38  
39 1 goto $throw->can('die');
40 }
41  
42 269 ▶sub error {
Subroutine error: called CC=9 SCAR=22.1
Pod documented
43 269 my ($self, $data) = @_;
44  
45 269 ▶ $data ||= {};
Condition100%2/2
$data ||= {}
l!l
6263
MC/DC100%1/1
$data ||= {}
$data
Truth table100%2/2
A
A= $data
Aresult
11
00
46  
47 269 ▶ if (!ref $data) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $data) 2 267 269
48 2 ▶ $data = $self->can($data) ? $self->$data : {package => $data};
Branch: 1 branch
BranchTrueFalseTotal
$self->can($data) ? : 1 1 2
49 }
50  
51 269 ▶ $data = {} if ref $data ne 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
if ref $data ne "HASH" 0 269 269
52  
53 269 ▶ my $args = $data->{throw} ? delete $data->{throw} : $data->{args} ? delete $data->{args} : undef;
Branch: 2 branches
BranchTrueFalseTotal
$data->{'throw'} ? : 3 266 269
$data->{'args'} ? : 0 266 266
54  
55 269 ▶ $data = $self->$args($data) if $args;
Branch: 1 branch
BranchTrueFalseTotal
if $args 3 266 269
56  
57 269 require Venus::Throw;
58  
59 my ($throw) = @_ = (
60 Venus::Throw->new(
61 context => (caller(1))[3],
62 269 ▶ package => $data->{package} || join('::', map ucfirst, ref($self), 'error'),
Condition66%2/3
$data->{'package'} || join('::', map(ucfirst($_), ref $self, 'error'))
l!l&&r!l&&!r
12680
MC/DC0%0/2
$data->{'package'} || join('::', map(ucfirst($_), ref $self, 'error'))
$data->{'package'} join('::', map(ucfirst($_), ref $self, 'error'))
Truth table66%2/3
A || B
A= $data->{'package'}B= join('::', map(ucfirst($_), ref $self, 'error'))
ABresult
1X1
011
000
63 ),
64 $data,
65 );
66  
67 269 goto $throw->can('error');
68 }
69  
70 8 ▶sub throw {
Subroutine throw: called CC=11 SCAR=24.7
Pod documented
71 8 my ($self, $data) = @_;
72  
73 8 ▶ $data ||= {};
Condition100%2/2
$data ||= {}
l!l
35
MC/DC100%1/1
$data ||= {}
$data
Truth table100%2/2
A
A= $data
Aresult
11
00
74  
75 8 ▶ if (!ref $data) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $data) 2 6 8
76 2 ▶ $data = $self->can($data) ? $self->$data : {package => $data};
Branch: 1 branch
BranchTrueFalseTotal
$self->can($data) ? : 1 1 2
77 }
78  
79 8 ▶ $data = {} if ref $data ne 'HASH';
Branch: 1 branch
BranchTrueFalseTotal
if ref $data ne "HASH" 0 8 8
80  
81 8 ▶ my $args = $data->{throw} ? delete $data->{throw} : $data->{args} ? delete $data->{args} : undef;
Branch: 2 branches
BranchTrueFalseTotal
$data->{'throw'} ? : 0 8 8
$data->{'args'} ? : 0 8 8
82  
83 8 ▶ $data = $self->$args($data) if $args;
Branch: 1 branch
BranchTrueFalseTotal
if $args 0 8 8
84  
85 8 require Venus::Throw;
86  
87 my $throw = Venus::Throw->new(
88 context => (caller(1))[3],
89 8 ▶ package => $data->{package} || join('::', map ucfirst, ref($self), 'error'),
Condition66%2/3
$data->{'package'} || join('::', map(ucfirst($_), ref $self, 'error'))
l!l&&r!l&&!r
170
MC/DC0%0/2
$data->{'package'} || join('::', map(ucfirst($_), ref $self, 'error'))
$data->{'package'} join('::', map(ucfirst($_), ref $self, 'error'))
Truth table66%2/3
A || B
A= $data->{'package'}B= join('::', map(ucfirst($_), ref $self, 'error'))
ABresult
1X1
011
000
90 );
91  
92 8 for my $key (keys %{$data}) {
93 7 ▶ $throw->$key($data->{$key}) if $throw->can($key);
Branch: 1 branch
BranchTrueFalseTotal
if $throw->can($key) 7 0 7
94 }
95  
96 8 return $throw;
97 }
98  
99 # EXPORTS
100  
101 131 ▶sub EXPORT {
Subroutine EXPORT: called CC=1 SCAR=0.0
Pod undocumented
102 131 ['die', 'error', 'throw']
103 }
104  
105 119 1;
106  
107  
108  
109 =head1 NAME
110  
111 Venus::Role::Throwable - Throwable Role
112  
113 =cut
114  
115 =head1 ABSTRACT
116  
117 Throwable Role for Perl 5
118  
119 =cut
120  
121 =head1 SYNOPSIS
122  
123 package Example;
124  
125 use Venus::Class;
126  
127 with 'Venus::Role::Throwable';
128  
129 package main;
130  
131 my $example = Example->new;
132  
133 # $example->throw;
134  
135 =cut
136  
137 =head1 DESCRIPTION
138  
139 This package modifies the consuming package and provides a mechanism for
140 throwing context-aware errors (exceptions).
141  
142 =cut
143  
144 =head1 METHODS
145  
146 This package provides the following methods:
147  
148 =cut
149  
150 =head2 die
151  
152 die(maybe[string | hashref] $data) (any)
153  
154 The die method builds a L<Venus::Throw> object using L</throw> and
155 automatically throws the exception.
156  
157 I<Since C<4.15>>
158  
159 =over 4
160  
161 =item die example 1
162  
163 # given: synopsis
164  
165 package Example;
166  
167 # ...
168  
169 sub error_on_example {
170 my ($self) = @_;
171  
172 return {
173 name => 'on.example',
174 capture => [$example],
175 stash => {
176 time => time,
177 },
178 raise => true,
179 };
180 }
181  
182 package main;
183  
184 my $die = $example->die('error_on_example');
185  
186 # Exception! isa Example::Error
187  
188 =back
189  
190 =cut
191  
192 =head2 error
193  
194 error(maybe[string | hashref] $data) (any)
195  
196 The error method dispatches to the L</throw> method, excepts a hashref of
197 options to be provided to the L</throw> method, and returns the result unless
198 an exception is raised automatically. If the C<throw> option is provided it is
199 excepted to be the name of a method used as a callback to provide arguments to
200 the thrower.
201  
202 I<Since C<3.40>>
203  
204 =over 4
205  
206 =item error example 1
207  
208 package main;
209  
210 my $example = Example->new;
211  
212 my $error = $example->error;
213  
214 # bless(..., "Example::Error")
215  
216 # $error->throw;
217  
218 # Exception! isa "Example::Error"
219  
220 =back
221  
222 =over 4
223  
224 =item error example 2
225  
226 package main;
227  
228 my $example = Example->new;
229  
230 my $error = $example->error('Example::Error::Unknown');
231  
232 # bless(..., "Example::Error::Unknown")
233  
234 # $error->throw;
235  
236 # Exception! isa "Example::Error::Unknown"
237  
238 =back
239  
240 =over 4
241  
242 =item error example 3
243  
244 package main;
245  
246 my $example = Example->new;
247  
248 my $error = $example->error({
249 name => 'on.example',
250 capture => [$example],
251 stash => {
252 time => time,
253 },
254 });
255  
256 # bless(..., "Example::Error")
257  
258 # $error->throw;
259  
260 # Exception! isa "Example::Error"
261  
262 =back
263  
264 =over 4
265  
266 =item error example 4
267  
268 # given: synopsis
269  
270 package Example;
271  
272 # ...
273  
274 sub error_on_example {
275 my ($self) = @_;
276  
277 return {
278 name => 'on.example',
279 capture => [$example],
280 stash => {
281 time => time,
282 },
283 };
284 }
285  
286 package main;
287  
288 my $error = $example->error('error_on_example');
289  
290 # bless(..., "Example::Error")
291  
292 # $error->throw;
293  
294 # Exception! isa "Example::Error"
295  
296 =back
297  
298 =over 4
299  
300 =item error example 5
301  
302 # given: synopsis
303  
304 package Example;
305  
306 # ...
307  
308 sub error_on_example {
309 my ($self) = @_;
310  
311 return {
312 name => 'on.example',
313 capture => [$example],
314 stash => {
315 time => time,
316 },
317 raise => false,
318 };
319 }
320  
321 package main;
322  
323 my $error = $example->error({throw => 'error_on_example'});
324  
325 # bless(..., "Example::Error")
326  
327 # $error->throw;
328  
329 # Exception! isa "Example::Error"
330  
331 =back
332  
333 =over 4
334  
335 =item error example 6
336  
337 # given: synopsis
338  
339 package Example;
340  
341 # ...
342  
343 sub error_on_example {
344 my ($self) = @_;
345  
346 return {
347 name => 'on.example',
348 capture => [$example],
349 stash => {
350 time => time,
351 },
352 raise => true,
353 };
354 }
355  
356 package main;
357  
358 my $error = $example->error({throw => 'error_on_example'});
359  
360 # Exception! isa Example::Error
361  
362 =back
363  
364 =cut
365  
366 =head2 throw
367  
368 throw(maybe[string | hashref] $data, any @args) (any)
369  
370 The throw method builds a L<Venus::Throw> object, which can raise errors
371 (exceptions). If passed a string representing a package name, the throw object
372 will be configured to throw an exception using that package name. If passed a
373 string representing a method name, the throw object will call that method
374 expecting a hashref to be returned which will be provided to L<Venus::Throw> as
375 arguments to configure the thrower. If passed a hashref, the keys and values
376 are expected to be method names and arguments which will be called to configure
377 the L<Venus::Throw> object returned. If passed additional arguments, assuming
378 they are preceeded by a string representing a method name, the additional
379 arguments will be supplied to the method when called. If the C<raise> argument
380 is provided (or returned from the callback), the thrower will automatically
381 throw the exception.
382  
383 I<Since C<0.01>>
384  
385 =over 4
386  
387 =item throw example 1
388  
389 package main;
390  
391 my $example = Example->new;
392  
393 my $throw = $example->throw;
394  
395 # bless({"package" => "Example::Error", ...,}, "Venus::Throw")
396  
397 # $throw->die;
398  
399 # Exception! isa Example::Error
400  
401 =back
402  
403 =over 4
404  
405 =item throw example 2
406  
407 package main;
408  
409 my $example = Example->new;
410  
411 my $throw = $example->throw('Example::Error::Unknown');
412  
413 # bless({"package" => "Example::Error::Unknown", ...,}, "Venus::Throw")
414  
415 # $throw->die;
416  
417 # Exception! isa Example::Error::Unknown
418  
419 =back
420  
421 =over 4
422  
423 =item throw example 3
424  
425 package main;
426  
427 my $example = Example->new;
428  
429 my $throw = $example->throw({
430 name => 'on.example',
431 capture => [$example],
432 stash => {
433 time => time,
434 },
435 });
436  
437 # bless({"package" => "Example::Error", ...,}, "Venus::Throw")
438  
439 # $throw->die;
440  
441 # Exception! isa Example::Error
442  
443 =back
444  
445 =over 4
446  
447 =item throw example 4
448  
449 # given: synopsis
450  
451 package Example;
452  
453 # ...
454  
455 sub error_on_example {
456 my ($self) = @_;
457  
458 return {
459 name => 'on.example',
460 capture => [$example],
461 stash => {
462 time => time,
463 },
464 };
465 }
466  
467 package main;
468  
469 my $throw = $example->throw('error_on_example');
470  
471 # bless({"package" => "Example::Error", ...,}, "Venus::Throw")
472  
473 # $throw->die;
474  
475 # Exception! isa Example::Error
476  
477 =back
478  
479 =cut
480  
481 =head1 AUTHORS
482  
483 Awncorp, C<awncorp@cpan.org>
484  
485 =cut
486  
487 =head1 LICENSE
488  
489 Copyright (C) 2022, Awncorp, C<awncorp@cpan.org>.
490  
491 This program is free software, you can redistribute it and/or modify it under
492 the terms of the Apache license version 2.0.
493  
494 =cut
« blib/lib/Venus/Type.pm ↑ Summary blib/lib/Venus/Role/Comparable.pm »