.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16)
.\"
.\" 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 "Debug::Client 3pm"
.TH Debug::Client 3pm "2012-04-09" "perl v5.14.2" "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"
Debug::Client \- debugger client side code for Padre, The Perl IDE.
.SH "VERSION"
.IX Header "VERSION"
This document describes Debug::Client version 0.20
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 3
\&  use Debug::Client;
\&  my $debugger = Debug::Client\->new(host => $host, port => $port);
\&  $debugger\->listener;
.Ve
.PP
Where \f(CW$host\fR is the host-name to be used by the script under test (\s-1SUT\s0)
to access the machine where Debug::Client runs. If they are on the same machine
this should be \f(CW\*(C`localhost\*(C'\fR.
\&\f(CW$port\fR can be any port number where the Debug::Client could listen.
.PP
This is the point where the external \s-1SUT\s0 needs to be launched 
by first setting
.PP
.Vb 1
\&  $ENV{PERLDB_OPTS} = "RemotePort=$host:$port"
.Ve
.PP
then running
.PP
.Vb 1
\&  perl \-d script
.Ve
.PP
Once the script under test was launched we can call the following:
.PP
.Vb 1
\&  my $out = $debugger\->get;
\&
\&  $out = $debugger\->step_in;
\&
\&  $out = $debugger\->step_over;
\&
\&
\&  my ($prompt, $module, $file, $row, $content) = $debugger\->step_in;
\&  my ($module, $file, $row, $content, $return_value) = $debugger\->step_out;
\&  my $value = $debugger\->get_value(\*(Aq$x\*(Aq);
\&
\&  $debugger\->run();         # run till end of breakpoint or watch
\&  $debugger\->run( 42 );     # run till line 42  (c in the debugger)
\&  $debugger\->run( \*(Aqfoo\*(Aq );  # run till beginning of sub
\&
\&  $debugger\->execute_code( \*(Aq$answer = 42\*(Aq );
\&
\&  $debugger\->execute_code( \*(Aq@name = qw(foo bar)\*(Aq );
\&
\&  my $value = $debugger\->get_value(\*(Aq@name\*(Aq);  $value is the dumped data?
\&
\&  $debugger\->execute_code( \*(Aq%phone_book = (foo => 123, bar => 456)\*(Aq );
\&
\&  my $value = $debugger\->get_value(\*(Aq%phone_book\*(Aq);  $value is the dumped data?
\&  
\&  
\&  $debugger\->set_breakpoint( "file", 23 ); # set breakpoint on file, line
\&
\&  $debugger\->get_stack_trace
.Ve
.SS "Example"
.IX Subsection "Example"
.Vb 2
\&  my $script = \*(Aqscript_to_debug.pl\*(Aq;
\&  my @args   = (\*(Aqparam\*(Aq, \*(Aqparam\*(Aq);
\&  
\&  my $perl = $^X; # the perl might be a different perl
\&  my $host = \*(Aqlocalhost\*(Aq;
\&  my $port = 24642;
\&  my $pid = fork();
\&  die if not defined $pid;
\&  
\&  if (not $pid) {
\&        local $ENV{PERLDB_OPTS} = "RemotePort=$host:$port"
\&        exec("$perl \-d $script @args");
\&  }
\&  
\&  
\&  require Debug::Client;
\&  my $debugger = Debug::Client\->new(
\&    host => $host,
\&    port => $port,
\&  );
\&  $debugger\->listener;
\&  my $out = $debugger\->get;
\&  $out = $debugger\->step_in;
\&  # ...
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The prime use of this module is to provide debugger functionality for Padre 0.94+,
.PP
This module should be Perl 5.16.0 ready.
.SH "METHODS"
.IX Header "METHODS"
.IP "new" 4
.IX Item "new"
The constructor can get two parameters: host and port.
.Sp
.Vb 1
\&  my $debugger = Debug::Client\->new;
\&
\&  my $debugger = Debug::Client\->new(host => \*(Aqremote.host.com\*(Aq, port => 24642);
.Ve
.Sp
Immediately after the object creation one needs to call
.Sp
.Vb 1
\&  $debugger\->listener;
.Ve
.Sp
\&\s-1TODO:\s0 Is there any reason to separate the two?
.IP "listener" 4
.IX Item "listener"
listener/hearken To listen attentively; give heed. See \f(CW\*(C`BUGS AND LIMITATIONS\*(C'\fR
.Sp
See \f(CW\*(C`new\*(C'\fR
.Sp
.Vb 1
\& $debugger\->listener
.Ve
.IP "buffer" 4
.IX Item "buffer"
Returns the content of the buffer since the last command
.Sp
.Vb 1
\&  $debugger\->buffer;
.Ve
.IP "quit" 4
.IX Item "quit"
.Vb 1
\& $debugger\->quit();
.Ve
.IP "show_line" 4
.IX Item "show_line"
\&. (dot)
.Sp
Return the internal debugger pointer to the line last executed, and print out that line.
.Sp
.Vb 1
\& $debugger\->show_line();
.Ve
.IP "get_lineinfo" 4
.IX Item "get_lineinfo"
Return the internal debugger pointer to the line last executed, 
and generate file-name and row for where are we now. 
trying to use perl5db line-info in naff way,
.Sp
.Vb 1
\& $debugger\->get_lineinfo();
.Ve
.Sp
Then use the following as and when.
.Sp
.Vb 2
\& $debugger\->filename;
\& $debugger\->row;
.Ve
.Sp
to get filename and row for ide due to changes in perl5db v1.35 see perl5156delta
.IP "show_view" 4
.IX Item "show_view"
v [line]
.Sp
View a few lines of code around the current line.
.Sp
.Vb 1
\& $debugger\->show_view();
.Ve
.IP "step_in" 4
.IX Item "step_in"
s [expr]
.Sp
Single step. 
Executes until the beginning of another statement, descending into subroutine calls. 
If an expression is supplied that includes function calls, it too will be single-stepped.
.Sp
.Vb 1
\& $debugger\->step_in();
.Ve
.Sp
Expressions not supported.
.IP "step_over" 4
.IX Item "step_over"
.Vb 1
\& $debugger\->step_over();
.Ve
.IP "step_out" 4
.IX Item "step_out"
.Vb 1
\& my ($prompt, $module, $file, $row, $content, $return_value) = $debugger\->step_out();
.Ve
.Sp
Where \f(CW$prompt\fR is just a number, probably useless
.Sp
\&\f(CW$return_value\fR  will be undef if the function was called in \s-1VOID\s0 context
.Sp
It will hold a scalar value if called in \s-1SCALAR\s0 context
.Sp
It will hold a reference to an array if called in \s-1LIST\s0 context.
.Sp
\&\s-1TODO:\s0 check what happens when the return value is a reference to a complex data structure
or when some of the elements of the returned array are themselves references
.IP "get_stack_trace" 4
.IX Item "get_stack_trace"
Sends the stack trace command \f(CW\*(C`T\*(C'\fR to the remote debugger
and returns it as a string if called in scalar context.
Returns the prompt number and the stack trace string
when called in array context.
.IP "toggle_trace" 4
.IX Item "toggle_trace"
Sends the stack trace command \f(CW\*(C`t\*(C'\fR Toggle trace mode.
.Sp
.Vb 1
\& $debugger\->toggle_trace();
.Ve
.IP "list_subroutine_names" 4
.IX Item "list_subroutine_names"
Sends the stack trace command \f(CW\*(C`S\*(C'\fR [[!]pattern] 
List subroutine names [not] matching pattern.
.IP "run" 4
.IX Item "run"
.Vb 1
\&  $debugger\->run;
.Ve
.Sp
Will run till the next breakpoint or watch or the end of
the script. (Like pressing c in the debugger).
.Sp
.Vb 1
\&  $debugger\->run($param)
.Ve
.IP "set_breakpoint" 4
.IX Item "set_breakpoint"
.Vb 1
\& $debugger\->set_breakpoint($file, $line, $condition);
.Ve
.Sp
\&\fI\f(CI$condition\fI is not currently used\fR
.IP "remove_breakpoint" 4
.IX Item "remove_breakpoint"
.Vb 1
\& $debugger\->remove_breakpoint( $self, $file, $line );
.Ve
.IP "show_breakpoints" 4
.IX Item "show_breakpoints"
The data as (L) prints in the command line debugger.
.Sp
.Vb 1
\& $debugger\->show_breakpoints();
.Ve
.IP "get_value" 4
.IX Item "get_value"
.Vb 1
\& my $value = $debugger\->get_value($x);
.Ve
.Sp
If \f(CW$x\fR is a scalar value, \f(CW$value\fR will contain that value.
If it is a reference to a \s-1ARRAY\s0 or \s-1HASH\s0 then \f(CW$value\fR should be the
value of that reference?
.IP "get_p_exp" 4
.IX Item "get_p_exp"
p expr
.Sp
Same as print {$DB::OUT} expr in the current package. 
In particular, because this is just Perl's own print function, 
this means that nested data structures and objects are not dumped, 
unlike with the x command.
.Sp
The \s-1DB::OUT\s0 filehandle is opened to /dev/tty, 
regardless of where \s-1STDOUT\s0 may be redirected to.
From perldebug, but defaulted to y 0
.Sp
.Vb 1
\&  $debugger\->get_p_exp();
.Ve
.IP "get_y_zero" 4
.IX Item "get_y_zero"
From perldebug, but defaulted to y 0
.Sp
.Vb 1
\& y [level [vars]]
.Ve
.Sp
Display all (or some) lexical variables (mnemonic: my variables) in the current 
scope or level scopes higher. You can limit the variables that you see with vars 
which works exactly as it does for the V and X commands. Requires the PadWalker 
module version 0.08 or higher; will warn if this isn't installed. 
Output is pretty-printed in the same style as for V and the format is controlled by the same options.
.Sp
.Vb 1
\&  $debugger\->get_y_zero();
.Ve
.IP "get_v_vars" 4
.IX Item "get_v_vars"
V [pkg [vars]]
.Sp
Display all (or some) variables in package (defaulting to main ) 
using a data pretty-printer (hashes show their keys and values so you see what's what, 
control characters are made printable, etc.). 
Make sure you don't put the type specifier (like $ ) there, just the symbol names, like this:
.Sp
.Vb 1
\& $debugger\->get_v_vars(regex);
.Ve
.IP "get_x_vars" 4
.IX Item "get_x_vars"
X [vars] Same as V currentpackage [vars]
.Sp
.Vb 1
\& $debugger\->get_x_vars(regex);
.Ve
.IP "get_h_var" 4
.IX Item "get_h_var"
Enter h or `h h' for help,
For more help, type h cmd_letter, optional var
.Sp
.Vb 1
\& $debugger\->get_h_var();
.Ve
.IP "set_option" 4
.IX Item "set_option"
o booloption ...
.Sp
Set each listed Boolean option to the value 1 .
o anyoption? ...
.Sp
Print out the value of one or more options.
o option=value ...
.Sp
Set the value of one or more options. If the value has internal white-space, 
it should be quoted. For example, you could set o pager=\*(L"less \-MQeicsNfr\*(R" to 
call less with those specific options. You may use either single or double quotes, 
but if you do, you must escape any embedded instances of same sort of quote you began with, 
as well as any escaping any escapes that immediately precede that quote but 
which are not meant to escape the quote itself. In other words, you follow 
single-quoting rules irrespective of the quote; eg: o option='this isn\e't bad' or o option=\*(L"She said, \e\*(R"Isn't it?\e"" .
.Sp
For historical reasons, the =value is optional, but defaults to 1 only where 
it is safe to do so\*(--that is, mostly for Boolean options. 
It is always better to assign a specific value using = . The option can be abbreviated, 
but for clarity probably should not be. Several options can be set together. 
See Configurable Options for a list of these.
.Sp
.Vb 1
\& $debugger\->set_option();
.Ve
.IP "get_options" 4
.IX Item "get_options"
o
.Sp
Display all options.
.Sp
.Vb 1
\& $debugger\->get_options();
.Ve
.IP "get" 4
.IX Item "get"
Actually I think this is an internal method....
.Sp
In \s-1SCALAR\s0 context will return all the buffer collected since the last command.
.Sp
In \s-1LIST\s0 context will return ($prompt, \f(CW$module\fR, \f(CW$file\fR, \f(CW$row\fR, \f(CW$content\fR)
Where \f(CW$prompt\fR is the what the standard debugger uses for prompt. Probably not too
interesting.
\&\f(CW$file\fR and \f(CW$row\fR describe the location of the next instructions.
\&\f(CW$content\fR is the actual line \- this is probably not too interesting as it is 
in the editor. \f(CW$module\fR is just the name of the module in which the current execution is.
.IP "filename" 4
.IX Item "filename"
.Vb 1
\& $debugger\->filename();
.Ve
.IP "row" 4
.IX Item "row"
.Vb 1
\& $debugger\->row();
.Ve
.IP "module" 4
.IX Item "module"
.Vb 1
\& $debugger\->module();
.Ve
.SS "Internal Methods"
.IX Subsection "Internal Methods"
.IP "\(bu" 4
_get
.IP "\(bu" 4
_logger
.IP "\(bu" 4
_process_line
.IP "\(bu" 4
_prompt
.IP "\(bu" 4
_send
.IP "\(bu" 4
_send_get
.SH "BUGS AND LIMITATIONS"
.IX Header "BUGS AND LIMITATIONS"
Warning if you use List request you may get spurious results.
.PP
When using against perl5db.pl v1.35 list mode gives an undef response, also leading single quote now correct. 
Tests are skipped for list mode against v1.35 now.
.PP
Debug::Client 0.12 tests are failing, due to changes in perl debugger, 
when using perl5db.pl v1.34
.PP
Debug::Client 0.13_01 skips added to failing tests.
.PP
.Vb 1
\& c [line|sub]
.Ve
.PP
Continue, optionally inserting a one-time-only breakpoint at the specified line or subroutine.
.PP
.Vb 1
\& c is now ignoring options [line|sub]
.Ve
.PP
and just performing c on it's own
.PP
\&\fIWarning sub listen has bean deprecated\fR
.PP
Has bean deprecated since 0.13_04 and all future versions starting with v0.14
.PP
Perl::Critic Error Subroutine name is a homonym for built-in function
.PP
Use \f(CW$debugger\fR\->listener instead
.SH "AUTHORS"
.IX Header "AUTHORS"
Kevin Dawson <bowtie@cpan.org>
.PP
Gabor Szabo <gabor@szabgab.com>
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
Breno G. de Oliveira <garu at cpan.org>
.PP
Ahmad M. Zawawi <ahmad.zawawi@gmail.com>
.PP
Mark Gardner <mjgardner@cpan.org>
.PP
Wolfram Humann <whumann@cpan.org>
.SH "COPYRIGHT"
.IX Header "COPYRIGHT"
Copyright 2008\-2012 Gabor Szabo/Kevin Dawson
.SH "LICENSE"
.IX Header "LICENSE"
This program is free software; you can redistribute it and/or
modify it under the same terms as Perl 5 itself.
.SH "WARRANTY"
.IX Header "WARRANTY"
There is no warranty whatsoever.
If you lose data or your hair because of this program,
that's your problem.
.SH "CREDITS and THANKS"
.IX Header "CREDITS and THANKS"
Originally started out from the remote\-port.pl script from 
Pro Perl Debugging written by Richard Foley.
.SH "See Also"
.IX Header "See Also"
GRID::Machine::remotedebugtut
.PP
Devel::ebug
.PP
Devel::Trepan