NAME

CGI::Carp::DebugScreen - provides a decent debug screen for Web applications

SYNOPSIS

  use strict;
  use warnings;
  use Carp;
  use CGI::Carp::DebugScreen ( debug => $ENV{Debug} );
  use CGI;

  my $query = CGI->new;

  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, 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 with 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

Your code will look like this when you want to configure everything:

  use CGI::Carp::DebugScreen (
    debug          => 1,
    engine         => '+MyEngine',
    lines          => 5,
    modules        => 1,
    environment    => 1,
    raw_error      => 0,
    overload       => 1,
    debug_template => $DebugTemplate,
    error_template => $ErrorTemplate,
    style          => $Style,
  );

debug (or d)

If set to 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 base name of a view class. Default value is DefaultView, which uses no template engines. HTML::Template and TT are also available. As of 0.15, you can pass any class with a prepending + or any object with as_html method, which should take a hash of options and returns an HTML string. Your rendering class/object doesn't need to use all of the options naturally.

The options are:

version

version of this module.

debug

if true, debug_template should be used, otherwise, error_template.

debug_template, error_template, style

the ones you specified while loading (or via methods).

view_class

the actual class name of the view (i.e. renderer).

error_at, error_message

where and why your application died.

raw_error, show_raw_error

an unprocessed error message (from CGI::Carp), and a flag to use this.

stacktraces

array reference of hash references whose keys are message, caller, line, context (information on the lines around the traced line; array reference of hash references whose keys are no, line, hit).

modules

array reference of hash references whose keys are package and file.

environment

array reference of hash references whose keys are key and value.

watchlist

array reference of hash references whose keys are key and value (which may be an escaped scalar or an HTML table).

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 to true, debug screen shows a list of included modules. The default value is undef.

environment (or env)

If set to true, debug screen shows a table of environmental variables. The default value is undef.

raw_error (or raw)

If set to true, debug screen shows a raw error message from CGI::Carp::confess. The default value is undef.

ignore_overload (or overload)

If set to 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)

Override the default templates/style if defined. 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 (Tokuhiro Matsuno)

for original Sledge::Plugin::DebugScreen (http://tokuhirom.dnsalias.org/~tokuhirom/tokulog/2181.html, this site is gone now)

nipotan (Koichi Taniguchi)

for patches for Sledge::Plugin::DebugScreen (http://blog.livedoor.jp/nipotan/archives/50342811.html and http://blog.livedoor.jp/nipotan/archives/50342898.html)

nekokak (Atsushi Kobayashi)

for CGI::Application::Plugin::DebugScreen articles (http://www.border.jp/nekokak/blog/archives/2005/12/cgiappdebugscre.html, http://www.border.jp/nekokak/blog/archives/2005/12/cgiappdebugscre_1.html, http://www.border.jp/nekokak/blog/archives/2005/12/cgiappdebugscre_2.html, http://www.border.jp/nekokak/blog/archives/2005/12/cgiappdebugscre_3.html, all gone now)

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.

cpanm CGI::Carp::DebugScreen

perl -MCPAN -e shell
install CGI::Carp::DebugScreen