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.

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.