summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Module/Pluggable.pm
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Module/Pluggable.pm')
-rw-r--r--Master/tlpkg/tlperl/lib/Module/Pluggable.pm110
1 files changed, 106 insertions, 4 deletions
diff --git a/Master/tlpkg/tlperl/lib/Module/Pluggable.pm b/Master/tlpkg/tlperl/lib/Module/Pluggable.pm
index 55cf7269e70..9e7962efab7 100644
--- a/Master/tlpkg/tlperl/lib/Module/Pluggable.pm
+++ b/Master/tlpkg/tlperl/lib/Module/Pluggable.pm
@@ -1,15 +1,18 @@
package Module::Pluggable;
use strict;
-use vars qw($VERSION);
+use vars qw($VERSION $FORCE_SEARCH_ALL_PATHS);
use Module::Pluggable::Object;
+use if $] > 5.017, 'deprecate';
+
# ObQuote:
# Bob Porter: Looks like you've been missing a lot of work lately.
# Peter Gibbons: I wouldn't say I've been missing it, Bob!
-$VERSION = '4.0';
+$VERSION = '4.7';
+$FORCE_SEARCH_ALL_PATHS = 0;
sub import {
my $class = shift;
@@ -22,6 +25,7 @@ sub import {
my ($package) = $opts{'package'} || $pkg;
$opts{filename} = $file;
$opts{package} = $package;
+ $opts{force_search_all_paths} = $FORCE_SEARCH_ALL_PATHS unless exists $opts{force_search_all_paths};
my $finder = Module::Pluggable::Object->new(%opts);
@@ -152,9 +156,8 @@ Optionally it instantiates those classes for you.
=head1 ADVANCED USAGE
-
Alternatively, if you don't want to use 'plugins' as the method ...
-
+
package MyClass;
use Module::Pluggable sub_name => 'foo';
@@ -227,6 +230,21 @@ and then later ...
my @filters = $self->filters;
my @plugins = $self->plugins;
+
+=head1 PLUGIN SEARCHING
+
+Every time you call 'plugins' the whole search path is walked again. This allows
+for dynamically loading plugins even at run time. However this can get expensive
+and so if you don't expect to want to add new plugins at run time you could do
+
+
+ package Foo;
+ use strict;
+ use Module::Pluggable sub_name => '_plugins';
+
+ our @PLUGINS;
+ sub plugins { @PLUGINS ||= shift->_plugins }
+ 1;
=head1 INNER PACKAGES
@@ -307,6 +325,62 @@ the extensions F<.swp> or F<.swo>, or files beginning with F<.#>.
Setting C<include_editor_junk> changes C<Module::Pluggable> so it does
not ignore any files it finds.
+=head2 follow_symlinks
+
+Whether, when searching directories, to follow symlinks.
+
+Defaults to 1 i.e do follow symlinks.
+
+=head2 min_depth, max_depth
+
+This will allow you to set what 'depth' of plugin will be allowed.
+
+So, for example, C<MyClass::Plugin::Foo> will have a depth of 3 and
+C<MyClass::Plugin::Foo::Bar> will have a depth of 4 so to only get the former
+(i.e C<MyClass::Plugin::Foo>) do
+
+ package MyClass;
+ use Module::Pluggable max_depth => 3;
+
+and to only get the latter (i.e C<MyClass::Plugin::Foo::Bar>)
+
+ package MyClass;
+ use Module::Pluggable min_depth => 4;
+
+
+=head1 TRIGGERS
+
+Various triggers can also be passed in to the options.
+
+If any of these triggers return 0 then the plugin will not be returned.
+
+=head2 before_require <plugin>
+
+Gets passed the plugin name.
+
+If 0 is returned then this plugin will not be required either.
+
+=head2 on_require_error <plugin> <err>
+
+Gets called when there's an error on requiring the plugin.
+
+Gets passed the plugin name and the error.
+
+The default on_require_error handler is to C<carp> the error and return 0.
+
+=head2 on_instantiate_error <plugin> <err>
+
+Gets called when there's an error on instantiating the plugin.
+
+Gets passed the plugin name and the error.
+
+The default on_instantiate_error handler is to C<carp> the error and return 0.
+
+=head2 after_require <plugin>
+
+Gets passed the plugin name.
+
+If 0 is returned then this plugin will be required but not returned as a plugin.
=head1 METHODs
@@ -319,7 +393,29 @@ search_path.
$self->search_path( add => "New::Path" ); # add
$self->search_path( new => "New::Path" ); # replace
+=head1 BEHAVIOUR UNDER TEST ENVIRONMENT
+In order to make testing reliable we exclude anything not from blib if blib.pm is
+in %INC.
+
+However if the module being tested used another module that itself used C<Module::Pluggable>
+then the second module would fail. This was fixed by checking to see if the caller
+had (^|/)blib/ in their filename.
+
+There's an argument that this is the wrong behaviour and that modules should explicitly
+trigger this behaviour but that particular code has been around for 7 years now and I'm
+reluctant to change the default behaviour.
+
+You can now (as of version 4.1) force Module::Pluggable to look outside blib in a test environment by doing either
+
+ require Module::Pluggable;
+ $Module::Pluggable::FORCE_SEARCH_ALL_PATHS = 1;
+ import Module::Pluggable;
+
+or
+
+ use Module::Pluggable force_search_all_paths => 1;
+
=head1 FUTURE PLANS
@@ -332,6 +428,12 @@ Recently tried fixed to find inner packages and to make it
However suggestions (and patches) are welcome.
+=head1 DEVELOPMENT
+
+The master repo for this module is at
+
+https://github.com/simonwistow/Module-Pluggable
+
=head1 AUTHOR
Simon Wistow <simon@thegestalt.org>