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;
      $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_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();
      $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 $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:

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

      $ebug->break_point(6, '$e = 4');

    A break point can be set at a line number in a file:

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

      $ebug->break_point("t/Calc.pm", 29, '$i == 2');

  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:

      $ebug->break_point_subroutine("main::add");
      $ebug->break_point_subroutine("Calc::fib");

  break_points
    The break_points method returns a list of all the line numbers in the
    current file that have a break point set.

      my @break_points = $ebug->break_points();

  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:

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

  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
    Leon Brocard, "<acme@astray.com>"

COPYRIGHT
    Copyright (C) 2005, Leon Brocard

    This module is free software; you can redistribute it or modify it under
    the same terms as Perl itself.