view release on metacpan or  search on metacpan

lib/CGI/Carp/WarningsToBrowser.pm  view on Meta::CPAN

package CGI::Carp::WarningsToBrowser;

our $VERSION = 0.02;

=pod

=head1 NAME

CGI::Carp::WarningsToBrowser - A version of L<CGI::Carp>'s warningsToBrowser()
that displays the warnings loudly and boldly

=head1 RATIONALE

The author feels that it's important to expose warnings as early as possible in
the software development lifecycle, preferably by the same developer who created
them, as part of the "L<shift left|https://devopedia.org/shift-left>" effort.
"Shift left" basically means that the earlier in the SDLC that a problem can be
found, the cheaper it is to fix it.

=head1 SYNOPSIS

Put this at the top of your CGI script (the earlier the better, otherwise some
warnings might not get captured):

 use CGI::Carp::WarningsToBrowser;

Warnings will now be displayed at the very top of the web page, rather than
hidden in HTML comments like L<CGI::Carp>'s version.  This is intended mainly
for dev and test environments, not for prod, so it's a good idea to use L<if>:

 use if $is_dev, 'CGI::Carp::WarningsToBrowser';

=head1 HANDLING ERRORS

This module does not handle fatal errors, because L<CGI::Carp> does an adequate
job at that task.

=head1 COMPATIBILITY

Javascript must be enabled on the browser side, otherwise the warnings will
appear at the very bottom of the document. (the warnings are actually output in
an C<END { }> block, and three lines of Javascript are used to move them to the
top of the HTML page)

=head1 AUTHOR

Dee Newcum <deenewcum@cpan.org>

=head1 CONTRIBUTING

Please use L<Github's issue tracker|https://github.com/DeeNewcum/CGI-Carp-WarningsToBrowser/issues>
to file both bugs and feature requests. Contributions to the project in form of
Github's pull requests are welcome.

=head1 LICENSE

This library is free software; you may redistribute it and/or modify it under
the same terms as Perl itself.

=cut

use strict;
use warnings;

use HTML::Entities 3.00 ();

our @WARNINGS;

sub import {
    # if we're under the debugger, don't interfere with the warnings