/ 
WWW-Mechanize-Pluggable-1.14
River stage two • 9 direct dependents • 14 total dependents
++
/ WWW::Mechanize::Pluggable

NAME

WWW::Mechanize::Pluggable - A WWW::Mechanize that's custmomizable via plugins

SYNOPSIS

  use WWW::Mechanize::Pluggable;
  # plugins now automatically loaded

DESCRIPTION

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.com

COPYRIGHT

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

WWW::Mechanize

CLASS METHODS

import

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 specific to it, if there are any.

What your plugin sees

Let's take the example

  use WWW::Mechanize::Pluggable Zonk => [foo => 1, bar => [qw(a b c)]],
                                Thud => [baz => 'quux'];

WWW::Mechanize::Plugin::Zonk's import() would get called like this:

  WWW::Mechanize::Plugin::Zonk->import(foo => 1, bar => [qw(a b c)]);

And WWW::Mechanize::Plugin::Thud's import() would get

  WWW::Mechanize::Plugin::Thud->import(baz => 'quux');

So each plugin only sees what it's supposed to.

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.

init gets all of the arguments supplied to new; it can process them or not as it pleases.

What your plugin sees

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

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.

_create_mech_object

Create the WWW::Mechanize object. Optional parameter '_Pluggable_mech_class' specifies a different class, e.g. Test::WWW::Mechanize.

mech

Returns the component WWW::Mechanize object.

This is a simple set/get accessor; normally we'd just use Class::Accessor 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 AUTOLOAD (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.

_insert_hook

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.

_remove_hook

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.

pre_hook

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.

post_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.

last_method

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.

AUTOLOAD

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.

clone

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.

TODO

The plugin mechanism is ridiculously programmer-intensive. This needs to be replaced with something better.