NAME
DB::Pluggable - Add plugin support for the Perl debugger
VERSION
version 1.101050
SYNOPSIS
$ cat ~/.perldb
use DB::Pluggable;
use Hook::Modular::Builder;
my $config = builder {
log_level 'error';
enable 'BreakOnTestNumber';
enable 'StackTraceAsHTML';
enable 'TypeAhead', type => [ '{l', 'c' ] if $ENV{DBTYPEAHEAD};
enable 'Dumper';
};
$DB::PluginHandler = DB::Pluggable->new(config => $config);
$DB::PluginHandler->run;
Alternatively, build the configuration yourself, for example, using
YAML:
$ cat ~/.perldb
use DB::Pluggable;
use YAML;
$DB::PluginHandler = DB::Pluggable->new(config => Load <run;
Then:
$ perl -d foo.pl
DESCRIPTION
This class adds plugin support to the Perl debugger. It is based on
Hook::Modular, so see its documentation for details.
You need to have a "~/.perldb" file (see perldebug for details) that
invokes the plugin mechanism. The one in the synopsis will do, and there
is a more commented one in this distribution's "etc/perldb" file.
Plugins should live in the "DB::Pluggable::" namespace, like
DB::Pluggable::BreakOnTestNumber does.
METHODS
enable_watchfunction
Tells the debugger to call "DB::watchfunction()", which in turn calls
the "db.watchfunction" hook on all plugins that have registered it.
run
First it calls the "plugin.init" hook, then it enables hooks for the
relevant debugger commands (see above for which hooks are available).
Each command-related hook should return the appropriate constant from
DB::Pluggable::Constants - either "HANDLED" if the hook has handled the
command, or "DECLINED" if it didn't. If no hook has "HANDLED" the
command, the default command subroutine (e.g., "DB::cmd_b()") from
"perl5db.pl" will be called.
HOOKS
This class is very much in beta, so it's more like a proof of concept.
Therefore, not all hooks imaginable have been added, only the ones to
make this demo work. If you want more hooks or if the current hooks
don't work for you, let me know.
The following hooks exist:
"plugin.init"
Called at the beginning of the "run()" method. The hook doesn't get
any arguments.
"db.watchfunction"
Called from within "DB::watchfunction()". If you want the debugger
to call the function, you need to enable it by calling
"enable_watchfunction()" somewhere within your plugin. It's a good
idea to enable it as late as possible because it is being called
very often. See the DB::Pluggable::BreakOnTestNumber source code for
an example. The hook doesn't get any arguments.
"db.cmd.b"
Called when the "b" debugger command (used to set breakpoints) is
invoked. See "run()" below for what the hook should return.
The hook passes these named arguments:
"cmd"
This is the first argument passed to "DB::cmd_b()".
"line"
This is the second argument passed to "DB::cmd_b()". This is the
most important argument as it contains the command line. See the
DB::Pluggable::BreakOnTestNumber source code for an example.
"dbline"
This is the third argument passed to "DB::cmd_b()".
"db.eval"
The debugger's "eval()" function is overridden so we can hook into
it. This is needed to define new debugger commands that take
arguments. Each plugin that registered this hook will get a chance
to inspect the command line, which is the last line in $DB::evalarg
and act on it. Each hook gets passed a code reference in the
original "DB::eval()" function. If a plugin decides the handle the
command, it needs to call the original function and return "HANDLED"
- see DB::Pluggable::Constants - to indicate that it has done so. If
a plugin does not want to handle the command, it must return
"DECLINED".
The hook passes these named arguments:
"eval"
The code reference to the original "DB::eval()" function.
For example, if you wanted to define a new "xx" debugger command, you
could use:
sub register {
my ($self, $context) = @_;
$context->register_hook(
$self,
'db.eval' => $self->can('eval'),
);
}
sub eval {
my ($self, $context, $args) = @_;
return DECLINED unless $DB::evalarg =~ s/\n\s*xx\s+([^\n]+)$/\n $1/;
... # handle the actual command
$args->{eval}->();
HANDLED;
}
INSTALLATION
See perlmodinstall for information and options on installing Perl
modules.
BUGS AND LIMITATIONS
No bugs have been reported.
Please report any bugs or feature requests through the web interface at
.
AVAILABILITY
The latest version of this module is available from the Comprehensive
Perl Archive Network (CPAN). Visit to find a
CPAN site near you, or see .
The development version lives at
. Instead of sending patches,
please fork this project using the standard git and github
infrastructure.
AUTHOR
Marcel Gruenauer
COPYRIGHT AND LICENSE
This software is copyright (c) 2008 by Marcel Gruenauer.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.