NAME¶
Devel::ebug - A simple, extensible Perl debugger
SYNOPSIS¶
use Devel::ebug;
my $ebug = Devel::ebug->new;
$ebug->program("calc.pl");
$ebug->load;
print "At line: " . $ebug->line . "\n";
print "In subroutine: " . $ebug->subroutine . "\n";
print "In package: " . $ebug->package . "\n";
print "In filename: " . $ebug->filename . "\n";
print "Code: " . $ebug->codeline . "\n";
$ebug->step;
$ebug->step;
$ebug->next;
my($stdout, $stderr) = $ebug->output;
my $actual_line = $ebug->break_point(6);
$ebug->break_point(6, '$e == 4');
$ebug->break_point("t/Calc.pm", 29);
$ebug->break_point("t/Calc.pm", 29, '$i == 2');
my $actual_line = $ebug->break_point_subroutine("main::add");
$ebug->break_point_delete(29);
$ebug->break_point_delete("t/Calc.pm", 29);
my @filenames = $ebug->filenames();
my @break_points = $ebug->break_points();
my @break_points = $ebug->break_points("t/Calc.pm");
my @break_points = $ebug->break_points_with_condition();
my @break_points = $ebug->break_points_with_condition("t/Calc.pm");
my @break_points = $ebug->all_break_points_with_condition();
$ebug->watch_point('$x > 100');
my $codelines = $ebug->codelines(@span);
$ebug->run;
my $pad = $ebug->pad;
foreach my $k (sort keys %$pad) {
my $v = $pad->{$k};
print "Variable: $k = $v\n";
}
my $v = $ebug->eval('2 ** $exp');
my( $v, $is_exception ) = $ebug->eval('die 123');
my $y = $ebug->yaml('$z');
my @frames = $ebug->stack_trace;
my @frames2 = $ebug->stack_trace_human;
$ebug->undo;
$ebug->return;
print "Finished!\n" if $ebug->finished;
DESCRIPTION¶
A debugger is a computer program that is used to debug other programs.
Devel::ebug is a simple, extensible Perl debugger with a clean API. Using this
module, you may easily write a Perl debugger to debug your programs.
Alternatively, it comes with an interactive debugger, ebug.
perl5db.pl, Perl's current debugger is currently 2,600 lines of magic and
special cases. The code is nearly unreadable: fixing bugs and adding new
features is fraught with difficulties. The debugger has no test suite which
has caused breakage with changes that couldn't be properly tested. It will
also not debug regexes. Devel::ebug is aimed at fixing these problems and
delivering a replacement debugger which provides a well-tested simple
programmatic interface to debugging programs. This makes it easier to build
debuggers on top of Devel::ebug, be they console-, curses-, GUI- or
Ajax-based.
There are currently two user interfaces to Devel::debug, ebug and ebug_http.
ebug is a console-based interface to debugging programs, much like perl5db.pl.
ebug_http is an innovative web-based interface to debugging programs.
Note that if you're debugging a program, you can invoke the debugger in the
program itself by using the INT signal:
kill 2, $$ if $square > 100;
Devel::ebug is a work in progress.
Internally, Devel::ebug consists of two parts. The frontend is Devel::ebug,
which you interact with. The frontend starts the code you are debugging in the
background under the backend (running it under perl -d:ebug code.pl). The
backend starts a TCP server, which the frontend then connects to, and uses
this to drive the backend. This adds some flexibilty in the debugger. There is
some minor security in the client/server startup (a secret word), and a random
port is used from 3141-4165 so that multiple debugging sessions can happen
concurrently.
CONSTRUCTOR¶
new¶
The constructor creats a Devel::ebug object:
my $ebug = Devel::ebug->new;
program¶
The program method selects which program to load:
$ebug->program("calc.pl");
load¶
The load method loads the program and gets ready to debug it:
$ebug->load;
METHODS¶
break_point¶
The break_point method sets a break point in a program. If you are run-ing
through a program, the execution will stop at a break point. Break points can
be set in a few ways.
A break point can be set at a line number in the current file:
my $actual_line = $ebug->break_point(6);
A break point can be set at a line number in the current file with a condition
that must be true for execution to stop at the break point:
my $actual_line = $ebug->break_point(6, '$e = 4');
A break point can be set at a line number in a file:
my $actual_line = $ebug->break_point("t/Calc.pm", 29);
A break point can be set at a line number in a file with a condition that must
be true for execution to stop at the break point:
my $actual_line = $ebug->break_point("t/Calc.pm", 29, '$i == 2');
Breakpoints can not be set on some lines (for example comments); in this case a
breakpoint will be set at the next breakable line, and the line number will be
returned. If no such line exists, no breakpoint is set and the function
returns "undef".
break_point_delete¶
The break_point_delete method deletes an existing break point. A break point at
a line number in the current file can be deleted:
$ebug->break_point_delete(29);
A break point at a line number in a file can be deleted:
$ebug->break_point_delete("t/Calc.pm", 29);
break_point_subroutine¶
The break_point_subroutine method sets a break point in a program right at the
beginning of the subroutine. The subroutine is specified with the full package
name:
my $line = $ebug->break_point_subroutine("main::add");
$ebug->break_point_subroutine("Calc::fib");
The return value is the line at which the break point is set.
break_points¶
The break_points method returns a list of all the line numbers in a given file
that have a break point set.
Return the list of breakpoints in the current file:
my @break_points = $ebug->break_points();
Return the list of breakpoints in a given file:
my @break_points = $ebug->break_points("t/Calc.pm");
break_points_with_condition¶
The break_points method returns a list of break points for a given file.
Return the list of breakpoints in the current file:
my @break_points = $ebug->break_points_with_condition();
Return the list of breakpoints in a given file:
my @break_points = $ebug->break_points_with_condition("t/Calc.pm");
Each element of the list has the form
{ filename => "t/Calc.pm",
line => 29,
condition => "$foo > 12",
}
where "condition" might not be present.
all_break_points_with_condition¶
Like "break_points_with_condition" but returns a list of break points
for the whole program.
codeline¶
The codeline method returns the line of code that is just about to be executed:
print "Code: " . $ebug->codeline . "\n";
codelines¶
The codelines method returns lines of code.
It can return all the code lines in the current file:
my @codelines = $ebug->codelines();
It can return a span of code lines from the current file:
my @codelines = $ebug->codelines(1, 3, 4, 5);
It can return all the code lines in a file:
my @codelines = $ebug->codelines("t/Calc.pm");
It can return a span of code lines in a file:
my @codelines = $ebug->codelines("t/Calc.pm", 5, 6);
eval¶
The eval method evaluates Perl code in the current program and returns the
result. If the evalutation results in an exception, $@ is returned.
my $v = $ebug->eval('2 ** $exp');
In list context, eval also returns a flag indicating if the evalutation resulted
in an exception.
my( $v, $is_exception ) = $ebug->eval('die 123');
filename¶
The filename method returns the filename of the currently running code:
print "In filename: " . $ebug->filename . "\n";
filenames¶
The filenames method returns a list of the filenames of all the files currently
loaded:
my @filenames = $ebug->filenames();
finished¶
The finished method returns whether the program has finished running:
print "Finished!\n" if $ebug->finished;
line¶
The line method returns the line number of the statement about to be executed:
print "At line: " . $ebug->line . "\n";
next¶
The next method steps onto the next line in the program. It executes any
subroutine calls but does not step through them.
$ebug->next;
output¶
The output method returns any content the program has output to either standard
output or standard error:
my($stdout, $stderr) = $ebug->output;
package¶
The package method returns the package of the currently running code:
print "In package: " . $ebug->package . "\n";
pad¶
my $pad = $ebug->pad;
foreach my $k (sort keys %$pad) {
my $v = $pad->{$k};
print "Variable: $k = $v\n";
}
return¶
The return subroutine returns from a subroutine. It continues running the
subroutine, then single steps when the program flow has exited the subroutine:
$ebug->return;
It can also return your own values from a subroutine, for testing purposes:
$ebug->return(3.141);
run¶
The run subroutine starts executing the code. It will only stop on a break point
or watch point.
$ebug->run;
step¶
The step method steps onto the next line in the program. It steps through into
any subroutine calls.
$ebug->step;
subroutine¶
The subroutine method returns the subroutine of the currently working code:
print "In subroutine: " . $ebug->subroutine . "\n";
stack_trace¶
The stack_trace method returns the current stack trace, using Devel::StackTrace.
It returns a list of Devel::StackTraceFrame methods:
my @frames = $ebug->stack_trace;
foreach my $frame (@trace) {
print $frame->package, "->",$frame->subroutine,
"(", $frame->filename, "#", $frame->line, ")\n";
}
stack_trace_human¶
The stack_trace_human method returns the current stack trace in a human-readable
format:
my @frames = $ebug->stack_trace_human;
foreach my $frame (@trace) {
print "$frame\n";
}
undo¶
The undo method undos the last action. It accomplishes this by restarting the
process and passing (almost) all the previous commands to it. Note that
commands which do not change state are ignored. Commands that change state
are: break_point, break_point_delete, break_point_subroutine, eval, next,
step, return, run and watch_point.
$ebug->undo;
It can also undo multiple commands:
$ebug->undo(3);
watch_point¶
The watch point method sets a watch point. A watch point has a condition, and
the debugger will stop run-ing as soon as this condition is true:
$ebug->watch_point('$x > 100');
yaml¶
The eval method evaluates Perl code in the current program and returns the
result of YAML's
Dump() method:
my $y = $ebug->yaml('$z');
SEE ALSO¶
perldebguts
BUGS¶
Devel::ebug does not quite work under 5.8.0.
Devel::ebug does not handle signals under Windows.
AUTHOR¶
Latest releases by Brock Wilcox, "<awwaiid@thelackthereof.org>"
Leon Brocard, "<acme@astray.com>"
COPYRIGHT¶
Copyright (C) 2005-2008, Leon Brocard Copyright (C) 2011, Brock Wilcox
LICENSE¶
This module is free software; you can redistribute it or modify it under the
same terms as Perl itself.