| 1 | # | ||||||||||
| 2 | # Copyright (c) 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::Carp - report to immediate caller | ||||||||||
| 13 | |||||||||||
| 14 | =head1 SYNOPSIS | ||||||||||
| 15 | |||||||||||
| 16 | 1 | ▶ | use FP::Carp; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 17 | |||||||||||
| 18 | # Like `croak` but don't skip any parent call frames: | ||||||||||
| 19 | 2 | ▶ | sub foo { | ||||||||
|
Subroutine
foo: called CC=2 SCAR=6.9
| |||||||||||
| 20 | 2 | ▶ | @_ == 1 or fp_croak "I need 1 argument"; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 21 | } | ||||||||||
| 22 | |||||||||||
| 23 | # Easier if you just want to report an error about the number of | ||||||||||
| 24 | # arguments passed to the current subroutine: | ||||||||||
| 25 | 1 | ▶ | sub bar { | ||||||||
|
Subroutine
bar: called CC=2 SCAR=7.6
| |||||||||||
| 26 | 1 | ▶ | @_ == 2 or fp_croak_arity 2; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 27 | } | ||||||||||
| 28 | |||||||||||
| 29 | 2 | ▶ | sub test { | ||||||||
|
Subroutine
test: called CC=1 SCAR=0.0
| |||||||||||
| 30 | 2 | foo(@_); | |||||||||
| 31 | 1 | bar(@_); | |||||||||
| 32 | } | ||||||||||
| 33 | 2 | ▶ | sub try(&) { | ||||||||
|
Subroutine
try: called CC=2 SCAR=7.1
| |||||||||||
| 34 | 0 | ▶ | eval { &{$_[0]}; 1 } && return; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 35 | 2 | my $e= $@; | |||||||||
| 36 | 2 | $e=~ s/\n.*//s; | |||||||||
| 37 | 2 | $e=~ s{\\}{/}sg; # convert windows to unix paths | |||||||||
| 38 | 2 | $e | |||||||||
| 39 | } | ||||||||||
| 40 | is try { test(10) }, 'bar: needs 2 arguments (got 1) at lib/FP/Carp.pm line 31'; | ||||||||||
| 41 | is try { test(10,11) }, 'I need 1 argument at lib/FP/Carp.pm line 30'; | ||||||||||
| 42 | |||||||||||
| 43 | # there is currently no equivalent to `carp`, or `confess` (use | ||||||||||
| 44 | # Devel::Confess instead?) | ||||||||||
| 45 | |||||||||||
| 46 | =head1 DESCRIPTION | ||||||||||
| 47 | |||||||||||
| 48 | L<Carp> skips call frames in the same package as the caller of `croak` | ||||||||||
| 49 | (or `carp` etc.), as well as those from matching some other cases like | ||||||||||
| 50 | parent classes. This works well when assuming that all the code that's | ||||||||||
| 51 | being skipped is correct, and the error has to do with the code | ||||||||||
| 52 | outside those scopes. This is also necessary when not using tail-call | ||||||||||
| 53 | optimization (as via goto \&sub, or L<Sub::Call::Tail>) to skip parent | ||||||||||
| 54 | calls in tail position. | ||||||||||
| 55 | |||||||||||
| 56 | But for cases like checking the number of arguments to the current | ||||||||||
| 57 | subroutine, this is not useful, as the error really is in the | ||||||||||
| 58 | immediate caller. And if using tail-call optimization, just reporting | ||||||||||
| 59 | the next frame is also correct in other cases when the current call is | ||||||||||
| 60 | in the caller's tail position. | ||||||||||
| 61 | |||||||||||
| 62 | This provides L<Carp> like subroutines for these cases--they go up | ||||||||||
| 63 | exactly one frame, no matter what. | ||||||||||
| 64 | |||||||||||
| 65 | Since there's no logic for skipping of call frames, this module is | ||||||||||
| 66 | simpler than L<Carp>. | ||||||||||
| 67 | |||||||||||
| 68 | |||||||||||
| 69 | =head1 SEE ALSO | ||||||||||
| 70 | |||||||||||
| 71 | L<Carp>, L<FP::Repl> | ||||||||||
| 72 | |||||||||||
| 73 | =head1 NOTE | ||||||||||
| 74 | |||||||||||
| 75 | This is alpha software! Read the status section in the package README | ||||||||||
| 76 | or on the L<website|http://functional-perl.org/>. | ||||||||||
| 77 | |||||||||||
| 78 | =cut | ||||||||||
| 79 | |||||||||||
| 80 | package FP::Carp; | ||||||||||
| 81 | 93 | ▶ | use strict; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 82 | 93 | ▶ | use warnings; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 83 | 93 | ▶ | use warnings FATAL => 'uninitialized'; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 84 | 93 | ▶ | use Exporter "import"; | ||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||
| 85 | |||||||||||
| 86 | 93 | our @EXPORT = qw(fp_croak fp_croak_arity); | |||||||||
| 87 | 93 | our @EXPORT_OK = qw(); | |||||||||
| 88 | 93 | our %EXPORT_TAGS = (all => [@EXPORT, @EXPORT_OK]); | |||||||||
| 89 | |||||||||||
| 90 | 10 | ▶ | sub fp_croak { | ||||||||
|
Subroutine
fp_croak: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||
| 91 | 10 | my $msg = join("", @_); | |||||||||
| 92 | |||||||||||
| 93 | 10 | my @f1 = caller(1); | |||||||||
| 94 | 10 | my $reportloc = "$f1[1] line $f1[2]"; | |||||||||
| 95 | 10 | die "$msg at $reportloc\n" | |||||||||
| 96 | } | ||||||||||
| 97 | |||||||||||
| 98 | 1 | ▶ | sub fp_croak_arity { | ||||||||
|
Subroutine
fp_croak_arity: called CC=4 SCAR=14.1
Pod
undocumented
| |||||||||||
| 99 | 1 | ▶ | @_ <= 1 or warn "fp_croak_arity: wrong number of arguments"; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 100 | 1 | my ($maybe_n) = @_; | |||||||||
| 101 | |||||||||||
| 102 | # maybe_n can be a range, or really any string. | ||||||||||
| 103 | |||||||||||
| 104 | 1 | my $msg = do { | |||||||||
| 105 | 1 | ▶ | if (defined $maybe_n) { | ||||||||
|
Branch: 1 branch
| |||||||||||
| 106 | 1 | ▶ | my $argumentS = $maybe_n eq "1" ? "argument" : "arguments"; | ||||||||
|
Branch: 1 branch
| |||||||||||
| 107 | 1 | "needs $maybe_n $argumentS" | |||||||||
| 108 | } else { | ||||||||||
| 109 | 0 | "wrong number of arguments" | |||||||||
| 110 | } | ||||||||||
| 111 | }; | ||||||||||
| 112 | 1 | my @f1; | |||||||||
| 113 | my $nargs1; | ||||||||||
| 114 | { | ||||||||||
| 115 | |||||||||||
| 116 | 1 | package DB; | |||||||||
| 117 | 1 | @f1 = caller(1); | |||||||||
| 118 | 1 | $nargs1 = @DB::args; | |||||||||
| 119 | } | ||||||||||
| 120 | 1 | my $subname = $f1[3]; | |||||||||
| 121 | 1 | $subname =~ s/^.*:://s; | |||||||||
| 122 | 1 | my $reportloc = "$f1[1] line $f1[2]"; | |||||||||
| 123 | 1 | die "$subname: $msg (got $nargs1) at $reportloc\n" | |||||||||
| 124 | } | ||||||||||
| 125 | |||||||||||
| 126 | 93 | 1 | |||||||||