WWW::Mechanize::Plugin::Cookbook - how to write plugins for WWW::Mechanize::Pluggable
This document describes what a WWW::Mechanize::Pluggable plugin is, how they work in connection with the base module, and gives examples of how one would design a new plugin.
WWW::Mechanize::Pluggable
This cookbook addresses the current state of the Pluggable interface; future versions are expected to greatly streamline the process of creating plugins and hooks.
Pluggable
A plugin is basically as specially-named package that is automatically loaded by a parent class. This document outlines the interface between WWW::Mechanize::Pluggable and its plugin classes.
When WWW::Mechanize::Pluggable is loaded, it searches @INC for modules whose names begin with WWW::Mechanize::Plugin and calls import for the package, using the arguments supplied on WWW::Mechanize::Pluggable's own use line. This allows you to parameterize the plugins if you wish.
@INC
WWW::Mechanize::Plugin
import
use
When a WWW::Mechanize::Pluggable object is instantiated, its new method calls each of the plugins' init method. Typically, init() exports methods back into the caller's namespace, and also calls pre_hook and post_hook to wrap any of WWW::Mechanize's methods it desires.
new
init
init()
pre_hook
post_hook
WWW::Mechanize
When a WWW::Mechanize method is called, WWW::Mechanize::Pluggable's AUTOLOAD takes control. It calls any pre-hooks that have been installed for the method; if any of them return a true value, the actual method call is skipped. WW::Mechanize::Pluggable then calls the method (if it should) using the same context in which the method was originally callled, saving the return value. The post-hooks are then called, and the return value from the method is returned to the original caller.
AUTOLOAD
WW::Mechanize::Pluggable
Essentially, you now have complete control over what any method in the base class does. You can
alter the parameter list
process the call yourself
conditionally get involved, or not
post-process the results after the call
Called as import($class, %args).
import($class, %args)
This routine is optional; it is called when your plugin is loaded by WWW::Mechanize::Pluggable. You can use this to parameterize your plugin via arguments on the use statement.
It's recommended that you supply arguments as key-value pairs; this will make it possible for WWW::Mechanize::Pluggable to remove the "used-up" parameters from the c<use> line by returning the keys you want to have removed.
Here's a sample import method:
sub import { my($class, %args) = @_; if defined(my $value = $args{'mine'}) { if (_is_appropriate($value)) { # do whatever ,,, } } return ("mine"); }
This looks for the mine parameter on the use. It processes it as appropriate and returns the key so that WWW::Mechanize::Pluggable will delete it.
mine
Called as init($pluggable).
init($pluggable)
The init method allows your plugin a chance to export subroutines and store information appropriate for its proper functioning in the parent WWW::Mechanize::Pluggable object. It also can be used to set up pre-hooks and post-hooks for methods.
Note that at present it isn't possible to add hooks for methods installed by other plugins; a future release of this software may be able to do this.
Because other plugins will be doing the same thing, it's important to choose unique method names and field names. It's proabably a good idea to prefix field names with the name of your plugin, like _MyPlugin_data.
_MyPlugin_data
It's possible that we may change the interface in a future release of WWW::Mechanize::Pluggable to support "inside-out" objects (see http://www.windley.com/archives/2005/08/best_practices.shtml for an example).
Sample init function:
sub init { my($parent_object, %args) = @_; $parent_object->{_myplugin_foo} = "my data"; *{caller() . '::myplugin_method'} = \&my_implementation; $parent_object->pre_hook('get', sub { &my_prehook(@_) } ); $parent_object->post_hook('get', sub { &my_prehook(@_) } ); my @removed; if ($args{'my_arg'}) { # process my_arg push @removes, 'my_arg'; } @removed; }
The anonymous subroutine wrapping the hook setup currently is necessary to prevent the hook from being called during its installation; this needs to be fixed. The anonymous subroutine works for the moment, and will work in future releases, so go head and use it for now.
Also note that we have the same kind of interface that we do in import; you can parameterize a particular plugin by putting the parameters (key=>value-style) on the new and then processing them in init, and deleting them after processing by returning the list of names.
Called as $parent_object-pre_hook('method_name", $subref)>.
$parent_object-
Installs the referenced subroutine as a pre-hook for the named method. Currently, only WWW::Mechanize methods can be hooked; future releases may allow methods supplied by plugins to be hooked as well.
Installs the referenced subroutine as a post-hook for the named method. Currently, only WWW::Mechanize methods can be hooked; future releases may allow methods supplied by plugins to be hooked as well.
Since pre-hooks and post-hooks are all about getting your code involved in things, this section details how all that works.
Called as your_hook($pluggable, $internal_mech, @args).
your_hook($pluggable, $internal_mech, @args)
This is the subroutine that you passed a reference to in the call to either pre_hook or post_hook. It can do anything you like; it has access to both the \WWW::Mechanize::Pluggable object and to the internal WWW::Mechanize object, as well as to the parameters with which the method was called.
If your code is a pre-hook, it can cause WWW::Mechanize::Pluggable to skip the method call altogether by returning a true value.
Sample pre-hook:
sub my_prehook { my($pluggable, $mech, @args) = @_; # We'll assume that this is a hook for 'get'. if ($args[0] =~ /$selected_url/) { # alter the URL to what we want $args[0] =~ s/$what_we_dont_want/$what_we_do/; } # force another try with the altered URL. $pluggable->get(@args); # don't actually do the get with the old URL. return 'skip'; }
We used this approach because the interface currently doesn't allow us to alter the parameter list; this is something we probably should do in the next release.
To avoid doing a lot extra monkey coding, Class::Accessor::Fast is highly recommended.
Class::Accessor::Fast
package WWW::Mechanize::Plugin::MyPlugin; use base qw(Class::Accessor::Fast); __PACKAGE__->mk_accessors(qw(foo bar baz));
You can now use the newly-created accessors any way you like; often you'll use them to store data for other methods that are exported to WWW::Mechanize::Pluggable.
This is done (for the moment) by using a construct like this:
*{caller() . '::new_method'} = \&localsub;
This would call any subroutine or method call to new_method via the Mech::Pluggable object to be dispatched to localsub in this package.
In init, install a pre_hook for the method which does something like this:
sub init { pre_hook('desired_method', sub { \&substitute(@_) }); sub substitute { my($pluggable, $mech, @_) = @_; # Do whatever you want; return "skip"; }
Note the anonymous sub construct in the call to pre_hook. This is necessary because the construct \&substitute tries to call substitute() immediately, which we do not want.
\&substitute
We return "skip" as a mnemonic that a true value causes the real call to be skipped.
This is done with a prehook to count how many times we've tried to retry an action, and a posthook to
take whatever action is needed to set up for the retry
call back() on the Mech object
repeat the last action again on the Mech object
up the count of tries
The prehook is needed to keep the retry from going into an infinite loop.
The Perl Advent Calendar (http://www.perladvent.org/2004/6th/) for bringing Module::Pluggable to my attention.
Damian Conway, for showing us how to do things that Just Work.
Andy Lester, for WWW::Mechanize.
To install WWW::Mechanize::Pluggable, copy and paste the appropriate command in to your terminal.
cpanm
cpanm WWW::Mechanize::Pluggable
CPAN shell
perl -MCPAN -e shell install WWW::Mechanize::Pluggable
For more information on module installation, please visit the detailed CPAN module installation guide.