view release on metacpan or  search on metacpan

lib/CGI/Inspect.pm  view on Meta::CPAN

package CGI::Inspect;

=head1 NAME

CGI::Inspect - Inspect and debug CGI apps with an in-browser UI

=head1 SYNOPSIS

  use CGI::Inspect; # This exports inspect()

  print "Content-type: text/html\n\n";

  my $food = "toast";

  for my $i (1..10) {
    print "$i cookies for me to eat...<br>";
    inspect() if $i == 5; # be sure to edit $toast :)
  }

  print "I also like $food!";

=head1 DESCRIPTION

This class is a drop-in web based inspector for plain CGI (or CGI-based)
applications. Include the library, and then call inspect(). In your server
error logs you'll see something like "Please connect to localhost:8080". When
you do, you'll be greeted with an inspection UI which includes a stack trace,
REPL, and other goodies.

To work it's magic this modules uses Continuity, Devel::LexAlias,
Devel::StackTrace::WithLexicals, and their prerequisites (such as PadWalker).
Remember that you can always install such things locally for debugging -- no
need to install them systemwide (in case you are afraid of the power that they
provide).

=cut

use strict;
use Continuity;
use Continuity::RequestCallbacks;
use base 'Exporter';
our @EXPORT = qw( inspect );
our @EXPORT_OK = qw( nodie );

our $VERSION = '0.5';

=head1 EXPORTED SUBS

=head2 inspect()

This starts the Continuity server and inspector on the configured port
(defaulting to 8080). You can pass it parameters which it will then pass on to
CGI::Inspect->new. The most useful one is probably port:

  inspect( port => 12345 );

Another useful parameter is plugins. The default is:

    plugins => [qw( BasicLook Exit REPL CallStack )]

=cut

sub inspect {
  print STDERR "Starting inspector...\n";
  require IO::Handle;
  STDERR->autoflush(1);
  STDOUT->autoflush(1);
  print "<script>window.open('http://localhost:8080/','cgi-inspect');</script>\n";
  my $self = CGI::Inspect->new(@_);
  $self->start_inspecting;
}

# This might be cool, but we'll disable it for now. I mean... because it doesn't work.
# sub import {
  # my $class = shift;
  # my $nodie = grep { $_ eq 'nodie' } @_;
  # $SIG{__DIE__} = \&CGI::Inspect::inspect unless $nodie;
  # $class->SUPER::import(@_);
# }


=head1 PLUGINS

CGI::Inspect comes with a few plugins by default:

=over 4

=item * L<REPL|CGI::Inspect::Plugin::REPL> - A simple Read-Eval-Print prompt

=item * L<StackTrace|CGI::Inspect::Plugin::StackTrace> - A pretty stack trace (with lexical editing!)