NAME

Devel::Chitin::Actionable - Get and set breakpoints and actions

SYNOPSIS

my $unconditional_bp = Devel::Chitin::Breakpoint->new(
                          file => $filename, line => 123 );

my $conditional_bp = Devel::Chitin::Breakpoint->new(
                          file => $filename, $line => 123,
                          code => q($a eq 'stop'));

my $inactive_bp = Devel::Chitin::Breakpoint->new(
                          file => $filename, $line 123,
                          inactive => 1);

my @bp = Devel::Chitin::Breakpoint->get(file => $filename, line => 123);
printf("breakpoint on line %d of %s: %s\n",
          $bp[0]->line, $b[0]->file, $bp[0]->code);

DESCRIPTION

Used to manipulate breakpoints and actions in the debugged program. Breakpoints are used to stop execution of the debugged program and let the debugging system take control there. Actions are used to run arbitrary code before a line in the debugged program executes.

Breakpoints

Breakpoints are associated with a file and line number, and the same file/line combination may have more than one breakpoint. Before executing a line with one or more breakpoints, all those breakpoints with string code attributes are tested by eval-ing, as a string eval, their code in the context of the debugged program; these can be used to implement a conditional breakpoint that stops depending on some condition in the program code. Coderef code attributes are called directly, and get no special scoping.

If any of these tests returns true, the debugger will stop the program before executing that line.

Constructor

my $bp = Devel::Chitin::Breakpoint->new(file => $f, line => $l,
                                      [ code => $code ],
                                      [ once => 1 ],
                                      [ inactive => 1]);

Creates a new Breakpoint object. file and line are required arguments. file must be a filename as it appears in $main::{"<_$file"}. If code is omitted, the value "1" is used as a default which creates an unconditional breakpoint. If once is a true value, then the breakpoint will delete itself after triggering. If inactive is true, the breakpoint will not trigger.

The breakpoint code can be either a string or a coderef. Strings are executed as a string-eval, and are evaluated in the context of the program being debugged. Coderefs are called directly, and behave according to normal scoping rules.

Methods

my @bp = Devel::Chitin::Breakpoint->get(file => $f, %other_params);

Retrieve breakpoints. Always returns a list of matching breakpoints. file is required, and if no other filters are used, returns all the breakpoints for that file. You may also filter by line, code and inactive.

$bp->file

$bp->line

$bp->once

Read-only accessors that return whatever values were used to create the breakpoint.

$bp->code

$bp->code($string)

Mutator that retrieves the breakpoint's code condition, or sets it.

$bp->inactive();

$bp->inactive( 1 | 0);

Mutator that retrieves the current inactive flag, or sets it.

$bp->delete();

Remove a breakpoint. Deleted breakpoints will never trigger again.

Actions

Actions are a lot like breakpoints; they are associated with a file and line number, and they have code that runs before that line in the program is executed. The difference is that the return value from the code is ignored.

The code is evaluated in the context of the running program if specified as a string, so it can, for example, affect variables there or print them out. Coderefs are called directly, and get no special scoping.

Constructor

my $act = Devel::Chitin::Action->new(file => $f, line => $l, code => $code,
                                      [ once => 1],
                                      [ inactive => 1]);

Creates a new Action object. file, line and code are required arguments. file must be a filename as it appears in $main::{"<_$file"}. breakpoint. If once is a true value, then the action will delete itself after running. If inactive is true, the action will not run.

Methods

my @acts = Devel::Chitin::Action->get(file => $f, %other_params);

Retrieve actions. Always returns a list of matching actions. file is required, and if no other filters are used, returns all the actions for that file. You may also filter by line, code and inactive.

$act->file

$act->line

$act->once

Read-only accessors that return whatever values were used to create the action.

$act->code

$act->code($string);

Mutator that retrieves the action's code, or set it.

$act->inactive();

$act->inactive( 1 | 0);

Mutator that retrieves the current inactive flag, or sets it.

$act->delete();

Remove an action. Deleted actions will never run again.

SEE ALSO

Devel::Chitin

AUTHOR

Anthony Brummett <brummett@cpan.org>

COPYRIGHT

Copyright 2017, Anthony Brummett. This module is free software. It may be used, redistributed and/or modified under the same terms as Perl itself.