NAME
CGI::Carp::DebugScreen - provides a decent debug screen for Web applications
SYNOPSIS
use Carp;
use CGI::Carp::DebugScreen (
debug => $ENV{Debug},
engine => 'HTML::Template',
lines => 5,
modules => 1,
environment => 1,
overload => 1,
raw_error => 0,
);
croak "let's see";
DESCRIPTION
CGI::Carp qw/fatalsToBrowser/ is very useful for debugging. But the error screen it provides is a bit too plain; something you don't want to see, and you don't want your boss and colleagues and users to see. You might know CGI::Carp has a wonderful set_message() function but, hey, you don't want to repeat yourself, right?
Hence this module.
This module calls CGI::Carp qw/fatalsToBrowser/ and set_message() function internally. If something dies or croaks, this confesses stack traces, included modules (optional), environmental variables (optional, too) in a more decent way.
When you finish debugging, set debug option to false (via some environmental variable, for example). Then, more limited, less informative error screen appears when dies or croaks. If something goes wrong and your users might see the screen, they only know something has happened. They'll never know where your modules are and they'll never see the awkward 500 Internal Server Error -- hopefully.
You can, and are suggested to, customize both debug and error screens, and some style settings, in harmony with your application.
Enjoy.
OPTIONS
use CGI::Carp::DebugScreen (
debug => 1,
engine => 'HTML::Template',
lines => 5,
modules => 1,
environment => 1,
raw_error => 0,
overload => 1,
debug_template => $DebugTemplate,
error_template => $ErrorTemplate,
style => $Style,
);
debug (or d)
If set true, debug screen appears; if false, error screen does. The default value is 1. Setting some environmental variable here is a good idea.
engine (or e)
Sets the name of a view subclass. Default value is 'DefaultView', which uses no template engines. 'HTML::Template' and 'TT' are also available.
lines (or l)
Sets the number of lines shown before and after the traced line. The default value is 3.
modules (or m / mod)
If set true, debug screen shows a list of included modules. The default value is undef.
environment (or env)
If set true, debug screen shows a table of environmental variables. The default value is undef.
raw_error (or raw)
If set true, debug screen shows a raw error (CGI::Carp::confessed) message. The default value is undef.
ignore_overload (or overload)
If set true, watchlist dumper (CGI::Carp::DebugScreen::Dumper) ignores overloading of the objects and pokes into further. The default value is undef.
debug_template (or dt)
error_template (or et)
style (or s)
Overwrite the default templates and style if defined. But you may want to set these templates through correspondent methods.
PACKAGE METHODS
debug
show_modules
show_environment
show_raw_error
ignore_overload
set_debug_template
set_error_template
set_style
Do the same as the correspondent options. e.g.
CGI::Carp::DebugScreen->debug(1); # debug screen appears
add_watchlist
CGI::Carp::DebugScreen->add_watchlist( name => $ref );
If set, the module dumps the contents of the references while outputting the debug screen.
TODO
Encoding support (though CGI::Carp qw/fatalsToBrowser/ sends no charset header). And some more tests. Any ideas?
SEE ALSO
CGI::Carp, CGI::Application::Plugin::DebugScreen, Sledge::Plugin::DebugScreen
ACKNOWLEDGMENT
The concept, debug screen template and style are based on several Japanese hackers' blog articles. You might not be able to read Japanese pages but I thank:
- tokuhirom at http://tokuhirom.dnsalias.org/~tokuhirom/tokulog/
- nipotan at http://blog.livedoor.jp/nipotan/
- nekokak at http://www.border.jp/nekokak/blog/
-
CGI::Application::Plugin::DebugScreen articles 1, 2, 3, 4
AUTHOR
Kenichi Ishigaki, <ishigaki@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2005-2006 by Kenichi Ishigaki
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.