-
-
01 Feb 2019 18:31:43 UTC
- Distribution: WWW-Mechanize-Pluggable
- Module version: 1.14
- Source (raw)
- Browse (raw)
- Changes
- How to Contribute
- Issues (0)
- Testers (459 / 0 / 0)
- Kwalitee
Bus factor: 1- % Coverage
- License: unknown
- Activity
24 month- Tools
- Download (26.05KB)
- MetaCPAN Explorer
- Permissions
- Subscribe to distribution
- Permalinks
- This version
- Latest version
and 1 contributors-
Joe McMahon
- Dependencies
- Carp
- Data::Dump::Streamer
- File::Temp
- FindBin
- HTML::Form
- HTML::HeadParser
- HTML::TokeParser
- HTTP::Cookies
- HTTP::Daemon
- HTTP::Request
- HTTP::Status
- LWP
- LWP::UserAgent
- Module::Pluggable
- Test::Exception
- Test::More
- URI
- URI::URL
- URI::file
- WWW::Mechanize
- and possibly others
- Reverse dependencies
- CPAN Testers List
- Dependency graph
- NAME
- SYNOPSIS
- DESCRIPTION
- SUBCLASSING
- USAGE
- BUGS
- SUPPORT
- AUTHOR
- COPYRIGHT
- SEE ALSO
- CLASS METHODS
- AUTOLOAD
- TODO
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 usingModule::Pluggable
; this means that any module namedWWW::Mechanize::Plugin::whatever...
will be found and loaded whenWWW::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, theirimport()
methods can callWWW::Mechanize::Pluggable
'sprehook
andposthook
methods. These methods add callbacks to the plugin code inWWW::Mechanize::Pluggable
's methods. These callbacks can act before a method or after it, and have to option of short-circuiting the call to theWWW::Mechanize::Pluggable
method altogether.These methods receive whatever parameters the
WWW::Mechanize::Pluggable
methods received, plus a reference to the actviveMech
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 subclassingWWW::Mechanize
, because there's no other way to extend the class. WithModule::Pluggable
support, it is easy to load another method directly intoWWW::Mechanize::Pluggable
's namespace; it then appears as if it had always been there. In addition, thepre_hook()
andpost_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. WithWWW::Mechanize::Pluggable
, one simply installs the desired plugins and they are all automatically available when youuse 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
CLASS METHODS
import
Handles the delegation of import options to the appropriate plugins.
import
loads the plugins (found via a call to__PACKAGE__-
plugins>) usingerquire
; it then calls each plugin'simport
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 getWWW::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 theirinit
methods (if they exist). Not meant to be called by your code; it's internal-use-only.init
gets all of the arguments supplied tonew
; it can process them or not as it pleases.What your plugin sees
Your plugin's
init
gets a reference to thePluggable
object plus the list of parameters supplied to thenew()
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 internalWWW::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 thefoo
argument and returnfoo
; this parameter would then be deleted from the arguments.new
new
constructs aWWW::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 thisnew
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 theWWW::Mechanize::Pluggable
class to have no superclass (other thanUNIVERSAL
).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 underlyingWWW::Mechanize
object. If weuse base qw(Class::Accessor)
, as is needed to make it work properly,Class::Accessor
'sAUTOLOAD
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
'sclone()
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.
Module Install Instructions
To install WWW::Mechanize::Pluggable, copy and paste the appropriate command in to your terminal.
cpanm WWW::Mechanize::Pluggable
perl -MCPAN -e shell install WWW::Mechanize::Pluggable
For more information on module installation, please visit the detailed CPAN module installation guide.