.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.05)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.ie \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    nr % 0
.    rr F
.\}
.el \{\
.    de IX
..
.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "CGI::Inspect 3"
.TH CGI::Inspect 3 "2009-06-26" "perl v5.10.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
CGI::Inspect \- Inspect and debug CGI apps with an in\-browser UI
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use CGI::Inspect; # This exports inspect()
\&
\&  print "Content\-type: text/html\en\en";
\&
\&  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!";
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This class is a drop-in web based inspector for plain \s-1CGI\s0 (or CGI-based)
applications. Include the library, and then call \fIinspect()\fR. In your server
error logs you'll see something like \*(L"Please connect to localhost:8080\*(R". When
you do, you'll be greeted with an inspection \s-1UI\s0 which includes a stack trace,
\&\s-1REPL\s0, and other goodies.
.PP
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).
.SH "EXPORTED SUBS"
.IX Header "EXPORTED SUBS"
.SS "\fIinspect()\fP"
.IX Subsection "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:
.PP
.Vb 1
\&  inspect( port => 12345 );
.Ve
.PP
Another useful parameter is plugins. The default is:
.PP
.Vb 1
\&    plugins => [qw( BasicLook Exit REPL CallStack )]
.Ve
.SH "PLUGINS"
.IX Header "PLUGINS"
CGI::Inspect comes with a few plugins by default:
.IP "\(bu" 4
\&\s-1REPL\s0 \- A simple Read-Eval-Print prompt
.IP "\(bu" 4
StackTrace \- A pretty stack trace (with lexical editing!)
.IP "\(bu" 4
Exit \- Stop inspecting
.SS "Creating Plugins"
.IX Subsection "Creating Plugins"
Plugins are easy to create! They are really just subroutines that return a
string for what they want printed. All of the built-in plugins actuall inherti
from CGI::Inspect::Plugin, which just provides some convenience methods. The
main CGI::Inspect module will create an instance of your plugin with
Plugin\->new, and then will execute it with \f(CW$plugin\fR\->process.
.PP
Plugins can, however, make use of Continuity, including utilizing callbacks.
Here is the complete source to the 'Exit' plugin, as a fairly simple example.
.PP
.Vb 1
\&  package CGI::Inspect::Plugin::Exit;
\&
\&  use strict;
\&  use base \*(AqCGI::Inspect::Plugin\*(Aq;
\&
\&  sub process {
\&    my ($self) = @_;
\&    my $exit_link = $self\->request\->callback_link(
\&      Exit => sub {
\&        $self\->manager\->{do_exit} = 1;
\&      }
\&    );
\&    my $output = qq{
\&      <div class=dialog title="Exit">
\&        $exit_link
\&      </div>
\&    };
\&    return $output;
\&  }
\&
\&  1;
.Ve
.PP
For now, read the source of the default plugins for further ideas. And of
course email the author if you have any questions or ideas!
.SH "METHODS"
.IX Header "METHODS"
These methods are all internal. All you have to do is call \fIinspect()\fR.
.SS "CGI::Inspect\->\fInew()\fP"
.IX Subsection "CGI::Inspect->new()"
Create a new monitor object.
.ie n .SS "$self\->start_inspecting"
.el .SS "\f(CW$self\fP\->start_inspecting"
.IX Subsection "$self->start_inspecting"
Load plugins and start inspecting!
.ie n .SS "$self\->start_server"
.el .SS "\f(CW$self\fP\->start_server"
.IX Subsection "$self->start_server"
Initialize the Continuity server, and begin the run loop.
.ie n .SS "$self\->display"
.el .SS "\f(CW$self\fP\->display"
.IX Subsection "$self->display"
Display the current page, based on \f(CW$self\fR\->{content}
.ie n .SS "$self\->request"
.el .SS "\f(CW$self\fP\->request"
.IX Subsection "$self->request"
Returns the current request obj
.ie n .SS "$self\->load_plugins"
.el .SS "\f(CW$self\fP\->load_plugins"
.IX Subsection "$self->load_plugins"
Load all of our plugins.
.ie n .SS "$self\->main"
.el .SS "\f(CW$self\fP\->main"
.IX Subsection "$self->main"
This is executed as the entrypoint for inspector sessions.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Carp::REPL
.SH "AUTHOR"
.IX Header "AUTHOR"
.Vb 1
\&  Brock Wilcox <awwaiid@thelackthereof.org> \- http://thelackthereof.org/
.Ve
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
.Vb 3
\&  Copyright (c) 2008\-2009 Brock Wilcox <awwaiid@thelackthereof.org>. All rights
\&  reserved.  This program is free software; you can redistribute it and/or
\&  modify it under the same terms as Perl itself.
.Ve