blib/lib/CGI/Carp/WarningsToBrowser.pm

filter: Statementstmt 100% 26 / 26 Branchbran 75.0% 6 / 8 Conditioncond 50.0% 3 / 6 MC/DCmcdc 25.0% 1 / 4 Subroutinesub 100% 7 / 7 Podpod n/a totaltotal 84.3% 43 / 51 CC 8 SCAR 12.8
CC
8
Cov
88%
import
5.0
_print_warnings
5.0
BEGIN
1.0
CRAP 3.6
↑ Summary
1 package CGI::Carp::WarningsToBrowser;
2  
3 5 our $VERSION = 0.02;
4  
5 =pod
6  
7 =head1 NAME
8  
9 CGI::Carp::WarningsToBrowser - A version of L<CGI::Carp>'s warningsToBrowser()
10 that displays the warnings loudly and boldly
11  
12 =head1 RATIONALE
13  
14 The author feels that it's important to expose warnings as early as possible in
15 the software development lifecycle, preferably by the same developer who created
16 them, as part of the "L<shift left|https://devopedia.org/shift-left>" effort.
17 "Shift left" basically means that the earlier in the SDLC that a problem can be
18 found, the cheaper it is to fix it.
19  
20 =head1 SYNOPSIS
21  
22 Put this at the top of your CGI script (the earlier the better, otherwise some
23 warnings might not get captured):
24  
25 use CGI::Carp::WarningsToBrowser;
26  
27 Warnings will now be displayed at the very top of the web page, rather than
28 hidden in HTML comments like L<CGI::Carp>'s version. This is intended mainly
29 for dev and test environments, not for prod, so it's a good idea to use L<if>:
30  
31 use if $is_dev, 'CGI::Carp::WarningsToBrowser';
32  
33 =head1 HANDLING ERRORS
34  
35 This module does not handle fatal errors, because L<CGI::Carp> does an adequate
36 job at that task.
37  
38 =head1 COMPATIBILITY
39  
40 Javascript must be enabled on the browser side, otherwise the warnings will
41 appear at the very bottom of the document. (the warnings are actually output in
42 an C<END { }> block, and three lines of Javascript are used to move them to the
43 top of the HTML page)
44  
45 =head1 AUTHOR
46  
47 Dee Newcum <deenewcum@cpan.org>
48  
49 =head1 CONTRIBUTING
50  
51 Please use L<Github's issue tracker|https://github.com/DeeNewcum/CGI-Carp-WarningsToBrowser/issues>
52 to file both bugs and feature requests. Contributions to the project in form of
53 Github's pull requests are welcome.
54  
55 =head1 LICENSE
56  
57 This library is free software; you may redistribute it and/or modify it under
58 the same terms as Perl itself.
59  
60 =cut
61  
62 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
63 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
64  
65 5 ▶use HTML::Entities 3.00 ();
Subroutine BEGIN: called CC=1 SCAR=0.0
66  
67 5 our @WARNINGS;
68  
69 5 ▶sub import {
Subroutine import: called CC=4 SCAR=16.1
70 # if we're under the debugger, don't interfere with the warnings
71 5 ▶ return if (exists $INC{'perl5db.pl'} && $DB::{single});
Branch: 1 branch
BranchTrueFalseTotal
if exists $INC{"perl5db.pl"} and $main::DB::{"single"} 0 5 5
Condition33%1/3
exists $INC{"perl5db.pl"} and $main::DB::{"single"}
!ll&&!rl&&r
500
MC/DC0%0/2
exists $INC{"perl5db.pl"} and $main::DB::{"single"}
exists $INC{"perl5db.pl"} $main::DB::{"single"}
Truth table33%1/3
A and B
A= exists $INC{"perl5db.pl"}B= $main::DB::{"single"}
ABresult
0X0
100
111
72 # if we're under perl -c, don't interfere with the warnings
73 5 ▶ return if ($^C);
Branch: 1 branch
BranchTrueFalseTotal
if $^C 0 5 5
74 5 $main::SIG{__WARN__} = \&_handle_warn;
75 }
76  
77  
78 3 ▶sub _handle_warn {
Subroutine _handle_warn: called CC=1 SCAR=0.0
79 3 push @WARNINGS, shift;
80 }
81  
82  
83 4 ▶END {
Subroutine END: called CC=1 SCAR=0.0
84 4 _print_warnings();
85 }
86  
87  
88 5 ▶sub _print_warnings {
Subroutine _print_warnings: called CC=5 SCAR=16.1
89 5 ▶ return unless (@WARNINGS);
Branch: 1 branch
BranchTrueFalseTotal
unless @CGI::Carp::WarningsToBrowser::WARNINGS 2 3 5
90 # TODO: Hopefully we have output a text/html document. Is there a way to
91 # detect this, and avoid printing on other kinds of documents (which could
92 # corrupt file downloads, for example)
93 # see -- Tie::StdHandle or Tie::Handle::Base
94  
95 # TODO: What do we do about encoding? Is there a way to auto-detect what
96 # kind of encoding was specified? Or should we just use
97 # Unicode::Diacritic::Strip (to strip diacritics) and/or Text::Unidecode (to
98 # output string-representations of non-ASCII Unicode characters)?
99 # see -- Tie::StdHandle or Tie::Handle::Base
100  
101 # In some situations, the HTTP response header won't have been output yet.
102 # Try to auto-detect this.
103 3 my $bytes_written = tell(STDOUT);
104 3 ▶ if (!defined($bytes_written) || $bytes_written <= 0) {
Branch: 1 branch
BranchTrueFalseTotal
if (not defined $bytes_written or $bytes_written <= 0) 1 2 3
Condition66%2/3
not defined $bytes_written or $bytes_written <= 0
l!l&&r!l&&!r
012
MC/DC50%1/2
not defined $bytes_written or $bytes_written <= 0
not defined $bytes_written $bytes_written <= 0
Truth table66%2/3
not(A) or B
A= not defined $bytes_writtenB= $bytes_written <= 0
ABresult
1X1
011
000
105 # The HTTP response header *probably* hasn't been output yet, so output
106 # one of our own.
107 # (though see https://perldoc.perl.org/functions/tell for caveats)
108  
109 # TODO: Do we want to output an encoding along with this?
110 1 print STDOUT "Status: 500\n";
111 1 print STDOUT "Content-type: text/html\n\n";
112 }
113  
114 # print the warning-header
115 3 print STDOUT <<'EOF';
116 <div id="CGI::Carp::WarningsToBrowser" style="background-color:#faa; border:1px solid #000; padding:0.3em; margin-bottom:1em">
117 <b>Perl warnings</b>
118 <pre style="font-size:85%">
119 EOF
120 3 foreach my $warning (@WARNINGS) {
121 3 print STDOUT HTML::Entities::encode_entities($warning);
122 }
123  
124 # print the warning-footer
125 3 print STDOUT <<'EOF';
126 </pre></div>
127 <!-- move the warnings <div> to the very top of the document -->
128 <script type="text/javascript">
129 var warningsToBrowser_pre = document.getElementById('CGI::Carp::WarningsToBrowser');
130 if (warningsToBrowser_pre) {
131 warningsToBrowser_pre.remove();
132 document.body.prepend(warningsToBrowser_pre);
133 }
134 </script>
135 EOF
136 }
137  
138 5 1;
↑ Summary