NAME
WWW::Mechanize::Pluggable - custmomizable via plugins
SYNOPSIS
use WWW::Mechanize::Pluggable;
# plugins now automatically loadedDESCRIPTION
This module provides all of the same functionality of WWW::Mechanize, but adds support for plugins using Module::Pluggable; this means that any module named WWW::Mechanize::Plugin::whatever... will be found and loaded when WWW::Mechanize::Pluggable is loaded.
Big deal, you say. Well, it becomes a big deal in conjunction with WWW::Mechanize::Pluggable's other feature: plugin hooks. When plugins are loaded, their import() methods can call WWW::Mechanize::Pluggable's prehook and posthook methods. These methods add callbacks to the plugin code in WWW::Mechanize::Pluggable's methods. These callbacks can act before a method or after it, and have to option of short-circuiting the call to the WWW::Mechanize::Pluggable method altogether.
These methods receive whatever parameters the WWW::Mechanize::Pluggable methods received, plus a reference to the actvive Mech object.
All other extensions to WWW::Mechanize::Pluggable are handled by the plugins.
SUBCLASSING
Subclassing this class is not recommended; partly because the method redispatch we need to do internally doesn't play well with the standard Perl OO model, and partly because you should be using plugins and hooks instead.
In WWW::Mechanize, it is recommended that you extend functionality by subclassing WWW::Mechanize, because there's no other way to extend the class. With Module::Pluggable support, it is easy to load another method directly into WWW::Mechanize::Pluggable's namespace; it then appears as if it had always been there. In addition, the pre_hook() and post_hook() methods provide a way to intercept a call and replace it with your output, or to tack on further processing at the end of a standard method (or even a plugin!).
The advantage of this is in not having a large number of subclasses, all of which add or alter WWW::Mechanize's function, and all of which have to be loaded if you want them available in your code. With WWW::Mechanize::Pluggable, one simply installs the desired plugins and they are all automatically available when you use WWW::Mechanize::Pluggable.
Configuration is a possible problem area; if three different plugins all attempt to replace get(), only one will win. It's better to create more sophisticated methods that call on lower-level ones than to alter existing known behavior.
USAGE
See the synopsis for an example use of the base module; extended behavior is documented in the plugin classes.
BUGS
None known.
SUPPORT
Contact the author at mcmahon@yahoo-inc.com.
AUTHOR
Joe McMahon
mcmahon@yahoo-inc.comCOPYRIGHT
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
SEE ALSO
CLASS METHODS
new
new constructs a WWW::Mechanize::Pluggable object and initializes its pre and port hook queues.
insert_hook
Adds a hook to a hook queue.
Needs the queue name, the method name of the method being hooked, and a reference to the hook sub itself.
remove_hook
Adds a hook to a hook queue.
Needs the queue name, the method name of the method being hooked, and a reference to the hook sub itself.
pre_hook
Shortcut to add a hook to a method's pre queue.
post_hook
Shortcut to add a hook to a method's post queue.
init
init runs through all of the plugins for this class and calls their init methods (if they exist). Not meant to be called by your code; it's internal-use-only.
AUTOLOAD
AUTOLOAD here is carefully tweaked to push anything we don't understand (either subroutine call or method call) to the parent class(es). Note that since SUPER searches the entire inheritance tree, we just have to add classes to @ISA to get SUPER to look in them.
clone
An ovveride for WWW::Mechanize's clone() method; uses YAML to make sure that the code references get cloned too.
There's been some discussion as to whether this is totally adequate (for instance, if the code references are closures, they won't be properly cloned). For now, we'll go with this and see how it works.