| 1 | # | ||||||||||||||||||||
| 2 | # Copyright (c) 2015-2020 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::Weak - utilities to weaken references | ||||||||||||||||||||
| 13 | |||||||||||||||||||||
| 14 | =head1 SYNOPSIS | ||||||||||||||||||||
| 15 | |||||||||||||||||||||
| 16 | 1 | ▶ | use FP::Weak; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 17 | |||||||||||||||||||||
| 18 | 1 | ▶ | sub foo { | ||||||||||||||||||
|
Subroutine
foo: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 19 | 1 | ▶ | my $f; $f = sub { my ($n,$tot) = @_; $n < 100 ? &$f($n+1, $tot+$n) : $tot }; | ||||||||||||||||||
|
Subroutine
__ANON__: called CC=2 SCAR=6.9
Branch: 1 branch
| |||||||||||||||||||||
| 20 | 1 | Weakened $f | |||||||||||||||||||
| 21 | } | ||||||||||||||||||||
| 22 | |||||||||||||||||||||
| 23 | is foo->(10, 0), 4905; | ||||||||||||||||||||
| 24 | # the subroutine returned from foo will not be leaked. | ||||||||||||||||||||
| 25 | |||||||||||||||||||||
| 26 | |||||||||||||||||||||
| 27 | =head1 DESCRIPTION | ||||||||||||||||||||
| 28 | |||||||||||||||||||||
| 29 | =over 4 | ||||||||||||||||||||
| 30 | |||||||||||||||||||||
| 31 | =item weaken <location> | ||||||||||||||||||||
| 32 | |||||||||||||||||||||
| 33 | `Scalar::Util`'s `weaken`, unless one of the `with_..` development | ||||||||||||||||||||
| 34 | utils are used (or `$FP::Weak::weaken` is changed). | ||||||||||||||||||||
| 35 | |||||||||||||||||||||
| 36 | =item Weakened <location> | ||||||||||||||||||||
| 37 | |||||||||||||||||||||
| 38 | Calls `weaken <location>` after copying the reference, then returns | ||||||||||||||||||||
| 39 | the unweakened reference. | ||||||||||||||||||||
| 40 | |||||||||||||||||||||
| 41 | =item Keep <location> | ||||||||||||||||||||
| 42 | |||||||||||||||||||||
| 43 | Protect <location> from being weakened by accessing elements of `@_`. | ||||||||||||||||||||
| 44 | |||||||||||||||||||||
| 45 | =back | ||||||||||||||||||||
| 46 | |||||||||||||||||||||
| 47 | Optionally exported development utils: | ||||||||||||||||||||
| 48 | |||||||||||||||||||||
| 49 | =over 4 | ||||||||||||||||||||
| 50 | |||||||||||||||||||||
| 51 | =item noweaken ($var), noWeakened ($var) | ||||||||||||||||||||
| 52 | |||||||||||||||||||||
| 53 | No-ops. The idea is to prefix the weakening ops with 'no' to disable | ||||||||||||||||||||
| 54 | them. | ||||||||||||||||||||
| 55 | |||||||||||||||||||||
| 56 | =item warnweaken ($var), warnWeakened ($var) | ||||||||||||||||||||
| 57 | |||||||||||||||||||||
| 58 | Give a warning in addition to the weakening operation. | ||||||||||||||||||||
| 59 | |||||||||||||||||||||
| 60 | =item cluckweaken ($var), cluckWeakened ($var) | ||||||||||||||||||||
| 61 | |||||||||||||||||||||
| 62 | Give a warning with backtrace in addition to the weakening operation. | ||||||||||||||||||||
| 63 | |||||||||||||||||||||
| 64 | =item with_noweaken { code }, &with_noweaken ($proc) | ||||||||||||||||||||
| 65 | |||||||||||||||||||||
| 66 | =item with_warnweaken { code } (and same as above) | ||||||||||||||||||||
| 67 | |||||||||||||||||||||
| 68 | =item with_cluckweaken { code } | ||||||||||||||||||||
| 69 | |||||||||||||||||||||
| 70 | Within their dynamic scope, globally change `weaken` to one of the | ||||||||||||||||||||
| 71 | alternatives | ||||||||||||||||||||
| 72 | |||||||||||||||||||||
| 73 | =item do_weaken (1|0|"yes"|"no"|"on"|"off"|"warn"|"cluck") | ||||||||||||||||||||
| 74 | |||||||||||||||||||||
| 75 | Turn weakening on and off (unscoped, 'persistently'). | ||||||||||||||||||||
| 76 | |||||||||||||||||||||
| 77 | =back | ||||||||||||||||||||
| 78 | |||||||||||||||||||||
| 79 | =head1 NOTE | ||||||||||||||||||||
| 80 | |||||||||||||||||||||
| 81 | This is alpha software! Read the status section in the package README | ||||||||||||||||||||
| 82 | or on the L<website|http://functional-perl.org/>. | ||||||||||||||||||||
| 83 | |||||||||||||||||||||
| 84 | =cut | ||||||||||||||||||||
| 85 | |||||||||||||||||||||
| 86 | package FP::Weak; | ||||||||||||||||||||
| 87 | 60 | ▶ | use strict; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 88 | 60 | ▶ | use warnings; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 89 | 60 | ▶ | use warnings FATAL => 'uninitialized'; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 90 | 60 | ▶ | use Exporter "import"; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 91 | |||||||||||||||||||||
| 92 | 60 | our @EXPORT = qw(weaken Weakened Keep); | |||||||||||||||||||
| 93 | 60 | our @EXPORT_OK = qw( | |||||||||||||||||||
| 94 | do_weaken | ||||||||||||||||||||
| 95 | noweaken noWeakened with_noweaken | ||||||||||||||||||||
| 96 | warnweaken warnWeakened with_warnweaken | ||||||||||||||||||||
| 97 | cluckweaken cluckWeakened with_cluckweaken | ||||||||||||||||||||
| 98 | ); | ||||||||||||||||||||
| 99 | 60 | our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]); | |||||||||||||||||||
| 100 | |||||||||||||||||||||
| 101 | 60 | ▶ | use Scalar::Util (); | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 102 | 60 | ▶ | use FP::Carp; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 103 | |||||||||||||||||||||
| 104 | 60 | our $weaken = \&Scalar::Util::weaken; | |||||||||||||||||||
| 105 | |||||||||||||||||||||
| 106 | 12891 | ▶ | sub weaken { | ||||||||||||||||||
|
Subroutine
weaken: called CC=2 SCAR=7.2
Pod
documented
| |||||||||||||||||||||
| 107 | 12891 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 108 | 12891 | goto &$weaken | |||||||||||||||||||
| 109 | } | ||||||||||||||||||||
| 110 | |||||||||||||||||||||
| 111 | # XX is there really no way (short of re-exporting everywhere with a | ||||||||||||||||||||
| 112 | # Chj::ruse approach) to avoid the extra function call cost? | ||||||||||||||||||||
| 113 | |||||||||||||||||||||
| 114 | # protect a variable from being pruned by callees that prune their | ||||||||||||||||||||
| 115 | # arguments | ||||||||||||||||||||
| 116 | 46 | ▶ | sub Keep { | ||||||||||||||||||
|
Subroutine
Keep: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||||||||||||
| 117 | 46 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 118 | 46 | my ($v) = @_; | |||||||||||||||||||
| 119 | 46 | $v | |||||||||||||||||||
| 120 | } | ||||||||||||||||||||
| 121 | |||||||||||||||||||||
| 122 | # weaken a variable, but also provide a non-weakened reference to its | ||||||||||||||||||||
| 123 | # value as result | ||||||||||||||||||||
| 124 | 535 | ▶ | sub Weakened { | ||||||||||||||||||
|
Subroutine
Weakened: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||
| 125 | 535 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 126 | 535 | my ($ref) = @_; | |||||||||||||||||||
| 127 | 535 | weaken $_[0]; | |||||||||||||||||||
| 128 | 535 | $ref | |||||||||||||||||||
| 129 | } | ||||||||||||||||||||
| 130 | |||||||||||||||||||||
| 131 | 3 | ▶ | sub noweaken { | ||||||||||||||||||
|
Subroutine
noweaken: called CC=2 SCAR=7.6
Pod
documented
| |||||||||||||||||||||
| 132 | 3 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 133 | |||||||||||||||||||||
| 134 | # noop | ||||||||||||||||||||
| 135 | } | ||||||||||||||||||||
| 136 | |||||||||||||||||||||
| 137 | 0 | ▶ | sub noWeakened { | ||||||||||||||||||
|
Subroutine
noWeakened: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||
| 138 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 139 | 0 | $_[0] | |||||||||||||||||||
| 140 | } | ||||||||||||||||||||
| 141 | |||||||||||||||||||||
| 142 | 2 | ▶ | sub with_noweaken (&) { local $weaken = \&noweaken; &{ $_[0] }() } | ||||||||||||||||||
|
Subroutine
with_noweaken: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 143 | |||||||||||||||||||||
| 144 | 60 | ▶ | use Carp; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 145 | |||||||||||||||||||||
| 146 | 1 | ▶ | sub warnweaken { | ||||||||||||||||||
|
Subroutine
warnweaken: called CC=2 SCAR=7.1
Pod
documented
| |||||||||||||||||||||
| 147 | 1 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 148 | 1 | carp "weaken ($_[0])"; | |||||||||||||||||||
| 149 | 1 | Scalar::Util::weaken($_[0]); | |||||||||||||||||||
| 150 | } | ||||||||||||||||||||
| 151 | |||||||||||||||||||||
| 152 | 0 | ▶ | sub warnWeakened { | ||||||||||||||||||
|
Subroutine
warnWeakened: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||
| 153 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 154 | 0 | carp "weaken ($_[0])"; | |||||||||||||||||||
| 155 | 0 | Weakened($_[0]); | |||||||||||||||||||
| 156 | } | ||||||||||||||||||||
| 157 | |||||||||||||||||||||
| 158 | 1 | ▶ | sub with_warnweaken (&) { local $weaken = \&warnweaken; &{ $_[0] }() } | ||||||||||||||||||
|
Subroutine
with_warnweaken: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||
| 159 | |||||||||||||||||||||
| 160 | 60 | ▶ | use Carp 'cluck'; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 161 | 60 | ▶ | use FP::Carp; | ||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||
| 162 | |||||||||||||||||||||
| 163 | 0 | ▶ | sub cluckweaken { | ||||||||||||||||||
|
Subroutine
cluckweaken: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||
| 164 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 165 | 0 | cluck "weaken ($_[0])"; | |||||||||||||||||||
| 166 | 0 | Scalar::Util::weaken($_[0]); | |||||||||||||||||||
| 167 | } | ||||||||||||||||||||
| 168 | |||||||||||||||||||||
| 169 | 0 | ▶ | sub cluckWeakened { | ||||||||||||||||||
|
Subroutine
cluckWeakened: not called CC=2 SCAR=17.9
Pod
documented
| |||||||||||||||||||||
| 170 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 171 | 0 | cluck "weaken ($_[0])"; | |||||||||||||||||||
| 172 | 0 | Weakened($_[0]); | |||||||||||||||||||
| 173 | } | ||||||||||||||||||||
| 174 | |||||||||||||||||||||
| 175 | 0 | ▶ | sub with_cluckweaken (&) { local $weaken = \&cluckweaken; &{ $_[0] }() } | ||||||||||||||||||
|
Subroutine
with_cluckweaken: not called CC=1 SCAR=6.9
Pod
documented
| |||||||||||||||||||||
| 176 | |||||||||||||||||||||
| 177 | 0 | ▶ | sub do_weaken { | ||||||||||||||||||
|
Subroutine
do_weaken: not called CC=4 SCAR=30.0
Pod
documented
| |||||||||||||||||||||
| 178 | 0 | ▶ | @_ == 1 or fp_croak_arity 1; | ||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||
| 179 | 0 | my ($v) = @_; | |||||||||||||||||||
| 180 | my $w = $v | ||||||||||||||||||||
| 181 | ? ( | ||||||||||||||||||||
| 182 | +{ | ||||||||||||||||||||
| 183 | 1 => \&Scalar::Util::weaken, | ||||||||||||||||||||
| 184 | "yes" => \&Scalar::Util::weaken, | ||||||||||||||||||||
| 185 | "no" => \&noweaken, | ||||||||||||||||||||
| 186 | "on" => \&Scalar::Util::weaken, | ||||||||||||||||||||
| 187 | "off" => \&noweaken, | ||||||||||||||||||||
| 188 | "noweaken" => \&noweaken, | ||||||||||||||||||||
| 189 | "warn" => \&warnweaken, | ||||||||||||||||||||
| 190 | "warnweaken" => \&warnweaken, | ||||||||||||||||||||
| 191 | "cluck" => \&cluckweaken, | ||||||||||||||||||||
| 192 | "cluckweaken" => \&cluckweaken, | ||||||||||||||||||||
| 193 | 0 | ▶ | }->{$v} // die "do_weaken: unknown key '$v'" | ||||||||||||||||||
|
Branch: 1 branch
Condition0%0/2
{1, \&Scalar::Util::weaken, "yes", \&Scalar::Util::weaken, "no", \&FP::Weak::noweaken, "on", \&Scalar::Util::weaken, "off", \&FP::Weak::noweaken, "noweaken", \&FP::Weak::noweaken, "warn", \&FP::Weak::warnweaken, "warnweaken", \&FP::Weak::warnweaken, "cluck", \&FP::Weak::cluckweaken, "cluckweaken", \&FP::Weak::cluckweaken}->{$v} // die("do_weaken: unknown key '${v}'")
MC/DC0%0/1
{1, \&Scalar::Util::weaken, "yes", \&Scalar::Util::weaken, "no", \&FP::Weak::noweaken, "on", \&Scalar::Util::weaken, "off", \&FP::Weak::noweaken, "noweaken", \&FP::Weak::noweaken, "warn", \&FP::Weak::warnweaken, "warnweaken", \&FP::Weak::warnweaken, "cluck", \&FP::Weak::cluckweaken, "cluckweaken", \&FP::Weak::cluckweaken}->{$v} // die("do_weaken: unknown key '${v}'")
{1, \&Scalar::Util::weaken, "yes", \&Scalar::Util::weaken, "no", \&FP::Weak::noweaken, "on", \&Scalar::Util::weaken, "off", \&FP::Weak::noweaken, "noweaken", \&FP::Weak::noweaken, "warn", \&FP::Weak::warnweaken, "warnweaken", \&FP::Weak::warnweaken, "cluck", \&FP::Weak::cluckweaken, "cluckweaken", \&FP::Weak::cluckweaken}->{$v}
Truth table0%0/2
A
A= {1, \&Scalar::Util::weaken, "yes", \&Scalar::Util::weaken, "no", \&FP::Weak::noweaken, "on", \&Scalar::Util::weaken, "off", \&FP::Weak::noweaken, "noweaken", \&FP::Weak::noweaken, "warn", \&FP::Weak::warnweaken, "warnweaken", \&FP::Weak::warnweaken, "cluck", \&FP::Weak::cluckweaken, "cluckweaken", \&FP::Weak::cluckweaken}->{$v}
| |||||||||||||||||||||
| 194 | ) | ||||||||||||||||||||
| 195 | : \&noweaken; | ||||||||||||||||||||
| 196 | 0 | $weaken = $w | |||||||||||||||||||
| 197 | } | ||||||||||||||||||||
| 198 | |||||||||||||||||||||
| 199 | 60 | 1 | |||||||||||||||||||