lib/FP/Optional.pm

filter: Statementstmt 73.2% 52 / 71 Branchbran 36.6% 11 / 30 Conditioncond 40.0% 2 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 72.7% 16 / 22 Podpod 28.5% 2 / 7 totaltotal 60.1% 83 / 138 CC 18 SCAR 13.8
CC
18
Cov
61%
__ANON__
12.0
__ANON__
6.0
__ANON__
6.0
CRAP 4.0
« bin/expand-tail ↑ Summary lib/FP/Array/Mixin.pm »
1 #
2 # Copyright (c) 2015-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::Optional - dealing with optional values
13  
14 =head1 SYNOPSIS
15  
16 1 ▶ use FP::Optional qw(perhaps_to_maybe perhaps_to_x perhaps_to_or
Subroutine BEGIN: called CC=1 SCAR=0.0
17 perhaps_to_exists
18 1 optionally poptionally);
19  
20 3 ▶ sub perhaps_div {
Subroutine perhaps_div: called CC=2 SCAR=6.9
21 3 my ($a, $b) = @_;
22 3 ▶ $b == 0 ? () : $a/$b
Branch: 1 branch
BranchTrueFalseTotal
$b == 0 ? : 1 2 3
23 }
24 if (my ($r) = perhaps_div 10, 2) {
25 is $r, 5;
26 }
27 *maybe_div = perhaps_to_maybe \&perhaps_div;
28 is maybe_div(10, 2), 5;
29 is maybe_div(10, 0), undef;
30  
31 1 ▶ use FP::Div qw(square);
Subroutine BEGIN: called CC=1 SCAR=0.0
32 # short-cutting evaluation for undef:
33 *optionally_square = optionally(\&square);
34 is optionally_square(2), 4;
35 is optionally_square(undef), undef;
36  
37  
38 =head1 DESCRIPTION
39  
40 Places holding or code passing optional values do either hold or pass
41 a 'real' value, or the absence of a value ('nothing').
42  
43 There are two straight-forward ways to return 'nothing' from a
44 function: undef and the empty list. The empty list has the advantage
45 that it is unambiguous, but the disadvantage that the result needs to
46 be received in list context, which can be more verbose, also, there is
47 the danger of accidentally interpolate the result into a list of other
48 values, which will go wrong if the values in the list have positional
49 meaning.
50  
51 Example using undef:
52  
53 =for test ignore
54 package Users;
55 my %uid_to_username;
56 sub maybe_uid_to_username {
57 my ($uid) = @_;
58 $uid_to_username{$uid}
59 }
60 package main;
61 use Users;
62 if (defined (my $user = maybe_uid_to_username (123))) {
63 ...
64 } else {
65 ...
66 }
67 my @existing_usernames = map {
68 my $maybe_username = maybe_uid_to_username $_;
69 defined $maybe_uid_to_username ? $maybe_uid_to_username : ()
70 } @uids;
71  
72 # assume rename_user expects pairs of usernames:
73 rename_users (map { maybe_uid_to_username $_ } @uidpairs)
74  
75 Example using the empty list:
76  
77 package Users;
78 my %uid_to_username;
79 sub perhaps_uid_to_username {
80 my ($uid) = @_;
81 exists $uid_to_username{$uid} ? $uid_to_username{$uid} : ()
82 }
83 package main;
84 use Users;
85 if (my ($user) = perhaps_uid_to_username (123)) {
86 ...
87 } else {
88 ...
89 }
90 my @existing_usernames = map { perhaps_uid_to_username $_ } @uids;
91  
92 # This would be *wrong*:
93 # rename_users (map { perhaps_uid_to_username $_ } @uidpairs)
94  
95 # Instead this wordy version would need to be used:
96 rename_users (map {
97 if (my ($name) = perhaps_uid_to_username $_) {
98 $name
99 } else {
100 undef
101 } @uidpairs);
102  
103 An alternative to optional values are exceptions:
104  
105 package Users;
106 my %uid_to_username;
107 sub x_uid_to_username {
108 my ($uid) = @_;
109 exists $uid_to_username{$uid} ? $uid_to_username{$uid}
110 : die "no such user"
111 }
112 package main;
113 use Users;
114 my $user = x_uid_to_username (123);
115 ...
116 my @existing_usernames = map {
117 my $name;
118 eval { $name = x_uid_to_username $_; 1 } ? $name : ()
119 } @uids;
120  
121 rename_users (map { x_uid_to_username $_ } @uidpairs);
122  
123  
124 The functional perl project *always* prefixes function names with
125 `maybe_` or `perhaps_` if they optionally don't return a value, and
126 depending on whether they do so by returning undef or the empty
127 list. The reason is to make the user of the library directly visibly
128 aware of it, to prevent bugs.
129  
130 It also prefixes variable names with maybe_ if they are
131 optionally undef. (If they are introduced in an `if` conditional form,
132 then no prefixing is done as they will always be set in the scope of
133 the variable (well, this is not strictly true as in the else branch
134 they are visible too, but that's more like an accident of the Perl
135 language, right?))
136  
137 The functions in this module help convert between functions following
138 these conventions.
139  
140 It also offers functions to build chains that propagate failures:
141  
142 =over 4
143  
144 =item optionally (\&f [, $pos])
145  
146 Returns a function that when receiving undef as its first argument, or
147 $_[$pos] if $pos given, directly returns undef without calling f;
148 otherwise calls f with the original arguments (with tail-call
149 optimization).
150  
151 =item poptionally (\&f)
152  
153 Returns a function that when not receiving any argument, directly
154 returns (). Otherwise calls it with the original arguments (tail-call
155 optimized).
156  
157 =back
158  
159 =head1 IDEAS
160  
161 Implement a binary operator (perhaps named `%%` or `otherwise`), that
162 evaluates the left-hand side in list context, and returns the
163 right-hand side if the result is the empty list, or the last element
164 of the list otherwise. (Zefram says one could implement such an
165 operator, using cv_set_call_checker() and generating a custom op based
166 on OP_DOR.) Example code: `pass($foo->perhaps_name %% $myname)`.
167  
168 =head1 SEE ALSO
169  
170 `maybe` in L<FP::Predicates>
171  
172 Perl 6 error values (which are false in conditional context but carry
173 an error message)
174  
175 =head1 NOTE
176  
177 This is alpha software! Read the status section in the package README
178 or on the L<website|http://functional-perl.org/>.
179  
180 =cut
181  
182 package FP::Optional;
183 60 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
184 60 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
185 60 ▶use warnings FATAL => 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
186 60 ▶use Exporter "import";
Subroutine BEGIN: called CC=1 SCAR=0.0
187  
188 60 our @EXPORT = qw();
189 our @EXPORT_OK
190 60 = qw(perhaps_to_maybe perhaps_to_x perhaps_to_or perhaps_to_exists
191 optionally poptionally have);
192 60 our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]);
193  
194 60 ▶use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
195 60 ▶use FP::Docstring;
Subroutine BEGIN: called CC=1 SCAR=0.0
196  
197 # Functions to change the kind of optionals API:
198  
199 157 ▶sub perhaps_to_maybe {
Subroutine perhaps_to_maybe: called CC=2 SCAR=7.0
Pod undocumented
200 157 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 157 0 157
201 157 my ($f) = @_;
202 16 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
203 16 ▶ if (my ($v) = &$f(@_)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($v) = &$f(@_)) { } 14 2 16
204 14 $v
205 } else {
206 undef
207 2 }
208 }
209 157 }
210  
211 1 ▶sub perhaps_to_x {
Subroutine perhaps_to_x: called CC=2 SCAR=10.5
Pod undocumented
212 1 ▶ @_ == 2 or fp_croak_arity 2;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 2 or fp_croak_arity(2) 1 0 1
213 1 my ($f, $exception) = @_;
214 0 ▶ sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
215 0 ▶ if (my ($v) = &$f(@_)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($v) = &$f(@_)) { } 0 0 0
216 0 $v
217 } else {
218 0 die $exception
219 }
220 }
221 1 }
222  
223 1 ▶sub perhaps_to_or {
Subroutine perhaps_to_or: called CC=2 SCAR=12.4
Pod undocumented
224 1 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 1 0 1
225 1 my ($f) = @_;
226 0 ▶ sub {
Subroutine __ANON__: not called CC=3 SCAR=24.8
227 0 ▶ @_ == 3 or fp_croak_arity 3;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 3 or fp_croak_arity(3) 0 0 0
228 0 my ($t, $k, $other) = @_;
229 0 ▶ if (my ($v) = &$f($t, $k)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($v) = &$f($t, $k)) { } 0 0 0
230 0 $v
231 } else {
232 0 $other
233 }
234 }
235 1 }
236  
237 1 ▶sub perhaps_to_exists {
Subroutine perhaps_to_exists: called CC=2 SCAR=10.5
Pod undocumented
238 1 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 1 0 1
239 1 my ($f) = @_;
240 0 ▶ sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
241 0 ▶ if (my ($_v) = &$f(@_)) {
Branch: 1 branch
BranchTrueFalseTotal
if (my($_v) = &$f(@_)) { } 0 0 0
242 0 1
243 } else {
244 0 ''
245 }
246 }
247 1 }
248  
249 # Functions to help build chains:
250  
251 # build functions that short-cut the 'nothing' case:
252  
253 1 ▶sub optionally {
Subroutine optionally: called CC=4 SCAR=14.5
Pod documented
254 1 ▶ @_ >= 1 and @_ <= 2 or fp_croak_arity "1-2";
Branch: 1 branch
BranchTrueFalseTotal
@_ >= 1 and @_ <= 2 or fp_croak_arity("1-2") 1 0 1
Condition33%1/3
@_ >= 1 and @_ <= 2
!ll&&!rl&&r
001
MC/DC0%0/2
@_ >= 1 and @_ <= 2
@_ >= 1 @_ <= 2
Truth table33%1/3
A and B
A= @_ >= 1B= @_ <= 2
ABresult
0X0
100
111
255 1 my ($f, $maybe_pos) = @_;
256 1 ▶ my $pos = $maybe_pos // 0;
Condition50%1/2
$maybe_pos // 0
l!l
01
MC/DC0%0/1
$maybe_pos // 0
$maybe_pos
Truth table50%1/2
A
A= $maybe_pos
Aresult
11
00
257 2 ▶ sub {
Subroutine __ANON__: called CC=2 SCAR=6.9
258 2 ▶ if (defined $_[$pos]) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $_[$pos]) { } 1 1 2
259 1 goto &$f
260 } else {
261  
262 # pass on the undef value
263 undef
264 1 }
265 }
266 1 }
267  
268 # perhaps-based optionally: (XX better name? perhapsionally??)
269 0 ▶sub poptionally {
Subroutine poptionally: not called CC=2 SCAR=17.9
Pod documented
270 0 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 0 0 0
271 0 my ($f) = @_;
272 0 ▶ sub {
Subroutine __ANON__: not called CC=2 SCAR=17.9
273 0 ▶ if (@_) {
Branch: 1 branch
BranchTrueFalseTotal
if (@_) { } 0 0 0
274 0 goto &$f
275 } else {
276  
277 # pass on the empty list
278 ()
279 0 }
280 }
281 0 }
282  
283 0 ▶sub have {
Subroutine have: not called CC=2 SCAR=17.9
Pod undocumented
284 0 __ 'Turn a "perhaps" (one or more values in list context meaning
285 there is a result, none meaning a failure) into a boolean. In
286 other words, `have` returns true if receiving at least one
287 argument.';
288 0 ▶ @_ ? 1 : ''
Branch: 1 branch
BranchTrueFalseTotal
@_ ? : 0 0 0
289 }
290  
291 60 1
« bin/expand-tail ↑ Summary lib/FP/Array/Mixin.pm »