/ 
Debug-Client-0.13_09
River stage zero No dependents
/ Debug::Client

NAME

Debug::Client - client side code for perl debugger

SYNOPIS

use Debug::Client;
my $debugger = Debug::Client->new(host => $host, port => $port);
$debugger->listener;

Where $host is the host-name to be used by the script under test (SUT) to access the machine where Debug::Client runs. If they are on the same machine this should be localhost. $port can be any port number where the Debug::Client could listen.

This is the point where the external SUT needs to be launched by first setting

$ENV{PERLDB_OPTS} = "RemotePort=$host:$port"

then running

perl -d script

Once the script under test was launched we can call the following:

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('$x');

$debugger->run();         # run till end of breakpoint or watch
$debugger->run( 42 );     # run till line 42  (c in the debugger)
$debugger->run( 'foo' );  # run till beginning of sub

$debugger->execute_code( '$answer = 42' );

$debugger->execute_code( '@name = qw(foo bar)' );

my $value = $debugger->get_value('@name');  $value is the dumped data?

$debugger->execute_code( '%phone_book = (foo => 123, bar => 456)' );

my $value = $debugger->get_value('%phone_book');  $value is the dumped data?


$debugger->set_breakpoint( "file", 23 ); # set breakpoint on file, line

$debugger->get_stack_trace

Other planned methods:

$debugger->set_breakpoint( "file", 23, COND ); # set breakpoint on file, line, on condition
$debugger->set_breakpoint( "file", subname, [COND] )

$debugger->set_watch
$debugger->remove_watch
$debugger->remove_breakpoint


$debugger->watch_variable   (to make it easy to display values of variables)

example

  my $script = 'script_to_debug.pl';
  my @args   = ('param', 'param');
  
  my $perl = $^X; # the perl might be a different perl
  my $host = 'localhost';
  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;
  # ...

DESCRIPTION

new

The constructor can get two parameters: host and port.

my $debugger = Debug::Client->new;

my $debugger = Debug::Client->new(host => 'remote.hots.com', port => 24642);

Immediately after the object creation one needs to call

$debugger->listener;

TODO: Is there any reason to separate the two?

listen

Has bean deprecated in this version 0.13_04 and all future versions starting with v0.14

Perl::Critic Error Subroutine name is a homonym for built-in function

Use $debugger->listener instead

listener

listener/hearken To listen attentively; give heed.

See new

$debugger->listener

buffer

Returns the content of the buffer since the last command

$debugger->buffer;

quit

$debugger->quit();

show_line

.

Return the internal debugger pointer to the line last executed, and print out that line.

$debugger->show_line();

show_view

v [line]

View a few lines of code around the current line.

$debugger->show_view();

step_in

s [expr]

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.

$debugger->step_in();

Expressions not supported.

step_over

$debugger->step_over();

step_out

my ($prompt, $module, $file, $row, $content, $return_value) = $debugger->step_out();

Where $prompt is just a number, probably useless

$return_value will be undef if the function was called in VOID context

It will hold a scalar value if called in SCALAR context

It will hold a reference to an array if called in LIST context.

TODO: 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

get_stack_trace

Sends the stack trace command T 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.

toggle_trace

Sends the stack trace command t Toggle trace mode.

$debugger->toggle_trace();

list_subroutine_names

Sends the stack trace command S [[!]pattern] List subroutine names [not] matching pattern.

run

$debugger->run;

Will run till the next breakpoint or watch or the end of the script. (Like pressing c in the debugger).

$debugger->run($param)

set_breakpoint

$debugger->set_breakpoint($file, $line, $condition);

remove_breakpoint

show_breakpoints

The data as (L) prints in the command line debugger.

$debugger->show_breakpoints();

list_break_watch_action

In scalar context returns the list of all the breakpoints and watches as a text output. The data as (L) prints in the command line debugger.

In list context it returns the prompt number, and a list of hashes. Each hash has

file =>
line =>
cond =>

to provide the file-name, line number and the condition of the breakpoint. In case of no condition the last one will be the number 1.

execute_code

$debugger->execute_code($some_code_to_execute);

get_value

my $value = $debugger->get_value($x);

If $x is a scalar value, $value will contain that value. If it is a reference to a SCALAR, ARRAY or HASH then $value should be the value of that reference?

get_p_exp

p expr

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.

The DB::OUT filehandle is opened to /dev/tty, regardless of where STDOUT may be redirected to. From perldebug, but defaulted to y 0

$debugger->get_p_exp();

get_y_zero

From perldebug, but defaulted to y 0

y [level [vars]]

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.

$debugger->get_y_zero();

get_v_vars

V [pkg [vars]]

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:

$debugger->get_v_vars(regex);

get_x_vars

X [vars] Same as V currentpackage [vars]

$debugger->get_v_vars(regex);

get

Actually I think this is an internal method....

In SCALAR context will return all the buffer collected since the last command.

In LIST context will return ($prompt, $module, $file, $row, $content) Where $prompt is the what the standard debugger uses for prompt. Probably not too interesting. $file and $row describe the location of the next instructions. $content is the actual line - this is probably not too interesting as it is in the editor. $module is just the name of the module in which the current execution is.

filename

$debugger->filename();

row

$debugger->row();

BUGS AND LIMITATIONS

Debug::Client 0.12 tests are failing, due to changes in perl debugger, when using perl5db.pl v1.34 Debug::Client 0.13_01 skips added to failing tests.

c [line|sub]

Continue, optionally inserting a one-time-only breakpoint at the specified line or subroutine.

c is now ignoring options [line|sub]

and just performing c on it's own

INTERNAL METHODS

_get

_logger

_parse_dumper

_process_line

_prompt

_send

_send_get

_show_help

AUTHORS

Gabor Szabo <gabor@szabgab.com>

Breno G. de Oliveira <garu at cpan.org>

Kevin Dawson <bowtie@cpan.org>

Ahmad M. Zawawi <ahmad.zawawi@gmail.com>

COPYRIGHT

Copyright 2008-2011 Gabor Szabo. http://szabgab.com/

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl 5 itself.

WARRANTY

There is no warranty whatsoever. If you lose data or your hair because of this program, that's your problem.

CREDITS and THANKS

Originally started out from the remoteport.pl script from Pro Perl Debugging written by Richard Foley.

See Also

GRID::Machine::remotedebugtut