local-lib5/man/man3/Module::Pluggable.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sh \" Subsection heading
   6 .br
   7 .if t .Sp
   8 .ne 5
   9 .PP
  10 \fB\\$1\fR
  11 .PP
  12 ..
  13 .de Sp \" Vertical space (when we can't use .PP)
  14 .if t .sp .5v
  15 .if n .sp
  16 ..
  17 .de Vb \" Begin verbatim text
  18 .ft CW
  19 .nf
  20 .ne \\$1
  21 ..
  22 .de Ve \" End verbatim text
  23 .ft R
  24 .fi
  25 ..
  26 .\" Set up some character translations and predefined strings.  \*(-- will
  27 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  28 .\" double quote, and \*(R" will give a right double quote.  | will give a
  29 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used to
  30 .\" do unbreakable dashes and therefore won't be available.  \*(C` and \*(C'
  31 .\" expand to `' in nroff, nothing in troff, for use with C<>.
  32 .tr \(*W-|\(bv\*(Tr
  33 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  34 .ie n \{\
  35 .    ds -- \(*W-
  36 .    ds PI pi
  37 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  38 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  39 .    ds L" ""
  40 .    ds R" ""
  41 .    ds C` ""
  42 .    ds C' ""
  43 'br\}
  44 .el\{\
  45 .    ds -- \|\(em\|
  46 .    ds PI \(*p
  47 .    ds L" ``
  48 .    ds R" ''
  49 'br\}
  50 .\"
  51 .\" If the F register is turned on, we'll generate index entries on stderr for
  52 .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
  53 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  54 .\" output yourself in some meaningful fashion.
  55 .if \nF \{\
  56 .    de IX
  57 .    tm Index:\\$1\t\\n%\t"\\$2"
  58 ..
  59 .    nr % 0
  60 .    rr F
  61 .\}
  62 .\"
  63 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
  64 .\" way too many mistakes in technical documents.
  65 .hy 0
  66 .if n .na
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "Module::Pluggable 3"
 132 .TH Module::Pluggable 3 "2009-03-02" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Module::Pluggable \- automatically give your module the ability to have plugins
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 Simple use Module::Pluggable \-
 138 .PP
 139 .Vb 2
 140 \&    package MyClass;
 141 \&    use Module::Pluggable;
 142 .Ve
 143 .PP
 144 and then later ...
 145 .PP
 146 .Vb 4
 147 \&    use MyClass;
 148 \&    my $mc = MyClass\->new();
 149 \&    # returns the names of all plugins installed under MyClass::Plugin::*
 150 \&    my @plugins = $mc\->plugins();
 151 .Ve
 152 .SH "EXAMPLE"
 153 .IX Header "EXAMPLE"
 154 Why would you want to do this? Say you have something that wants to pass an
 155 object to a number of different plugins in turn. For example you may
 156 want to extract meta-data from every email you get sent and do something
 157 with it. Plugins make sense here because then you can keep adding new
 158 meta data parsers and all the logic and docs for each one will be
 159 self contained and new handlers are easy to add without changing the
 160 core code. For that, you might do something like ...
 161 .PP
 162 .Vb 1
 163 \&    package Email::Examiner;
 164 .Ve
 165 .PP
 166 .Vb 3
 167 \&    use strict;
 168 \&    use Email::Simple;
 169 \&    use Module::Pluggable require => 1;
 170 .Ve
 171 .PP
 172 .Vb 3
 173 \&    sub handle_email {
 174 \&        my $self  = shift;
 175 \&        my $email = shift;
 176 .Ve
 177 .PP
 178 .Vb 3
 179 \&        foreach my $plugin ($self\->plugins) {
 180 \&            $plugin\->examine($email);
 181 \&        }
 182 .Ve
 183 .PP
 184 .Vb 2
 185 \&        return 1;
 186 \&    }
 187 .Ve
 188 .PP
 189 \&.. and all the plugins will get a chance in turn to look at it.
 190 .PP
 191 This can be trivally extended so that plugins could save the email
 192 somewhere and then no other plugin should try and do that.
 193 Simply have it so that the \f(CW\*(C`examine\*(C'\fR method returns \f(CW1\fR if
 194 it has saved the email somewhere. You might also wnat to be paranoid
 195 and check to see if the plugin has an \f(CW\*(C`examine\*(C'\fR method.
 196 .PP
 197 .Vb 4
 198 \&        foreach my $plugin ($self\->plugins) {
 199 \&            next unless $plugin\->can('examine');
 200 \&            last if     $plugin\->examine($email);
 201 \&        }
 202 .Ve
 203 .PP
 204 And so on. The sky's the limit.
 205 .SH "DESCRIPTION"
 206 .IX Header "DESCRIPTION"
 207 Provides a simple but, hopefully, extensible way of having 'plugins' for
 208 your module. Obviously this isn't going to be the be all and end all of
 209 solutions but it works for me.
 210 .PP
 211 Essentially all it does is export a method into your namespace that
 212 looks through a search path for .pm files and turn those into class names.
 213 .PP
 214 Optionally it instantiates those classes for you.
 215 .SH "ADVANCED USAGE"
 216 .IX Header "ADVANCED USAGE"
 217 Alternatively, if you don't want to use 'plugins' as the method ...
 218 .PP
 219 .Vb 2
 220 \&    package MyClass;
 221 \&    use Module::Pluggable sub_name => 'foo';
 222 .Ve
 223 .PP
 224 and then later ...
 225 .PP
 226 .Vb 1
 227 \&    my @plugins = $mc\->foo();
 228 .Ve
 229 .PP
 230 Or if you want to look in another namespace
 231 .PP
 232 .Vb 2
 233 \&    package MyClass;
 234 \&    use Module::Pluggable search_path => ['Acme::MyClass::Plugin', 'MyClass::Extend'];
 235 .Ve
 236 .PP
 237 or directory
 238 .PP
 239 .Vb 1
 240 \&    use Module::Pluggable search_dirs => ['mylibs/Foo'];
 241 .Ve
 242 .PP
 243 Or if you want to instantiate each plugin rather than just return the name
 244 .PP
 245 .Vb 2
 246 \&    package MyClass;
 247 \&    use Module::Pluggable instantiate => 'new';
 248 .Ve
 249 .PP
 250 and then
 251 .PP
 252 .Vb 3
 253 \&    # whatever is passed to 'plugins' will be passed
 254 \&    # to 'new' for each plugin
 255 \&    my @plugins = $mc\->plugins(@options);
 256 .Ve
 257 .PP
 258 alternatively you can just require the module without instantiating it
 259 .PP
 260 .Vb 2
 261 \&    package MyClass;
 262 \&    use Module::Pluggable require => 1;
 263 .Ve
 264 .PP
 265 since requiring automatically searches inner packages, which may not be desirable, you can turn this off
 266 .PP
 267 .Vb 2
 268 \&    package MyClass;
 269 \&    use Module::Pluggable require => 1, inner => 0;
 270 .Ve
 271 .PP
 272 You can limit the plugins loaded using the except option, either as a string,
 273 array ref or regex
 274 .PP
 275 .Vb 2
 276 \&    package MyClass;
 277 \&    use Module::Pluggable except => 'MyClass::Plugin::Foo';
 278 .Ve
 279 .PP
 280 or
 281 .PP
 282 .Vb 2
 283 \&    package MyClass;
 284 \&    use Module::Pluggable except => ['MyClass::Plugin::Foo', 'MyClass::Plugin::Bar'];
 285 .Ve
 286 .PP
 287 or
 288 .PP
 289 .Vb 2
 290 \&    package MyClass;
 291 \&    use Module::Pluggable except => qr/^MyClass::Plugin::(Foo|Bar)$/;
 292 .Ve
 293 .PP
 294 and similarly for only which will only load plugins which match.
 295 .PP
 296 Remember you can use the module more than once
 297 .PP
 298 .Vb 3
 299 \&    package MyClass;
 300 \&    use Module::Pluggable search_path => 'MyClass::Filters' sub_name => 'filters';
 301 \&    use Module::Pluggable search_path => 'MyClass::Plugins' sub_name => 'plugins';
 302 .Ve
 303 .PP
 304 and then later ...
 305 .PP
 306 .Vb 2
 307 \&    my @filters = $self\->filters;
 308 \&    my @plugins = $self\->plugins;
 309 .Ve
 310 .SH "INNER PACKAGES"
 311 .IX Header "INNER PACKAGES"
 312 If you have, for example, a file \fBlib/Something/Plugin/Foo.pm\fR that
 313 contains package definitions for both \f(CW\*(C`Something::Plugin::Foo\*(C'\fR and
 314 \&\f(CW\*(C`Something::Plugin::Bar\*(C'\fR then as long as you either have either
 315 the \fBrequire\fR or \fBinstantiate\fR option set then we'll also find
 316 \&\f(CW\*(C`Something::Plugin::Bar\*(C'\fR. Nifty!
 317 .SH "OPTIONS"
 318 .IX Header "OPTIONS"
 319 You can pass a hash of options when importing this module.
 320 .PP
 321 The options can be ...
 322 .Sh "sub_name"
 323 .IX Subsection "sub_name"
 324 The name of the subroutine to create in your namespace.
 325 .PP
 326 By default this is 'plugins'
 327 .Sh "search_path"
 328 .IX Subsection "search_path"
 329 An array ref of namespaces to look in.
 330 .Sh "search_dirs"
 331 .IX Subsection "search_dirs"
 332 An array ref of directorys to look in before \f(CW@INC\fR.
 333 .Sh "instantiate"
 334 .IX Subsection "instantiate"
 335 Call this method on the class. In general this will probably be 'new'
 336 but it can be whatever you want. Whatever arguments are passed to 'plugins'
 337 will be passed to the method.
 338 .PP
 339 The default is 'undef' i.e just return the class name.
 340 .Sh "require"
 341 .IX Subsection "require"
 342 Just require the class, don't instantiate (overrides 'instantiate');
 343 .Sh "inner"
 344 .IX Subsection "inner"
 345 If set to 0 will \fBnot\fR search inner packages.
 346 If set to 1 will override \f(CW\*(C`require\*(C'\fR.
 347 .Sh "only"
 348 .IX Subsection "only"
 349 Takes a string, array ref or regex describing the names of the only plugins to
 350 return. Whilst this may seem perverse ... well, it is. But it also
 351 makes sense. Trust me.
 352 .Sh "except"
 353 .IX Subsection "except"
 354 Similar to \f(CW\*(C`only\*(C'\fR it takes a description of plugins to exclude
 355 from returning. This is slightly less perverse.
 356 .Sh "package"
 357 .IX Subsection "package"
 358 This is for use by extension modules which build on \f(CW\*(C`Module::Pluggable\*(C'\fR:
 359 passing a \f(CW\*(C`package\*(C'\fR option allows you to place the plugin method in a
 360 different package other than your own.
 361 .Sh "file_regex"
 362 .IX Subsection "file_regex"
 363 By default \f(CW\*(C`Module::Pluggable\*(C'\fR only looks for \fI.pm\fR files.
 364 .PP
 365 By supplying a new \f(CW\*(C`file_regex\*(C'\fR then you can change this behaviour e.g
 366 .PP
 367 .Vb 1
 368 \&    file_regex => qr/\e.plugin$/
 369 .Ve
 370 .Sh "include_editor_junk"
 371 .IX Subsection "include_editor_junk"
 372 By default \f(CW\*(C`Module::Pluggable\*(C'\fR ignores files that look like they were
 373 left behind by editors. Currently this means files ending in \fI~\fR (~),
 374 the extensions \fI.swp\fR or \fI.swo\fR, or files beginning with \fI.#\fR.
 375 .PP
 376 Setting \f(CW\*(C`include_editor_junk\*(C'\fR changes \f(CW\*(C`Module::Pluggable\*(C'\fR so it does
 377 not ignore any files it finds.
 378 .SH "METHODs"
 379 .IX Header "METHODs"
 380 .Sh "search_path"
 381 .IX Subsection "search_path"
 382 The method \f(CW\*(C`search_path\*(C'\fR is exported into you namespace as well.
 383 You can call that at any time to change or replace the
 384 search_path.
 385 .PP
 386 .Vb 2
 387 \&    $self\->search_path( add => "New::Path" ); # add
 388 \&    $self\->search_path( new => "New::Path" ); # replace
 389 .Ve
 390 .SH "FUTURE PLANS"
 391 .IX Header "FUTURE PLANS"
 392 This does everything I need and I can't really think of any other
 393 features I want to add. Famous last words of course
 394 .PP
 395 Recently tried fixed to find inner packages and to make it
 396 \&'just work' with \s-1PAR\s0 but there are still some issues.
 397 .PP
 398 However suggestions (and patches) are welcome.
 399 .SH "AUTHOR"
 400 .IX Header "AUTHOR"
 401 Simon Wistow <simon@thegestalt.org>
 402 .SH "COPYING"
 403 .IX Header "COPYING"
 404 Copyright, 2006 Simon Wistow
 405 .PP
 406 Distributed under the same terms as Perl itself.
 407 .SH "BUGS"
 408 .IX Header "BUGS"
 409 None known.
 410 .SH "SEE ALSO"
 411 .IX Header "SEE ALSO"
 412 File::Spec, File::Find, File::Basename, Class::Factory::Util, Module::Pluggable::Ordered