Tom Molesworth > Protocol-PerlDebugCLI > Protocol::PerlDebugCLI

Download:
Protocol-PerlDebugCLI-0.002.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.002   Source  

NAME ^

Protocol::PerlDebugCLI - generate and process events for interacting with the Perl debug interface

VERSION ^

version 0.002

SYNOPSIS ^

 use Protocol::PerlDebugCLI;
 my $deb = Protocol::PerlDebugCLI->new;

 # Attach handlers for the events that we're interested in,
 # anything else will be quietly ignored
 $deb->add_handler_for_event(
   breakpoint => sub {
     warn "Breakpoint reached\n";
   },
 );

 # Set a breakpoint and continue execution
 $deb->request_breakpoint(
   file => 'script.pl',
   line => 17,
 );
 $deb->request_continue;

DESCRIPTION ^

This is an abstract implementation for interacting with the perl debugger. It parses the debugger output (provided via the "on_read" method) and and generates events, similar in concept to SAX.

It also provides abstract methods for generating commands to drive the debugger; by hooking the write event a companion class or subclass can drive the debugger without knowing the details of the protocol.

This class is not intended to be used directly - it deals with the abstract protocol and requires additional code to deal with the transport layer (this could be through sockets, via the RemotePort= PERLDBOPTS flag, or on STDIN/STDOUT/TTY for a forked perl -d process).

See Net::Async::PerlDebugCLI for an implementation of a transport layer using RemotePort, and Tickit::Debugger::Async for a Tickit-based terminal debugging application.

Other similar classes for interacting with the debugger are listed in the "SEE ALSO" section.

METHODS ^

new

Instantiate a new object.

send_next_request

Attempt to send the next queued request to the debugger.

Expects the caller to have checked whether there are any requests pending, and will raise an exception if this is not the case.

have_queued_requests

Returns true if there are queued requests.

current_state

Accessor for the current state.

Will raise an exception if attempting to set the state to the same value as it had previously.

parse_variable_dump_line

Parse variable dump output, typically from v or x commands.

parse_code_context_line

Parse code context, which consists of the current active line and a few surrounding lines.

parse_at_breakpoint

At a breakpoint we start with the spec, then get line(s) of code

on_read

Should be called by the transport layer when data is available for parsing.

Expects the following parameters:

is_ready_for_request

Returns true if we're ready to send the next request (i.e. we're at a prompt).

request_stack_trace

Request a full stack trace.

request_vars_in_scope

Request a dump of all vars in the current scope.

request_current_line

Request information about the current line (i.e. next line to be executed).

request_step_into

Step into the current line.

request_step_over

Step over the current line.

request_continue

Continue execution.

request_breakpoint

Set a breakpoint on the requested line.

request_clear_breakpoint

Clear the given breakpoint.

Expects the following named parameters:

If no line is provided, will clear all existing breakpoints.

request_restart

Restart the current program.

request_watch

Request a watch on the given variable.

queue_command

Queue the given command.

write

Invokes a write event, requesting the given data be written to the underlying transport.

SEE ALSO ^

AUTHOR ^

Tom Molesworth <cpan@entitymodel.com>

LICENSE ^

Copyright Tom Molesworth 2011-2012. Licensed under the same terms as Perl itself.

syntax highlighting: