lib/FP/Failure.pm

filter: Statementstmt 98.0% 154 / 157 Branchbran 77.7% 28 / 36 Conditioncond 69.2% 9 / 13 MC/DCmcdc 50.0% 4 / 8 Subroutinesub 97.3% 37 / 38 Podpod 0.0% 0 / 5 totaltotal 90.2% 232 / 257 CC 24 SCAR 11.6
CC
24
Cov
93%
message
8.0
fails
6.2
failure
6.1
CRAP 3.2
« lib/Chj/tempdir.pm ↑ Summary lib/FP/Array_sort.pm »
1 #
2 # Copyright (c) 2019-2021 Christian Jaeger, copying@christianjaeger.ch
3 #
4 # This is free software, offered under either the same terms as perl 5
5 # or the terms of the Artistic License version 2 or the terms of the
6 # MIT License (Expat version). See the file COPYING.md that came
7 # bundled with this file.
8 #
9  
10 =head1 NAME
11  
12 FP::Failure - failure values
13  
14 =head1 SYNOPSIS
15  
16 1 ▶ use FP::Equal ':all'; use FP::Ops qw(the_method regex_substitute); use FP::List;
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
Subroutine BEGIN: called CC=1 SCAR=0.0
17 1 ▶ use FP::Failure;
Subroutine BEGIN: called CC=1 SCAR=0.0
18 is_equal \@FP::Failure::EXPORT, [qw(failure is_failure)];
19 # but there is more in EXPORT_OK...
20 1 ▶ use FP::Failure '*trace_failures';
Subroutine BEGIN: called CC=1 SCAR=0.0
21  
22 my $vals = do {
23 local $trace_failures = 0;
24 list(failure("not good"),
25 failure(666),
26 failure(undef),
27 666,
28 0,
29 undef)
30 };
31  
32 is_equal $vals->map(\&is_failure),
33 list(1, 1, 1, undef, undef, undef);
34  
35 is_equal $vals->map(sub { my ($v) = @_; $v ? "t" : "f" }),
36 list("f", "f", "f", "t", "f", "f");
37  
38 # failure dies when called in void context (for safety, failures have
39 # to be ignored *explicitly*):
40 is((eval { failure("hello"); 1 } || ref $@),
41 'FP::Failure::Failure');
42  
43 # get the wrapped value
44 is_equal $vals->filter(\&is_failure)->map(the_method "value"),
45 list("not good", 666, undef);
46  
47 # get a nice message
48 is_equal $vals->first->message,
49 "failure: 'not good'\n";
50  
51 # record backtraces
52 my $v = do {
53 local $trace_failures = 1;
54 failure(666, [$vals->first])
55 };
56  
57 is_equal $v->message,
58 "failure: 666\n because:\n failure: 'not good'\n";
59  
60 # request recorded backtrace to be shown
61 1 ▶ use Path::Tiny;
Subroutine BEGIN: called CC=1 SCAR=0.0
62 is_equal regex_substitute(sub { # cleaning up bt
63 s/line \d+/line .../g;
64 my $btlines = 0;
65 $_ = join("\n",
66 grep { not /^ \S/ or ++$btlines < 2 }
67 split /\n/)
68 },
69 $v->message(1)),
70 join("\n", "failure: 666 at ".path("lib/FP/Failure.pm")->canonpath
71 ." line ...",
72 " (eval) at lib/FP/Repl/WithRepl.pm line ...",
73 " because:",
74 " failure: 'not good'");
75  
76 # Wrapper that just returns 0 unless configured to create a failure
77 # object:
78  
79 1 ▶ use FP::Failure qw(*use_failure fails);
Subroutine BEGIN: called CC=1 SCAR=0.0
80 1 ▶ use FP::Show;
Subroutine BEGIN: called CC=1 SCAR=0.0
81  
82 is show(do { local $use_failure = 0; fails("hi") }),
83 0;
84 is show(do { local $use_failure = 1; fails("hi") }),
85 "Failure('hi', undef, undef)";
86  
87  
88 # Utility container for holding both a message and values:
89  
90 1 ▶ use FP::Failure qw(message messagefmt);
Subroutine BEGIN: called CC=1 SCAR=0.0
91  
92 is failure(message "Hi", "foo", 9)->message,
93 "failure: Hi: 'foo', 9\n";
94 is failure(message "Hi")->message,
95 "failure: Hi\n";
96  
97 # messagefmt is currently still passing everything through FP::Show;
98 # what should it do, implement another fmt character?
99 is failure(messagefmt "Hi %s %d", "foo", 9)->message,
100 "failure: Hi 'foo' 9\n";
101  
102  
103 =head1 DESCRIPTION
104  
105 Values meant to represent errors/failures and to be distinguishable
106 from non-error values. They are overloaded to be false in boolean
107 context (although doing a boolean test is not safe to distinguish from
108 non-failure values, as obviously those include false as well), or
109 checked via the `is_failure` function.
110  
111 The `value` method delivers the first argument given to `failure`,
112 `maybe_parents` the second, which is an array of the parents, meant
113 for chaining failures (reasons why this failure happened). `message`
114 produces a somewhat nice to read string, multi-line if parents are
115 chained in.
116  
117 Calling the constructor in void context throws the constructed failure
118 value as an exception.
119  
120 If the variable `$FP::Failure::trace_failures` is set to true (it can
121 be imported mutably via '*trace_failures'; default: false), then a
122 stack trace is collected with the failures and displayed with
123 `message` (if a true value is passed to message ?). (XX: use
124 `BACKTRACE=1` idea here, too? Implement the same in `Chj::Backtrace`,
125 too, and FP::Repl::Trap if fitting?)
126  
127 If the variable `$FP::Failure::use_failure` is set to true (it can be
128 imported mutably via '*use_failures'; default: false), then the
129 optionally exported wrapper function `fails` calls `failure` with its
130 arguments, otherwise it returns `0` (fully compatible with standard
131 Perl booleans, and a little bit faster).
132  
133 =head1 TODO
134  
135 Instead of using `FP::Failure::Failure` as base class, create a
136 failure protocol (FP::Abstract::Failure) instead?
137  
138 =head1 SEE ALSO
139  
140 L<FP::Either> (which wraps both cases in a shared parent type).
141  
142 Implements: L<FP::Abstract::Pure>, L<FP::Struct::Show>
143  
144 =head1 NOTE
145  
146 This is alpha software! Read the status section in the package README
147 or on the L<website|http://functional-perl.org/>.
148  
149 =cut
150  
151 package FP::Failure;
152 3 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
153 3 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
154 3 ▶use warnings FATAL => 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
155 3 ▶use Exporter "import";
Subroutine BEGIN: called CC=1 SCAR=0.0
156  
157 3 our @EXPORT = qw(failure is_failure);
158 3 our @EXPORT_OK = qw(*trace_failures *use_failure fails
159 message messagefmt);
160 3 our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]);
161  
162 3 ▶use FP::Lazy 'force';
Subroutine BEGIN: called CC=1 SCAR=0.0
163 3 ▶use Safe::Isa;
Subroutine BEGIN: called CC=1 SCAR=0.0
164 3 ▶use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
165  
166 3 package FP::Failure::Failure {
167  
168 3 ▶ use FP::Show;
Subroutine BEGIN: called CC=1 SCAR=0.0
169 3 ▶ use Safe::Isa;
Subroutine BEGIN: called CC=1 SCAR=0.0
170  
171 # avoid circular dependency on FP::Predicates
172 13 ▶ sub maybe_array {
Subroutine maybe_array: called CC=2 SCAR=6.9
173 13 my ($v) = @_;
174 13 ▶ !defined $v or ref($v) eq "ARRAY"
Branch: 1 branch
BranchTrueFalseTotal
not defined $v or ref $v eq "ARRAY" 11 2 13
175 }
176  
177 3 ▶ use FP::Struct [
Subroutine BEGIN: called CC=1 SCAR=0.0
178 3 "value",
179 [
180 \&maybe_array, "maybe_parents"
181  
182 # Array of failures that are the reason for this
183 # failure. Values other than FP::Failure::Failure are
184 # (mostly) ignored; allow anything to be stored so no
185 # complicated logic is needed for capture.
186 ],
187 "maybe_trace", # [[caller(0)],...]
188 ],
189 3 'FP::Abstract::Pure', 'FP::Struct::Show';
190  
191 use overload
192 5 ▶ bool => sub {undef},
Subroutine BEGIN: called CC=1 SCAR=0.1
Subroutine __ANON__: called CC=1 SCAR=0.0
193  
194 # Have to provide stringification, too, or it will stringify
195 # to undef and then fail to use the undef value in strings
196 # because of fatal warnings... and it can't be avoided by
197 # checking with `defined $v` first, as that returns
198 # false. Tricky Perl features.
199 0 ▶ '""' => sub { show $_[0] },
Subroutine __ANON__: not called CC=1 SCAR=6.9
200  
201 # '0+' => sub { warn "hello0+"; '' },
202 # fallback => 0
203 3 ;
204  
205 11 ▶ sub message {
Subroutine message: called CC=8 SCAR=20.8
206 11 my $s = shift;
207 11 my ($showtrace, $maybe_indent) = @_;
208 11 ▶ my $indent = $maybe_indent // "";
Condition100%2/2
$maybe_indent // ""
l!l
38
MC/DC100%1/1
$maybe_indent // ""
$maybe_indent
Truth table100%2/2
A
A= $maybe_indent
Aresult
11
00
209 11 my $tracestr = do {
210 11 ▶ if ($showtrace and my $t = $s->maybe_trace) {
Branch: 1 branch
BranchTrueFalseTotal
if ($showtrace and my $t = $s->maybe_trace) { } 1 10 11
Condition100%3/3
$showtrace and my $t = $s->maybe_trace
!ll&&!rl&&r
911
MC/DC100%2/2
$showtrace and my $t = $s->maybe_trace
$showtrace my $t = $s->maybe_trace
Truth table100%3/3
A and B
A= $showtraceB= my $t = $s->maybe_trace
ABresult
0X0
100
111
211 1 my $seen = 0;
212 join(
213 "\n$indent ",
214 map {
215 1 my (undef, $file, $line, $subname) = @$_;
216 8 ▶ $subname = "" unless $seen;
Branch: 1 branch
BranchTrueFalseTotal
unless $seen 1 7 8
217 8 $seen = 1;
218 8 "$subname at $file line $line"
219 } @$t
220 )
221 } else {
222 10 ""
223 }
224 };
225  
226 11 my $valuestr = do {
227 11 my $value = $s->value;
228 11 ▶ $value->$_isa('FP::Failure::Abstract::Message')
Branch: 1 branch
BranchTrueFalseTotal
$value->$FP::Failure::Failure::_isa('FP::Failure::Abstract::Message') ? : 6 5 11
229 ? $value->message
230 : show($value)
231 };
232 11 $indent . "failure: " . $valuestr . $tracestr . "\n" . do {
233 3 my @parents = grep { FP::Failure::is_failure($_) }
234 11 ▶ @{ $s->maybe_parents // [] };
Condition100%2/2
$s->maybe_parents // []
l!l
38
MC/DC100%1/1
$s->maybe_parents // []
$s->maybe_parents
Truth table100%2/2
A
A= $s->maybe_parents
Aresult
11
00
235 11 ▶ if (@parents) {
Branch: 1 branch
BranchTrueFalseTotal
if (@parents) { } 3 8 11
236 $indent
237 . " because:\n"
238 . join("",
239 3 map { $_->message($showtrace, $indent . " ") } @parents)
240 } else {
241 8 ""
242 }
243 }
244 }
245  
246 3 _END_
247 }
248  
249 3 our $trace_failures = 0; # bool
250  
251 13 ▶sub failure {
Subroutine failure: called CC=6 SCAR=18.0
Pod undocumented
252 13 ▶ @_ >= 1 and @_ <= 2 or fp_croak_arity "1-2";
Branch: 1 branch
BranchTrueFalseTotal
@_ >= 1 and @_ <= 2 or fp_croak_arity("1-2") 13 0 13
Condition33%1/3
@_ >= 1 and @_ <= 2
!ll&&!rl&&r
0013
MC/DC0%0/2
@_ >= 1 and @_ <= 2
@_ >= 1 @_ <= 2
Truth table33%1/3
A and B
A= @_ >= 1B= @_ <= 2
ABresult
0X0
100
111
253 13 my ($value, $maybe_parents) = @_;
254 my $v = FP::Failure::Failure->new(
255 $value,
256 $maybe_parents,
257 $trace_failures
258 13 ▶ ? do {
Branch: 1 branch
BranchTrueFalseTotal
$FP::Failure::trace_failures ? : 1 12 13
259 1 my @t;
260 1 my $i = 0;
261 1 while (1) {
262 9 my $t = [caller $i];
263 9 ▶ last unless @$t;
Branch: 1 branch
BranchTrueFalseTotal
unless @$t 1 8 9
264 8 push @t, $t;
265 8 $i++
266 }
267 \@t
268 1 }
269 : undef
270 );
271 13 ▶ defined wantarray ? $v : die $v ## no critic
Branch: 1 branch
BranchTrueFalseTotal
defined wantarray ? : 12 1 13
272 }
273  
274 15 ▶sub is_failure {
Subroutine is_failure: called CC=2 SCAR=7.2
Pod undocumented
275 15 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 15 0 15
276 15 force($_[0])->$_isa("FP::Failure::Failure")
277 }
278  
279 3 our $use_failure = 0; # bool
280  
281 2 ▶sub fails {
Subroutine fails: called CC=5 SCAR=18.2
Pod undocumented
282 2 ▶ @_ >= 1 and @_ <= 2 or fp_croak_arity "1-2";
Branch: 1 branch
BranchTrueFalseTotal
@_ >= 1 and @_ <= 2 or fp_croak_arity("1-2") 2 0 2
Condition33%1/3
@_ >= 1 and @_ <= 2
!ll&&!rl&&r
002
MC/DC0%0/2
@_ >= 1 and @_ <= 2
@_ >= 1 @_ <= 2
Truth table33%1/3
A and B
A= @_ >= 1B= @_ <= 2
ABresult
0X0
100
111
283 2 ▶ $use_failure ? &failure(@_) : defined wantarray ? 0 ## no critic
Branch: 2 branches
BranchTrueFalseTotal
$FP::Failure::use_failure ? : 1 1 2
defined wantarray ? : 1 0 1
284 : die "fails called in void context";
285 }
286  
287 3 package FP::Failure::Abstract::Message {
288 3 ▶ use FP::Struct [], 'FP::Abstract::Pure', 'FP::Struct::Show';
Subroutine BEGIN: called CC=1 SCAR=0.0
289 3 _END_
290 }
291  
292 3 package FP::Failure::Message {
293 3 ▶ use FP::Show;
Subroutine BEGIN: called CC=1 SCAR=0.0
294 3 ▶ use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
295  
296 3 ▶ use FP::Struct ['messagestring', 'arguments'],
Subroutine BEGIN: called CC=1 SCAR=0.0
297 3 'FP::Failure::Abstract::Message';
298  
299 5 ▶ sub message {
Subroutine message: called CC=3 SCAR=11.0
300 5 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 5 0 5
301 5 my $s = shift;
302 5 my $args = $s->arguments;
303 5 my $msg = $s->messagestring;
304 5 ▶ @$args ? "$msg: " . join(", ", map { show $_ } @$args) : $msg
Branch: 1 branch
BranchTrueFalseTotal
@$args ? : 3 2 5
305 }
306 3 _END_
307 }
308  
309 5 ▶sub message {
Subroutine message: called CC=1 SCAR=0.0
Pod undocumented
310 5 my ($msgstr, @args) = @_;
311 5 FP::Failure::Message->new($msgstr, \@args)
312 }
313  
314 3 package FP::Failure::MessageFmt {
315 3 ▶ use FP::Show;
Subroutine BEGIN: called CC=1 SCAR=0.0
316 3 ▶ use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
317  
318 3 ▶ use FP::Struct ['formatstring', 'arguments'],
Subroutine BEGIN: called CC=1 SCAR=0.0
319 3 'FP::Failure::Abstract::Message';
320  
321 1 ▶ sub message {
Subroutine message: called CC=2 SCAR=7.0
322 1 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 1 0 1
323 1 my $s = shift;
324 1 sprintf($s->formatstring, map { show $_ } @{ $s->arguments })
325 }
326  
327 3 _END_
328 }
329  
330 1 ▶sub messagefmt {
Subroutine messagefmt: called CC=3 SCAR=12.7
Pod undocumented
331 1 my ($fmtstr, @args) = @_;
332 1 ▶ if (not $fmtstr =~ /\%\%/) {
Branch: 1 branch
BranchTrueFalseTotal
if (not $fmtstr =~ /\%\%/) { } 1 0 1
333 1 ▶ if (($fmtstr =~ tr/%/%/) == @args) {
Branch: 1 branch
BranchTrueFalseTotal
if ($fmtstr =~ tr/%// == @args) { } 1 0 1
334 1 FP::Failure::MessageFmt->new($fmtstr, \@args)
335 } else {
336 0 die "wrong number of arguments (" . @args
337 . ") for given format string '$fmtstr'"
338 }
339 } else {
340 0 die "full fmt parsing support not implemented yet" # XX todo
341 }
342 }
343  
344 3 1
« lib/Chj/tempdir.pm ↑ Summary lib/FP/Array_sort.pm »