NAME

    Devel::ebug - A simple, extensible Perl debugger

VERSION

    version 0.66

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');
      $ebug->break_on_load("t/Calc.pm");
      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), and the two talk over a TCP socket on localhost,
    which the frontend uses to drive the backend. This adds some
    flexibility in the debugger.

    When "load" starts the program, the frontend listens on a port chosen
    by the operating system and passes it to the backend in the
    DEVEL_EBUG_CONNECT environment variable, along with a random secret
    word in SECRET. The backend connects back to that port and sends the
    secret before anything else, so the frontend can tell it apart from
    anything else that connects. Because the port is chosen by the
    operating system, any number of debugging sessions can run
    concurrently.

    Without DEVEL_EBUG_CONNECT, the backend instead listens on a port from
    3141-4165 derived from the secret, and waits for a frontend to attach
    with that secret, as ebug_server and ebug_client do. A frontend with
    the wrong secret is turned away without ending the session.

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");

    The program is run through the shell, so it may also carry arguments
    for the program ("add.pl 3 4"), subject to the shell's word splitting
    and interpolation. To pass arguments that must arrive exactly as given,
    set "args" instead.

 args

    The args method sets the command-line arguments for the program, as an
    array reference:

      $ebug->program("add.pl");
      $ebug->args([ 3, "four and a half" ]);

    When args is set the program is started without going through the
    shell, so each argument reaches the program's @ARGV unchanged, even if
    it contains spaces, quotes or other shell metacharacters. In that case
    "program" is taken as the path of the program alone. The arguments are
    used again each time the program is restarted, for example by undo.

 serializer

    The serializer method selects how requests and responses are written on
    the socket between the frontend and the backend:

      $ebug->serializer("json");

    yaml is the default and is what every existing client speaks: YAML
    output, hex packed onto a single line. json writes one plain JSON
    object per line instead, which is the format to choose when the other
    end is not Perl - a JSON line can be read by anything, whereas hex
    packed YAML asks a client for a YAML parser, object deserialization and
    a hex decoder first.

    It can also be set with the DEVEL_EBUG_SERIALIZER environment variable,
    which is how to choose the format for a frontend you do not construct
    yourself, such as ebug_client.

    The backend replies in whichever format each request arrived in, so
    nothing has to be arranged with it beforehand. Selecting json uses
    Cpanel::JSON::XS if it is installed, and otherwise requires JSON::PP,
    which has shipped with perl since 5.14 but is not otherwise a
    prerequisite of this distribution.

    See Devel::ebug::Wire for the details of both formats.

 load

    The load method loads the program and gets ready to debug it:

      $ebug->load;

METHODS

    If the program being debugged goes away without the debugger's help,
    for example because it was killed, crashed in XS code or called
    POSIX::_exit, any method that talks to it croaks with an error that
    begins Devel::ebug: lost the connection to the debugger. For a program
    started with "load", the error also says how it ended.

 break_point

    The break_point method sets a break point in a program. If you are
    running 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_on_load

    Set a breakpoint on file loading, the file name can be relative or
    absolute.

 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 evaluation results in an exception, $@ is returned.

      my $v = $ebug->eval('2 ** $exp');

    In list context, eval also returns a flag indicating if the evaluation
    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;

 interrupt

    The interrupt method asks a running program to stop at the next
    statement, as if a break point were there. It is meant for a program
    started with "run_nowait", or for calling from a signal handler during
    "run":

      $ebug->run_nowait;
      ...
      $ebug->interrupt;
      $ebug->wait_for_stop;

    It returns true if the program was signalled, and false without doing
    anything if the program is not running. Call "wait_for_stop" afterwards
    to find out where it stopped.

    Interrupting works by sending SIGINT to the program, so it is only
    supported for a program started with "load" on the same host, and not
    on Windows; it croaks otherwise. Like pressing Ctrl-C, it takes effect
    once the program next executes a Perl statement, so a long call into XS
    code finishes first.

 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";
      }

 pid

    The pid method returns the process id of the program being debugged, as
    reported by the program itself. This can differ from the process
    started by "load" when the program is run through the shell.

 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, a watch point, an "interrupt" or the end of the program.
    To start running without waiting for it to stop, see "run_nowait".

      $ebug->run;

 run_nowait

    The run_nowait method starts executing the code like "run", but returns
    straight away instead of waiting for the program to stop:

      $ebug->run_nowait;

    While the program is running, the only methods that may be called are
    "interrupt", "running" and "wait_for_stop"; anything else croaks. The
    "socket" becomes readable when the program stops, so a frontend with an
    event loop can wait on it rather than calling "wait_for_stop" right
    away.

 running

    The running method returns true between "run_nowait" and
    "wait_for_stop":

      print "still going\n" if $ebug->running;

 socket

    The socket method returns the socket connected to the program being
    debugged. Do not read from or write to it; it is only useful for
    waiting, for example with IO::Select, for it to become readable after
    "run_nowait".

 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 @traces = $ebug->stack_trace;
      foreach my $trace (@traces) {
        print $trace->package, "->",$trace->subroutine,
        "(", $trace->filename, "#", $trace->line, ")\n";
      }

 stack_trace_human

    The stack_trace_human method returns the current stack trace in a
    human-readable format:

      my @traces = $ebug->stack_trace_human;
      foreach my $trace (@traces) {
        print "$trace\n";
      }

 undo

    The undo method undoes 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);

 wait_for_stop

    The wait_for_stop method waits for a program started with "run_nowait"
    to stop, at a break point, a watch point, an "interrupt" or the end of
    the program, and updates "filename", "line" and so on to match:

      $ebug->wait_for_stop;
      print $ebug->filename, ":", $ebug->line, "\n";

    It returns straight away if the program is not running.

 watch_point

    The watch point method sets a watch point. A watch point has a
    condition, and the debugger will stop running 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

      The guts of debugging Perl

    Devel::Chitin

      A class that exposes the Perl debugging facilities as an API, with
      some functional overlap with Devel::ebug.

    ebug

      Command-line interface to Devel::ebug

    ebug_http

      Web based interface to Devel::ebug

CAVEATS

    Devel::ebug does not support Perls prior to 5.10.1.

    Devel::ebug does not handle signals under Windows.

    Running perl -d:ebug script.pl directly does not work, and will fail
    with No DB::DB routine defined. Devel::ebug is the frontend class; it
    is not itself a -d debugger backend. The backend is the internal
    Devel::ebug::Backend module, which is invoked automatically as perl
    -d:ebug::Backend script.pl when you call $ebug->load. To debug a
    script, either use the ebug command, or use Devel::ebug
    programmatically:

      my $ebug = Devel::ebug->new;
      $ebug->program('script.pl');
      $ebug->load;

AUTHOR

    Original author: Leon Brocard <acme@astray.com>

    Current maintainer: Graham Ollis <plicease@cpan.org>

    Contributors:

    Brock Wilcox <awwaiid@thelackthereof.org>

    Taisuke Yamada

COPYRIGHT AND LICENSE

    This software is copyright (c) 2005-2026 by Leon Brocard.

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