|
WWW::Mechanize::Pluggable - custmomizable via plugins |
WWW::Mechanize::Pluggable - custmomizable via plugins
use WWW::Mechanize::Pluggable; # plugins now automatically loaded
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 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.
See the synopsis for an example use of the base module; extended behavior is documented in the plugin classes.
None known.
Contact the author at mcmahon@yahoo-inc.com.
Joe McMahon
mcmahon@yahoo-inc.com
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.
Handles the delegation of import options to the appropriate plugins.
import loads the plugins (found via a call to __PACKAGE__-plugins>) using
erquire; it then calls each plugin's import method with the parameters
supplied on the use statement for WWW::Mechanize::Pluggable. The
plugin's import method is expected to return a list of argument
naems that are to be ermoved from the global argument list.
Let's take the example
use WWW::Mechanize::Pluggable foo => 1, bar => [qw(a b c)],
baz => 'quux';
Your import gets whatever is currently in the list, so we start off with
all the parameters. If your import returns ('foo', 'baz'), then it's
presumed to have sucessfully processed these parameters, and they are removed
from the list. So the next plugin gets called only with bar = [qw(a b c)]>.
A plugin can return either a null list or undef to leave the
parameter list alone.
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.
init gets all of the arguments supplied to new; it can
process them or not as it pleases.
Your plugin's init gets a reference to the Pluggable object
plus the list of parameters supplied to the new() call. This is
assumewd to be a set of zero or more key/value pairs.
init can return a list of keys to be deleted from the parameter
hash; this allows plugins to process parameters themselves without
the internal WWW::Mechanize object ever seeing them. If you
return a null list, nothing gets deleted.
As an example:
my $mech = new WWW::Mechanize::Pluggable foo=>'bar';
A plugin's init could process the foo argument and return foo;
this parameter would then be deleted from the arguments.
new constructs a WWW::Mechanize::Pluggable object and initializes
its pre and port hook queues. You can add parameters to be passed to
plugins' init methods by adding them to this new call.
Returns the component WWW::Mechanize object.
This is a simple set/get accessor; normally we'd just use the Class::Accessor manpage
to create it and forget about the details. We don't use Class::Accessor,
though, because we want the WWW::Mechanize::Pluggable class to have no
superclass (other than UNIVERSAL).
This is necessary because we use (q.v.) to trap all of the calls
to this class so they can be pre- and post-processed before being passed on
to the underlying WWW::Mechanize object. If we use base qw(Class::Accessor),
as is needed to make it work properly, Class::Accessor's AUTOLOAD gets control
instead of ours, and the hooks don't work.
Adds a hook to a hook queue. This is a utility routine, encapsulating the hook queue manipulation in a single method.
Needs the queue name, the method name of the method being hooked, and a reference to the hook sub itself.
Deletes a hook from a hook queue.
Needs the queue name, the method name of the method being hooked, and a reference to the hook sub itself.
Shortcut to add a hook to a method's pre queue. Needs a method name and a reference to a subroutine to be called as the hook.
Shortcut to add a hook to a method's post queue. Needs a method name and a reference to the subroutine to be called as the hook.
Records the last method used to call WWW::Mechanize::Pluggable.
This allows plugins to call a method again if necessary without
having to know what method was actually called.
This subroutine implements a mix of the ``decorator'' pattern and
the ``proxy'' pattern. It intercepts all the calls to the underlying class,
and also wraps them with pre-hooks (called before the method is called)
and post-hooks (called after the method is called). This allows us to
provide all of the functionality of WWW::Mechanize in this class
without copying any of the code, and to alter the behavior as well
without altering the original class.
Pre-hooks can cause the actual method call to the underlying class to be skipped altogether by returning a true value.
An ovveride for WWW::Mechanize's clone() method; uses YAML to make sure
that the code references get cloned too. Note that this is important for
later code (the cache stuff in particular); general users won't notice
any real difference.
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.
|
WWW::Mechanize::Pluggable - custmomizable via plugins |