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.