view release on metacpan or  search on metacpan

lib/Devel/Chitin.pm  view on Meta::CPAN

Single-step the next statement in the debugged program.  If the next statement
is a subroutine call, the debugger will stop on its first executable statement.

=item CLIENT->stepover()

Single-step the next statement in the debugged program.  If the next statement
is a subroutine call, the debugger will stop on its first executable statement
after that subroutine call returns.

=item CLIENT->stepout()

Continue running the debugged program until the current subroutine returns
or until the next breakpoint, whichever comes first.

=item CLIENT->stepout(cb => $subref);

This form of stepout() allows registering a callback to be invoked when the
current subroutine returns.  The callback's first argument is an instance of
L<Devel::Chitin::SubroutineReturn>, which provides access to the location
the function is returning from, its wantarray status, and the function's
return value.  The C<rv> property of the SubroutineReturn object is mutable,
and actually changes the value being returned from the function.

Callbacks are invoked in the order they are queued, and a return value changed
in this way is presented as the return value to the next callback.  The final
callback gets the last say about the ultimate return value from the function.

=item CLIENT->continue()

Continue running the debugged program until the next breakpoint.

=item CLIENT->user_requested_exit()

Sets a flag that indicates the program should completely exit after the
debugged program ends.  Normally, the debugger will regain control after the
program ends.

=item CLIENT->eval($string, $wantarray, $coderef);

Evaluate the given string in the context of the most recent stack frame of
the program being debugged.  Because of the limitations of Perl's debugging
hooks, this function does not return the value directly.  Instead, the
caller must cede control back to the debugger system and the eval will be
done before the next statement in the program being debugged.  If the
debugged program is currently stopped at a breakpoint, then the eval will be
done before resuming.

The result is delivered by calling the given $coderef with two arguments:
the $result and $exception.  If $wantarray was true, then the result will
be an arrayref.

=item CLIENT->eval_at($string [, $level]);

Evaluate the given string in the context of the program being debugged.  If
$level is omitted, the string is run in the context of the most recent stack
frame of the debugged program.  Otherwise, $level is the number of stack
frames before the most recent to evaluate the code in.  Negative numbers are
treated as 0.  eval_at returns a list of two items, the result and exception.

This method requires the PadWalker module.

This method is not yet implemented.

=item CLIENT->get_var_at_level($string, $level);

Return the value of the given variable expression.  $level is the stack level
in the context of the debugged program; 0 is the most recent level.  $string
is the name of the variable to inspect, including the sigil.  This method
handles some more complicated expressions such array and hash elements and
slices.

This method is temporary, until eval_at() is implemented.

=back

=head2 Informational methods

=over 4

=item CLIENT->is_loaded($file)

Return true if the file is loaded

=item CLIENT->loaded_files()

Return a list of loaded file names

=item CLIENT->is_breakable($file, $line)

Return true if the line has an executable statement.  Only lines with executable
statements may have breakpoints.  In particular, line containing only comments,
whitespace or block delimiters are typically not breakable.

=item CLIENT->subroutine_location($subroutine)

Return a L<Devel::Chitin::SubroutineLocation> instance for where the
named subroutine was defined.  C<$subroutine> should be fully qualified
including the package name.

If the named function does not exist, it returns undef.

=item CLIENT->stack()

Return an instance of L<Devel::Chitin::Stack>.  This object represents the
execution/call stack of the debugged program.

=item CLIENT->current_location()

Return an instance of L<Devel::Chitin::Location> representing the currently
stopped location in the debugged program.  This method returns undef if
called when the debugged program is actively running.

=item CLIENT->next_statement()

Returns a string representing the next Perl statement to execute when control
returns to the debugged program with "step over".  This involves inspecting
the OpTree of the currently executing subroutine and deparsing it at the
stopped location.  Since the returned string is a reconstruction based on the
OpTree, it may not match the original source code exactly.