lib/FP/Docstring.pm

filter: Statementstmt 81.6% 40 / 49 Branchbran 45.0% 9 / 20 Conditioncond n/a MC/DCmcdc n/a Subroutinesub 80.0% 8 / 10 Podpod 0.0% 0 / 1 totaltotal 71.2% 57 / 80 CC 11 SCAR 23.6
CC
11
Cov
71%
docstring
18.2
foo
2.0
__ANON__
2.0
CRAP 10.6
« lib/Chj/time_this.pm ↑ Summary lib/Chj/IsPerl.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::Docstring
13  
14 =head1 SYNOPSIS
15  
16 1 ▶ use FP::Docstring; # imports `__` (which does nothing) and `docstring`
Subroutine BEGIN: called CC=1 SCAR=0.0
17  
18 0 ▶ sub foo {
Subroutine foo: not called CC=1 SCAR=6.9
19 0 __ "bars the foo out of the list";
20 0 my ($l) = @_;
21 0 ▶ $l->filter(sub{not $_[0] =~ /foo/})
Subroutine __ANON__: not called CC=1 SCAR=6.9
22 0 }
23  
24 is docstring(\&foo),
25 "bars the foo out of the list";
26  
27  
28 =head1 DESCRIPTION
29  
30 A docstring is a (short) string used to document subroutines that is
31 part of the code at runtime and hence retrievable at runtime,
32 e.g. from a debugger or L<FP::Repl>. It is currently also shown by
33 L<FP::Show> (it makes the display verbose, though, thus this might
34 change).
35  
36 =head1 BUGS
37  
38 Using single-quoted strings directly after C<__> is giving an "Bad
39 name after __'" error, because the Perl parser thinks of the single
40 quote as being a namespace delimiter. Put a space between the C<__>
41 and the string.
42  
43 The extraction process may erroneously find things that are not
44 docstrings, due to it doing ad-hoc string parsing of the deparsed
45 code. If a docstring declaration *is* used at the beginning of the sub
46 then it should be safely retrieved though.
47  
48 =head1 SEE ALSO
49  
50 L<Docstring (Wikipedia)|https://en.wikipedia.org/wiki/Docstring>
51  
52 L<FP::Repl>
53  
54 =cut
55  
56 package FP::Docstring;
57 86 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
58 86 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
59 86 ▶use warnings FATAL => 'uninitialized';
Subroutine BEGIN: called CC=1 SCAR=0.0
60 86 ▶use Exporter "import";
Subroutine BEGIN: called CC=1 SCAR=0.0
61  
62 86 our @EXPORT = qw(__ docstring);
63 86 our @EXPORT_OK = qw();
64 86 our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]);
65  
66 86 ▶use FP::Carp;
Subroutine BEGIN: called CC=1 SCAR=0.0
67  
68 # Exception: use prototype here? Really DSL. Point it out early.
69 9072 ▶sub __ ($) { } ## no critic
Subroutine __: called CC=1 SCAR=0.0
70  
71 # optimization would be to make it syntax...
72  
73 86 my %endquote = ('[' => ']', '(' => ')', '{' => '}');
74  
75 86 my $warned;
76  
77 7 ▶sub docstring {
Subroutine docstring: called CC=11 SCAR=29.0
Pod undocumented
78 7 ▶ @_ == 1 or fp_croak_arity 1;
Branch: 1 branch
BranchTrueFalseTotal
@_ == 1 or fp_croak_arity(1) 7 0 7
79 7 my ($fn_or_glob) = @_;
80 7 ▶ my $fn
Branch: 2 branches
BranchTrueFalseTotal
UNIVERSAL::isa($fn_or_glob, 'CODE') ? : 7 0 7
UNIVERSAL::isa(\$fn_or_glob, 'GLOB') ? : 0 0 0
81 = UNIVERSAL::isa($fn_or_glob, "CODE") ? $fn_or_glob
82 : UNIVERSAL::isa(\$fn_or_glob, "GLOB") ? \&$fn_or_glob
83 : die "not a coderef nor glob: $fn_or_glob";
84 7 ▶ if (eval { require B::Deparse; 1 }) {
Branch: 1 branch
BranchTrueFalseTotal
if (eval { do { require B::Deparse; 1 } }) { } 7 0 7
85 7 my $str = B::Deparse->new->coderef2text($fn);
86  
87 #warn "str='$str'";
88 7 ▶ if (my ($docstring) = $str =~ /\b__\('(.*?)'\);/s) {
Branch: 3 branches
BranchTrueFalseTotal
if (my($docstring) = $str =~ /\b__\('(.*?)'\);/s) { } 4 3 7
elsif (($docstring) = $str =~ /\b__\("(.*?)"\);/s) { } 1 2 3
elsif (() = $str =~ /\b__\(q(.)(.*)/s) { } 2 0 2
89 4 $docstring
90 } elsif (($docstring) = $str =~ /\b__\("(.*?)"\);/s) {
91 1 $docstring =~ s/\\n/\n/sg;
92 1 $docstring =~ s/\\\\/\\/sg;
93 1 $docstring =~ s/\\\$/\$/sg;
94 1 $docstring
95 } elsif (my ($quote, $docstring_and_rest) = $str =~ /\b__\(q(.)(.*)/s) {
96  
97 # sigh, really?
98 2 ▶ my $endquote = $endquote{$quote}
Branch: 1 branch
BranchTrueFalseTotal
my $endquote = $endquote{$quote} or die "don't know what quote this is: $quote" 2 0 2
99 or die "don't know what quote this is: $quote";
100 2 $docstring_and_rest =~ s/\Q$endquote\E.*//s;
101 2 $docstring_and_rest
102 } else {
103 undef
104 0 }
105 } else {
106 0 ▶ unless ($warned) {
Branch: 1 branch
BranchTrueFalseTotal
unless ($warned) 0 0 0
107 0 ▶ warn "for docstring support, install B::Deparse" unless $warned;
Branch: 1 branch
BranchTrueFalseTotal
unless $warned 0 0 0
108 0 $warned = 1;
109 }
110 undef
111 0 }
112 }
113  
114 86 1
« lib/Chj/time_this.pm ↑ Summary lib/Chj/IsPerl.pm »