lib/FP/Show.pm

filter: Statementstmt 66.3% 73 / 110 Branchbran 44.4% 16 / 36 Conditioncond 40.0% 2 / 5 MC/DCmcdc 0.0% 0 / 3 Subroutinesub 76.9% 20 / 26 Podpod 0.0% 0 / 4 totaltotal 60.3% 111 / 184 CC 20 SCAR 26.7
CC
20
Cov
60%
__ANON__
58.4
show
8.8
keyshow
5.0
CRAP 14.4
« .htmlgen/gen ↑ Summary lib/FP/Trie.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::Show - give (nice) code representation for debugging purposes
13  
14 =head1 SYNOPSIS
15  
16 1 ▶ use FP::Show; # exports 'show'
Subroutine BEGIN: called CC=1 SCAR=0.0
17 1 ▶ use FP::List;
Subroutine BEGIN: called CC=1 SCAR=0.0
18  
19 is show(list(3, 4)->map(sub{$_[0]*10})), "list(30, 40)";
20  
21  
22 =head1 DESCRIPTION
23  
24 The 'show' function takes a value and returns a string of Perl code
25 which when evaluated should produce an equivalent clone of that value
26 (assuming that the Perl functions used in the string are imported into
27 the namespace where the code is evaluated).
28  
29 It is somewhat like Data::Dumper, but enables classes to determine the
30 formatting of their instances by implementing the
31 L<FP::Abstract::Show> protocol (for details, see there). This allows
32 for concise, more highlevel output than just showing the bare
33 internals. It's, for example, normally not useful when inspecting data
34 for debugging to know that an instance of FP::List consists of a chain
35 of FP::List::Pair objects which in turn are made of blessed arrays or
36 what not; just showing a call to the same convenience constructor
37 function that can be used normally to create such a value is a better
38 choice (see the example in the SYNOPSIS, and for more examples the
39 `intro` document of the Functional Perl distribution or website).
40  
41 `show` always works, regardless of whether a value implements the
42 protocol--it falls back to L<Data::Dumper>.
43  
44  
45 =head1 ALTERNATIVES
46  
47 Data::Dumper *does* have a similar feature, $Data::Dumper::Freezer,
48 but it needs the object to be mutated, which is not what one will
49 want.
50  
51 Why not use string overloading instead? Because '""' overloading is
52 returning 'plain' strings, not perl code (or so it seems, is there any
53 spec that defines exactly what it means?) Code couldn't know whether
54 to quote the result:
55  
56 3 ▶ sub foo2 {
Subroutine foo2: called CC=1 SCAR=0.0
57 3 my ($l) = @_;
58 # this is quoting safe:
59 3 die "not what we wanted: ".show($l)
60 # this would not be:
61 #die "not what we wanted: $l"
62 }
63  
64 eval { foo2 list 100-1, "bottles"; };
65 like $@, qr/^\Qnot what we wanted: list(99, 'bottles')/;
66 eval { foo2 "list(99, 'bottles')"; };
67 like $@, qr/^\Qnot what we wanted: 'list(99, \'bottles\')'/;
68 # so how would you tell which value foo2 really got in each case,
69 # just from looking at the message?
70  
71 # also:
72 eval { foo2 +{a => 1, b => 10}; };
73 like $@, qr/^\Qnot what we wanted: +{a => 1, b => 10}/;
74 # would die with something like:
75 # not what we wanted: HASH(0xEADBEEF)
76 # which isn't very informative
77  
78 Embedding pointer values in the output also means that it can't be
79 used for automatic testing. (Even with a future implementation of
80 cut-offs, values returned by `show` will be good enough when what one
81 needs to do is compare against a short representation. Also, likely we
82 would implement the cut-off value as an optional parameter.)
83  
84 =head1 BUGS
85  
86 Show can't currently handle circular data structures (it will run out
87 of stack space), and it will not detect sharing.
88  
89 Show does not use code formatting, which can make complex output
90 difficult to read.
91  
92 Both of these are planned to be fixed by using L<FP::AST::Perl> and
93 changing the protocol.
94  
95 =head1 SEE ALSO
96  
97 L<FP::Abstract::Show> for the protocol definition. Note that FP::Show
98 also works on values which don't implement the protocol (fall back to
99 Data::Dumper).
100  
101 L<http://www.functional-perl.org/docs/intro.xhtml> for the mentioned intro.
102  
103 L<FP::Equal>
104  
105 =head1 NOTE
106  
107 This is alpha software! Read the status section in the package README
108 or on the L<website|http://functional-perl.org/>.
109  
110 =cut
111  
112 package FP::Show;
113 86 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
114 86 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
115 86 ▶use warnings FATAL => 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
116 86 ▶use Exporter "import";
Subroutine BEGIN: called CC=1 SCAR=0.0
117  
118 86 our @EXPORT = qw(show);
119 86 our @EXPORT_OK = qw(show_many parameterized_show_coderef);
120 86 our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]);
121  
122 86 ▶use Chj::TerseDumper qw(terseDumper);
Subroutine BEGIN: called CC=1 SCAR=0.0
123 86 ▶use Scalar::Util qw(reftype);
Subroutine BEGIN: called CC=1 SCAR=0.0
124 86 ▶use Devel::Peek q(DumpWithOP);
Subroutine BEGIN: called CC=1 SCAR=0.0
125 86 ▶use Capture::Tiny qw(capture_stderr);
Subroutine BEGIN: called CC=1 SCAR=0.0
126 86 ▶use Scalar::Util qw(blessed);
Subroutine BEGIN: called CC=1 SCAR=0.0
127 86 ▶use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
128  
129 9 ▶sub keyshow {
Subroutine keyshow: called CC=4 SCAR=16.1
Pod undocumented
130 9 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 9 0 9
131 9 my ($str) = @_;
132 (
133 9 ▶ $str =~ /^\w+$/s
Branch: 1 branch
BranchTrueFalseTotal
$str =~ /^\w+$/s && $str =~ /[a-zA-Z]/s ? : 9 0 9
Condition33%1/3
$str =~ /^\w+$/s and $str =~ /[a-zA-Z]/s
!ll&&!rl&&r
009
MC/DC0%0/2
$str =~ /^\w+$/s and $str =~ /[a-zA-Z]/s
$str =~ /^\w+$/s $str =~ /[a-zA-Z]/s
Truth table33%1/3
A and B
A= $str =~ /^\w+$/sB= $str =~ /[a-zA-Z]/s
ABresult
0X0
100
111
134 and
135  
136 # make sure it's not just an integer, as that would not be quoted
137 # by perl and if big enough yield something different than the
138 # string
139 $str =~ /[a-zA-Z]/s
140 )
141 ? $str
142 : terseDumper($str)
143 }
144  
145 86 ▶our $show_details = $ENV{RUN_TESTS} ? 0 : 1;
Branch: 1 branch
BranchTrueFalseTotal
$ENV{'RUN_TESTS'} ? : 33 53 86
146  
147 344 ▶sub parameterized_show_coderef {
Subroutine parameterized_show_coderef: called CC=1 SCAR=4.3
Pod undocumented
148 344 my ($subprefix, $maybe_dummy_modifier) = @_;
149 5 ▶ sub {
Subroutine __ANON__: called CC=9 SCAR=40.7
150 5 my ($v, $show) = @_;
151 5 ▶ if ($show_details) {
Branch: 1 branch
BranchTrueFalseTotal
if ($FP::Show::show_details) { } 0 5 5
152 0 ▶ my $info = capture_stderr { DumpWithOP($v) };
Subroutine __ANON__: not called CC=1 SCAR=6.9
153 0 my @FILE = $info =~ m/\bFILE * = *("[^"]*"|\S+) *\n/g;
154 0 my @LINE = $info =~ m/\bLINE * = *(\d+) *\n/g; # col?..
155 0 my $location = do {
156 0 ▶ if (@FILE) {
Branch: 1 branch
BranchTrueFalseTotal
if (@FILE) { } 0 0 0
157 0 my $filestr = $FILE[-1];
158 0 ▶ if (@LINE) {
Branch: 1 branch
BranchTrueFalseTotal
if (@LINE) { } 0 0 0
159 0 my $line = $LINE[0];
160 0 "at $filestr line $line"
161 } else {
162 0 "at $filestr (line unknown)"
163 }
164 } else {
165 0 "(no location found)"
166 }
167 };
168  
169 my ($name, $maybe_prototype)
170 0 ▶ = eval { require Sub::Util; 1 }
Branch: 1 branch
BranchTrueFalseTotal
eval { do { require Sub::Util; 1 } } ? : 0 0 0
171 ? (Sub::Util::subname($v), Sub::Util::prototype($v))
172 : ("(for name, install Sub::Util)", undef);
173  
174 0 ▶ my $prototypestr
Branch: 1 branch
BranchTrueFalseTotal
defined $maybe_prototype ? : 0 0 0
175 = defined $maybe_prototype ? "($maybe_prototype) " : "";
176  
177 0 my $maybe_docstring = do {
178 0 require FP::Docstring;
179 0 FP::Docstring::docstring($v)
180 };
181 0 ▶ my $docstr
Branch: 1 branch
BranchTrueFalseTotal
defined $maybe_docstring ? : 0 0 0
182 = defined($maybe_docstring)
183 ? "; __ " . show($maybe_docstring)
184 : "";
185  
186 0 my $dummystr = "DUMMY: $name $location";
187 0 ▶ if (defined($maybe_dummy_modifier)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $maybe_dummy_modifier) 0 0 0
188 0 $dummystr = $maybe_dummy_modifier->($dummystr);
189 }
190 0 $subprefix . $prototypestr . "{ " . show($dummystr) . "$docstr }"
191 } else {
192 5 my $dummystr = "DUMMY";
193 5 ▶ if (defined($maybe_dummy_modifier)) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined $maybe_dummy_modifier) 0 5 5
194 0 $dummystr = $maybe_dummy_modifier->($dummystr);
195 }
196 5 $subprefix . "{ " . show($dummystr) . " }"
197 }
198 }
199 344 }
200  
201 our $primitive_show = +{
202  
203 # these return string or (string, bool) where the bool indicates
204 # the string already contains blessing
205 31 ▶ ARRAY => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
206 31 my ($v, $show) = @_;
207 31 "[" . join(", ", map { &$show($_) } @$v) . "]";
208 },
209 4 ▶ HASH => sub {
Subroutine __ANON__: called CC=1 SCAR=0.0
210 4 my ($v, $show) = @_;
211 "+{"
212 . join(", ",
213 4 map { keyshow($_) . " => " . &$show($$v{$_}) } sort keys %$v)
214 . "}";
215 },
216 0 ▶ REF => sub { # references to references
Subroutine __ANON__: not called CC=1 SCAR=6.9
217 0 my ($v, $show) = @_;
218 0 "\\(" . &$show($$v) . ")"
219 },
220 0 ▶ GLOB => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
221 0 my ($v, $show) = @_;
222 0 (terseDumper($v), 1)
223 },
224 0 ▶ SCALAR => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
225 0 my ($v, $show) = @_;
226 0 (terseDumper($v), 1)
227 },
228 CODE => parameterized_show_coderef("sub "),
229  
230 # Don't really have any sensible serialization for these either,
231 # but at least prevent them from hitting Data::Dumper which issues
232 # warnings and returns invalid syntax in XS mode and gives plain
233 # exceptions in useperl mode:
234 1 ▶ IO => sub {
Subroutine __ANON__: called CC=2 SCAR=7.1
235 1 my ($v, $show) = @_;
236 1 ▶ my $fileno = fileno($v) // "UNKNOWN";
Condition50%1/2
fileno $v // "UNKNOWN"
l!l
10
MC/DC0%0/1
fileno $v // "UNKNOWN"
fileno $v
Truth table50%1/2
A
A= fileno $v
Aresult
11
00
237 1 "IO($fileno)"
238 },
239 0 ▶ LVALUE => sub {
Subroutine __ANON__: not called CC=1 SCAR=6.9
240 0 my ($v, $show) = @_;
241 0 "LVALUE(UNKNOWN)"
242 },
243 86 };
244  
245 214 ▶sub show {
Subroutine show: called CC=8 SCAR=21.7
Pod undocumented
246 214 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 214 0 214
247 214 my ($v) = @_;
248 214 ▶ if (defined blessed($v)) {
Branch: 2 branches
BranchTrueFalseTotal
if (defined builtin::blessed($v)) { } 38 176 214
elsif (length(my $r = ref $v)) { } 35 141 176
249 38 ▶ if (my $m = $v->can("FP_Show_show")) {
Branch: 2 branches
BranchTrueFalseTotal
if (my $m = $v->can('FP_Show_show')) { } 36 2 38
elsif ($m = $$FP::Show::primitive_show{builtin::reftype($v)}) { } 2 0 2
250 36 (&$m($v, \&show))[0]
251 } elsif ($m = $$primitive_show{ reftype $v}) {
252  
253 # blessed basic type
254 2 my ($str, $includes_blessing) = &$m($v, \&show);
255 2 ▶ $includes_blessing ? $str : "bless($str, " . &show(ref($v)) . ")"
Branch: 1 branch
BranchTrueFalseTotal
$includes_blessing ? : 0 2 2
256 } else {
257 0 terseDumper($v)
258 }
259 } elsif (length(my $r = ref $v)) {
260 35 ▶ if (my $m = $$primitive_show{$r}) {
Branch: 1 branch
BranchTrueFalseTotal
if (my $m = $FP::Show::primitive_show->{$r}) { } 35 0 35
261 35 (&$m($v, \&show))[0]
262 } else {
263 0 terseDumper($v)
264 }
265 } else {
266 141 terseDumper($v)
267 }
268 }
269  
270 0 ▶sub show_many {
Subroutine show_many: not called CC=1 SCAR=6.9
Pod undocumented
271 0 join(", ", map { show $_ } @_)
272 }
273  
274 86 1
« .htmlgen/gen ↑ Summary lib/FP/Trie.pm »