1Module::Pluggable(3) User Contributed Perl Documentation Module::Pluggable(3)
2
6 Module::Pluggable - automatically give your module the ability to have
7 plugins
8
10 Simple use Module::Pluggable -
11 package MyClass;
13 use Module::Pluggable;
14 and then later ...
16 use MyClass;
18 my $mc = MyClass->new();
19 # returns the names of all plugins installed under MyClass::Plugin::*
20 my @plugins = $mc->plugins();
21
23 Why would you want to do this? Say you have something that wants to
24 pass an object to a number of different plugins in turn. For example
25 you may want to extract meta-data from every email you get sent and do
26 something with it. Plugins make sense here because then you can keep
27 adding new meta data parsers and all the logic and docs for each one
28 will be self contained and new handlers are easy to add without
29 changing the core code. For that, you might do something like ...
30 package Email::Examiner;
32 use strict;
34 use Email::Simple;
35 use Module::Pluggable require => 1;
36 sub handle_email {
38 my $self = shift;
39 my $email = shift;
40 foreach my $plugin ($self->plugins) {
42 $plugin->examine($email);
43 }
44 return 1;
46 }
47 .. and all the plugins will get a chance in turn to look at it.
49 This can be trivially extended so that plugins could save the email
51 somewhere and then no other plugin should try and do that. Simply have
52 it so that the "examine" method returns 1 if it has saved the email
53 somewhere. You might also want to be paranoid and check to see if the
54 plugin has an "examine" method.
55 foreach my $plugin ($self->plugins) {
57 next unless $plugin->can('examine');
58 last if $plugin->examine($email);
59 }
60 And so on. The sky's the limit.
62
64 Provides a simple but, hopefully, extensible way of having 'plugins'
65 for your module. Obviously this isn't going to be the be all and end
66 all of solutions but it works for me.
67 Essentially all it does is export a method into your namespace that
69 looks through a search path for .pm files and turn those into class
70 names.
71 Optionally it instantiates those classes for you.
73
75 Alternatively, if you don't want to use 'plugins' as the method ...
76 package MyClass;
78 use Module::Pluggable sub_name => 'foo';
79 and then later ...
81 my @plugins = $mc->foo();
83 Or if you want to look in another namespace
85 package MyClass;
87 use Module::Pluggable search_path => ['Acme::MyClass::Plugin', 'MyClass::Extend'];
88 or directory
90 use Module::Pluggable search_dirs => ['mylibs/Foo'];
92 Or if you want to instantiate each plugin rather than just return the
94 name
95 package MyClass;
97 use Module::Pluggable instantiate => 'new';
98 and then
100 # whatever is passed to 'plugins' will be passed
102 # to 'new' for each plugin
103 my @plugins = $mc->plugins(@options);
104 alternatively you can just require the module without instantiating it
106 package MyClass;
108 use Module::Pluggable require => 1;
109 since requiring automatically searches inner packages, which may not be
111 desirable, you can turn this off
112 package MyClass;
114 use Module::Pluggable require => 1, inner => 0;
115 You can limit the plugins loaded using the except option, either as a
117 string, array ref or regex
118 package MyClass;
120 use Module::Pluggable except => 'MyClass::Plugin::Foo';
121 or
123 package MyClass;
125 use Module::Pluggable except => ['MyClass::Plugin::Foo', 'MyClass::Plugin::Bar'];
126 or
128 package MyClass;
130 use Module::Pluggable except => qr/^MyClass::Plugin::(Foo|Bar)$/;
131 and similarly for only which will only load plugins which match.
133 Remember you can use the module more than once
135 package MyClass;
137 use Module::Pluggable search_path => 'MyClass::Filters' sub_name => 'filters';
138 use Module::Pluggable search_path => 'MyClass::Plugins' sub_name => 'plugins';
139 and then later ...
141 my @filters = $self->filters;
143 my @plugins = $self->plugins;
144
146 Every time you call 'plugins' the whole search path is walked again.
147 This allows for dynamically loading plugins even at run time. However
148 this can get expensive and so if you don't expect to want to add new
149 plugins at run time you could do
150 package Foo;
152 use strict;
153 use Module::Pluggable sub_name => '_plugins';
154 our @PLUGINS;
156 sub plugins { @PLUGINS ||= shift->_plugins }
157 1;
158
160 If you have, for example, a file lib/Something/Plugin/Foo.pm that
161 contains package definitions for both "Something::Plugin::Foo" and
162 "Something::Plugin::Bar" then as long as you either have either the
163 require or instantiate option set then we'll also find
164 "Something::Plugin::Bar". Nifty!
165
167 You can pass a hash of options when importing this module.
168 The options can be ...
170 sub_name
172 The name of the subroutine to create in your namespace.
173 By default this is 'plugins'
175 search_path
177 An array ref of namespaces to look in.
178 search_dirs
180 An array ref of directories to look in before @INC.
181 instantiate
183 Call this method on the class. In general this will probably be 'new'
184 but it can be whatever you want. Whatever arguments are passed to
185 'plugins' will be passed to the method.
186 The default is 'undef' i.e just return the class name.
188 require
190 Just require the class, don't instantiate (overrides 'instantiate');
191 inner
193 If set to 0 will not search inner packages. If set to 1 will override
194 "require".
195 only
197 Takes a string, array ref or regex describing the names of the only
198 plugins to return. Whilst this may seem perverse ... well, it is. But
199 it also makes sense. Trust me.
200 except
202 Similar to "only" it takes a description of plugins to exclude from
203 returning. This is slightly less perverse.
204 package
206 This is for use by extension modules which build on
207 "Module::Pluggable": passing a "package" option allows you to place the
208 plugin method in a different package other than your own.
209 file_regex
211 By default "Module::Pluggable" only looks for .pm files.
212 By supplying a new "file_regex" then you can change this behaviour e.g
214 file_regex => qr/\.plugin$/
216 include_editor_junk
218 By default "Module::Pluggable" ignores files that look like they were
219 left behind by editors. Currently this means files ending in ~ (~), the
220 extensions .swp or .swo, or files beginning with .#.
221 Setting "include_editor_junk" changes "Module::Pluggable" so it does
223 not ignore any files it finds.
224 follow_symlinks
226 Whether, when searching directories, to follow symlinks.
227 Defaults to 1 i.e do follow symlinks.
229 min_depth, max_depth
231 This will allow you to set what 'depth' of plugin will be allowed.
232 So, for example, "MyClass::Plugin::Foo" will have a depth of 3 and
234 "MyClass::Plugin::Foo::Bar" will have a depth of 4 so to only get the
235 former (i.e "MyClass::Plugin::Foo") do
236 package MyClass;
238 use Module::Pluggable max_depth => 3;
239 and to only get the latter (i.e "MyClass::Plugin::Foo::Bar")
241 package MyClass;
243 use Module::Pluggable min_depth => 4;
244
246 Various triggers can also be passed in to the options.
247 If any of these triggers return 0 then the plugin will not be returned.
249 before_require <plugin>
251 Gets passed the plugin name.
252 If 0 is returned then this plugin will not be required either.
254 on_require_error <plugin> <err>
256 Gets called when there's an error on requiring the plugin.
257 Gets passed the plugin name and the error.
259 The default on_require_error handler is to "carp" the error and return
261 0.
262 on_instantiate_error <plugin> <err>
264 Gets called when there's an error on instantiating the plugin.
265 Gets passed the plugin name and the error.
267 The default on_instantiate_error handler is to "carp" the error and
269 return 0.
270 after_require <plugin>
272 Gets passed the plugin name.
273 If 0 is returned then this plugin will be required but not returned as
275 a plugin.
276
278 search_path
279 The method "search_path" is exported into you namespace as well. You
280 can call that at any time to change or replace the search_path.
281 $self->search_path( add => "New::Path" ); # add
283 $self->search_path( new => "New::Path" ); # replace
284
286 In order to make testing reliable we exclude anything not from blib if
287 blib.pm is in %INC.
288 However if the module being tested used another module that itself used
290 "Module::Pluggable" then the second module would fail. This was fixed
291 by checking to see if the caller had (^|/)blib/ in their filename.
292 There's an argument that this is the wrong behaviour and that modules
294 should explicitly trigger this behaviour but that particular code has
295 been around for 7 years now and I'm reluctant to change the default
296 behaviour.
297 You can now (as of version 4.1) force Module::Pluggable to look outside
299 blib in a test environment by doing either
300 require Module::Pluggable;
302 $Module::Pluggable::FORCE_SEARCH_ALL_PATHS = 1;
303 import Module::Pluggable;
304 or
306 use Module::Pluggable force_search_all_paths => 1;
308
310 If a module's @INC has a hook and that hook is an object which has a
311 "files()" method then we will try and require those files too. See
312 "t/26inc_hook.t" for an example.
313 This has allowed App::FatPacker (as of version 0.10.0) to provide
315 support for Module::Pluggable.
316 This should also, theoretically, allow someone to modify PAR to do the
318 same thing.
319
321 Up until version 5.2 Module::Pluggable used a string "eval" to require
322 plugins.
323 This has now been changed to optionally use Module::Runtime and it's
325 "require_module" method when available and fall back to using a path
326 based "require" when not.
327 It's recommended, but not required, that you install Module::Runtime.
329
331 This does everything I need and I can't really think of any other
332 features I want to add. Famous last words of course (not least because
333 we're up to version 5.0 at the time of writing).
334 However suggestions (and patches) are always welcome.
336
338 The master repo for this module is at
339 https://github.com/simonwistow/Module-Pluggable
341
343 Simon Wistow <simon@thegestalt.org>
344
346 Copyright, 2006 Simon Wistow
347 Distributed under the same terms as Perl itself.
349
351 None known.
352
354 File::Spec, File::Find, File::Basename, Class::Factory::Util,
355 Module::Pluggable::Ordered
356perl v5.34.0 2021-07-22 Module::Pluggable(3)