| 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
| |||||||||||||||||||
| 79 | 7 | my ($fn_or_glob) = @_; | |||||||||||||||||
| 80 | 7 | ▶ | my $fn | ||||||||||||||||
|
Branch: 2 branches
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 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
| |||||||||||||||||||
| 107 | 0 | ▶ | warn "for docstring support, install B::Deparse" unless $warned; | ||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||
| 108 | 0 | $warned = 1; | |||||||||||||||||
| 109 | } | ||||||||||||||||||
| 110 | undef | ||||||||||||||||||
| 111 | 0 | } | |||||||||||||||||
| 112 | } | ||||||||||||||||||
| 113 | |||||||||||||||||||
| 114 | 86 | 1 | |||||||||||||||||