GSP
Quick Navigator

Search Site

Unix VPS
A - Starter
B - Basic
C - Preferred
D - Commercial
MPS - Dedicated
Previous VPSs
* Sign Up! *

Support
Contact Us
Online Help
Handbooks
Domain Status
Man Pages

FAQ
Virtual Servers
Pricing
Billing
Technical

Network
Facilities
Connectivity
Topology Map

Miscellaneous
Server Agreement
Year 2038
Credits
 

USA Flag

 

 

Man Pages
WWW::Mechanize::Pluggable(3) User Contributed Perl Documentation WWW::Mechanize::Pluggable(3)

WWW::Mechanize::Pluggable - A WWW::Mechanize that's 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.

WWW::Mechanize

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" 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" 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 the WWW::Mechanize object. Optional parameter '_Pluggable_mech_class' specifies a different class, e.g. Test::WWW::Mechanize.

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.

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.

The plugin mechanism is ridiculously programmer-intensive. This needs to be replaced with something better.
2019-02-01 perl v5.32.1

Search for    or go to Top of page |  Section 3 |  Main Index

Powered by GSP Visit the GSP FreeBSD Man Page Interface.
Output converted with ManDoc.