DB::Pluggable - add plugin support for the Perl debugger
$ cat ~/.perldb use DB::Pluggable; use YAML; $DB::PluginHandler = DB::Pluggable->new(config => Load <<EOYAML); global: log: level: error plugins: - module: BreakOnTestNumber EOYAML $DB::PluginHandler->run; $ perl -d foo.pl
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.
~/.perldb
etc/perldb
Plugins should live in the DB::Pluggable:: namespace, like DB::Pluggable::BreakOnTestNumber does.
DB::Pluggable::
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:
Called at the beginning of the run() method. The hook doesn't get any arguments.
run()
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::watchfunction()
enable_watchfunction()
Called when the b debugger command (used to set breakpoints) is invoked. See run() below for what the hook should return.
b
The hook passes these named arguments:
This is the first argument passed to DB::cmd_b().
DB::cmd_b()
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.
This is the third argument passed to DB::cmd_b().
Tells the debugger to call DB::watchfunction(), which in turn calls the db.watchfunction hook on all plugins that have registered it.
db.watchfunction
First it calls the plugin.init hook, then it enables hooks for the relevant debugger commands (see above for which hooks are available).
plugin.init
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.
HANDLED
DECLINED
perl5db.pl
DB::Pluggable inherits from Hook::Modular.
The superclass Hook::Modular defines these methods and functions:
new(), add_plugin_path(), add_rewrite_task(), add_to_rule_namespaces(), autoload_plugin(), bootstrap(), context(), dumper(), error(), extract_package(), home_dir(), init(), is_loaded(), load_cache(), load_plugin(), load_plugins(), log(), register_hook(), rewrite_config(), rule_namespaces(), run_hook(), run_hook_once(), run_main(), set_context(), should_log()
The superclass Class::Accessor::Fast defines these methods and functions:
make_accessor(), make_ro_accessor(), make_wo_accessor()
The superclass Class::Accessor defines these methods and functions:
_carp(), _croak(), _mk_accessors(), accessor_name_for(), best_practice_accessor_name_for(), best_practice_mutator_name_for(), follow_best_practice(), get(), mk_accessors(), mk_ro_accessors(), mk_wo_accessors(), mutator_name_for(), set()
If you talk about this module in blogs, on del.icio.us or anywhere else, please use the dbpluggable tag.
dbpluggable
This document describes version 0.01 of DB::Pluggable.
No bugs have been reported.
Please report any bugs or feature requests to <bug-db-pluggable@rt.cpan.org>, or through the web interface at http://rt.cpan.org.
<bug-db-pluggable@rt.cpan.org
See perlmodinstall for information and options on installing Perl modules.
The latest version of this module is available from the Comprehensive Perl Archive Network (CPAN). Visit <http://www.perl.com/CPAN/> to find a CPAN site near you. Or see <http://www.perl.com/CPAN/authors/id/M/MA/MARCEL/>.
Marcel Grünauer, <marcel@cpan.org>
<marcel@cpan.org>
Copyright 2007-2008 by Marcel Grünauer
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
To install DB::Pluggable, copy and paste the appropriate command in to your terminal.
cpanm
cpanm DB::Pluggable
CPAN shell
perl -MCPAN -e shell install DB::Pluggable
For more information on module installation, please visit the detailed CPAN module installation guide.