local-lib5/man/man3/Sub::Exporter::Cookbook.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 "Sub::Exporter::Cookbook 3"
 132 .TH Sub::Exporter::Cookbook 3 "2008-11-21" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Sub::Exporter::Cookbook \- useful, demonstrative, or stupid Sub::Exporter tricks
 135 .SH "OVERVIEW"
 136 .IX Header "OVERVIEW"
 137 Sub::Exporter is a fairly simple tool, and can be used to achieve some very
 138 simple goals.  Its basic behaviors and their basic application (that is,
 139 \&\*(L"traditional\*(R" exporting of routines) are described in
 140 Sub::Exporter::Tutorial and Sub::Exporter.  This document presents
 141 applications that may not be immediately obvious, or that can demonstrate how
 142 certain features can be put to use (for good or evil).
 143 .SH "THE RECIPES"
 144 .IX Header "THE RECIPES"
 145 .Sh "Exporting Methods as Routines"
 146 .IX Subsection "Exporting Methods as Routines"
 147 With Exporter.pm, exporting methods is a non\-starter.  Sub::Exporter makes it
 148 simple.  By using the \f(CW\*(C`curry_method\*(C'\fR utility provided in
 149 Sub::Exporter::Util, a method can be exported with the invocant built in.
 150 .PP
 151 .Vb 1
 152 \&  package Object::Strenuous;
 153 .Ve
 154 .PP
 155 .Vb 4
 156 \&  use Sub::Exporter::Util;
 157 \&  use Sub::Exporter \-setup => {
 158 \&    exports => [ objection => curry_method('new') ],
 159 \&  };
 160 .Ve
 161 .PP
 162 With this configuration, the importing code may contain:
 163 .PP
 164 .Vb 1
 165 \&  my $obj = objection("irrelevant");
 166 .Ve
 167 .PP
 168 \&...and this will be equivalent to:
 169 .PP
 170 .Vb 1
 171 \&  my $obj = Object::Strenuous\->new("irrelevant");
 172 .Ve
 173 .PP
 174 The built-in invocant is determined by the invocant for the \f(CW\*(C`import\*(C'\fR method.
 175 That means that if we were to subclass Object::Strenuous as follows:
 176 .PP
 177 .Vb 2
 178 \&  package Object::Strenuous::Repeated;
 179 \&  @ISA = 'Object::Strenuous';
 180 .Ve
 181 .PP
 182 \&...then importing \f(CW\*(C`objection\*(C'\fR from the subclass would build-in that subclass.
 183 .PP
 184 Finally, since the invocant can be an object, you can write something like
 185 this:
 186 .PP
 187 .Vb 4
 188 \&  package Cypher;
 189 \&  use Sub::Exporter \-setup => {
 190 \&    exports => [ encypher => curry_method ],
 191 \&  };
 192 .Ve
 193 .PP
 194 with the expectation that \f(CW\*(C`import\*(C'\fR will be called an instantiated Cypher
 195 object:
 196 .PP
 197 .Vb 4
 198 \&  BEGIN {
 199 \&    my $cypher = Cypher\->new( ... );
 200 \&    $cypher\->import('encypher');
 201 \&  }
 202 .Ve
 203 .PP
 204 Now there is a globally-available \f(CW\*(C`encypher\*(C'\fR routine which calls the encypher
 205 method on an otherwise unavailable Cypher object.
 206 .Sh "Exporting Methods as Methods"
 207 .IX Subsection "Exporting Methods as Methods"
 208 While exporting modules usually export subroutines to be called as subroutines,
 209 it's easy to use Sub::Exporter to export subroutines meant to be called as
 210 methods on the importing package or its objects.
 211 .PP
 212 Here's a trivial (and naive) example:
 213 .PP
 214 .Vb 1
 215 \&  package Mixin::DumpObj;
 216 .Ve
 217 .PP
 218 .Vb 1
 219 \&  use Data::Dumper;
 220 .Ve
 221 .PP
 222 .Vb 3
 223 \&  use Sub::Exporter \-setup => {
 224 \&    exports => [ qw(dump) ]
 225 \&  };
 226 .Ve
 227 .PP
 228 .Vb 4
 229 \&  sub dump {
 230 \&    my ($self) = @_;
 231 \&    return Dumper($self);
 232 \&  }
 233 .Ve
 234 .PP
 235 When writing your own object class, you can then import \f(CW\*(C`dump\*(C'\fR to be used as a
 236 method, called like so:
 237 .PP
 238 .Vb 1
 239 \&  $object\->dump;
 240 .Ve
 241 .PP
 242 By assuming that the importing class will provide a certain interface, a
 243 method-exporting module can be used as a simple plugin:
 244 .PP
 245 .Vb 6
 246 \&  package Number::Plugin::Upto;
 247 \&  use Sub::Exporter \-setup => {
 248 \&    into    => 'Number',
 249 \&    exports => [ qw(upto) ],
 250 \&    groups  => [ default => [ qw(upto) ] ],
 251 \&  };
 252 .Ve
 253 .PP
 254 .Vb 4
 255 \&  sub upto {
 256 \&    my ($self) = @_;
 257 \&    return 1 .. abs($self\->as_integer);
 258 \&  }
 259 .Ve
 260 .PP
 261 The \f(CW\*(C`into\*(C'\fR line in the configuration says that this plugin will export, by
 262 default, into the Number package, not into the \f(CW\*(C`use\*(C'\fR\-ing package.  It can be
 263 exported anyway, though, and will work as long as the destination provides an
 264 \&\f(CW\*(C`as_integer\*(C'\fR method like the one it expects.  To import it to a different
 265 destination, one can just write:
 266 .PP
 267 .Vb 1
 268 \&  use Number::Plugin::Upto { into => 'Quantity' };
 269 .Ve
 270 .Sh "Mixing-in Complex External Behavior"
 271 .IX Subsection "Mixing-in Complex External Behavior"
 272 When exporting methods to be used as methods (see above), one very powerful
 273 option is to export methods that are generated routines that maintain an
 274 enclosed reference to the exporting module.  This allows a user to import a
 275 single method which is implemented in terms of a complete, well-structured
 276 package.
 277 .PP
 278 Here is a very small example:
 279 .PP
 280 .Vb 1
 281 \&  package Data::Analyzer;
 282 .Ve
 283 .PP
 284 .Vb 3
 285 \&  use Sub::Exporter \-setup => {
 286 \&    exports => [ analyze => \e'_generate_analyzer' ],
 287 \&  };
 288 .Ve
 289 .PP
 290 .Vb 2
 291 \&  sub _generate_analyzer {
 292 \&    my ($mixin, $name, $arg, $col) = @_;
 293 .Ve
 294 .PP
 295 .Vb 2
 296 \&    return sub {
 297 \&      my ($self) = @_;
 298 .Ve
 299 .PP
 300 .Vb 1
 301 \&      my $values = [ $self\->values ];
 302 .Ve
 303 .PP
 304 .Vb 3
 305 \&      my $analyzer = $mixin\->new($values);
 306 \&      $analyzer\->perform_analysis;
 307 \&      $analyzer\->aggregate_results;
 308 .Ve
 309 .PP
 310 .Vb 3
 311 \&      return $analyzer\->summary;
 312 \&    };
 313 \&  }
 314 .Ve
 315 .PP
 316 If imported by any package providing a \f(CW\*(C`values\*(C'\fR method, this plugin will
 317 provide a single \f(CW\*(C`analyze\*(C'\fR method that acts as a simple interface to a more
 318 complex set of behaviors.
 319 .PP
 320 Even more importantly, because the \f(CW$mixin\fR value will be the invocant on
 321 which the \f(CW\*(C`import\*(C'\fR was actually called, one can subclass \f(CW\*(C`Data::Analyzer\*(C'\fR and
 322 replace only individual pieces of the complex behavior, making it easy to write
 323 complex, subclassable toolkits with simple single points of entry for external
 324 interfaces.
 325 .Sh "Exporting Constants"
 326 .IX Subsection "Exporting Constants"
 327 While Sub::Exporter isn't in the constant-exporting business, it's easy to
 328 export constants by using one of its sister modules, Package::Generator.
 329 .PP
 330 .Vb 1
 331 \&  package Important::Constants;
 332 .Ve
 333 .PP
 334 .Vb 3
 335 \&  use Sub::Exporter \-setup => {
 336 \&    collectors => [ constants => \e'_set_constants' ],
 337 \&  };
 338 .Ve
 339 .PP
 340 .Vb 2
 341 \&  sub _set_constants {
 342 \&    my ($class, $value, $data) = @_;
 343 .Ve
 344 .PP
 345 .Vb 9
 346 \&    Package::Generator\->assign_symbols(
 347 \&      $data\->{into},
 348 \&      [
 349 \&        MEANING_OF_LIFE => 42,
 350 \&        ONE_TRUE_BASE   => 13,
 351 \&        FACTORS         => [ 6, 9 ],
 352 \&      ],
 353 \&    );
 354 \&  }
 355 .Ve
 356 .PP
 357 Then, someone can write:
 358 .PP
 359 .Vb 1
 360 \&  use Important::Constants 'constants';
 361 .Ve
 362 .PP
 363 .Vb 1
 364 \&  print "The factors @FACTORS produce $MEANING_OF_LIFE in $ONE_TRUE_BASE.";
 365 .Ve
 366 .PP
 367 (The constants must be exported via a collector, because they are effectively
 368 altering the importing class in a way other than installing subroutines.)
 369 .ie n .Sh "Altering the Importer's @ISA"
 370 .el .Sh "Altering the Importer's \f(CW@ISA\fP"
 371 .IX Subsection "Altering the Importer's @ISA"
 372 It's trivial to make a collector that changes the inheritence of an importing
 373 package:
 374 .PP
 375 .Vb 3
 376 \&  use Sub::Exporter \-setup => {
 377 \&    collectors => { \-base => \e'_make_base' },
 378 \&  };
 379 .Ve
 380 .PP
 381 .Vb 2
 382 \&  sub _make_base {
 383 \&    my ($class, $value, $data) = @_;
 384 .Ve
 385 .PP
 386 .Vb 3
 387 \&    my $target = $data\->{into};
 388 \&    push @{"$target\e::ISA"}, $class;
 389 \&  }
 390 .Ve
 391 .PP
 392 Then, the user of your class can write:
 393 .PP
 394 .Vb 1
 395 \&  use Some::Class \-base;
 396 .Ve
 397 .PP
 398 and become a subclass.  This can be quite useful in building, for example, a
 399 module that helps build plugins.  We may want a few utilities imported, but we
 400 also want to inherit behavior from some base plugin class;
 401 .PP
 402 .Vb 1
 403 \&  package Framework::Util;
 404 .Ve
 405 .PP
 406 .Vb 5
 407 \&  use Sub::Exporter \-setup => {
 408 \&    exports    => [ qw(log global_config) ],
 409 \&    collectors => { _become_plugin => \e'_become_plugin' },
 410 \&    groups     => [ \-plugin => [ qw(log global_config _become_plugin) ]
 411 \&  };
 412 .Ve
 413 .PP
 414 .Vb 2
 415 \&  sub _become_plugin {
 416 \&    my ($class, $value, $data) = @_;
 417 .Ve
 418 .PP
 419 .Vb 3
 420 \&    my $target = $data\->{into};
 421 \&    push @{"$target\e::ISA"}, $class\->plugin_base_class;
 422 \&  }
 423 .Ve
 424 .PP
 425 Now, you can write a plugin like this:
 426 .PP
 427 .Vb 2
 428 \&  package Framework::Plugin::AirFreshener;
 429 \&  use Framework::Util \-plugin;
 430 .Ve
 431 .Sh "Eating Exporter.pm's Brain"
 432 .IX Subsection "Eating Exporter.pm's Brain"
 433 You probably shouldn't actually do this in production.  It's offered more as a
 434 demonstration than a suggestion.
 435 .PP
 436 .Vb 3
 437 \& sub exporter_upgrade {
 438 \&   my ($pkg) = @_;
 439 \&   my $new_pkg = "$pkg\e::UsingSubExporter";
 440 .Ve
 441 .PP
 442 .Vb 1
 443 \&   return $new_pkg if $new_pkg\->isa($pkg);
 444 .Ve
 445 .PP
 446 .Vb 9
 447 \&   Sub::Exporter::setup_exporter({
 448 \&     as      => 'import',
 449 \&     into    => $new_pkg,
 450 \&     exports => [ @{"$pkg\e::EXPORT_OK"} ],
 451 \&     groups  => {
 452 \&       %{{"$pkg\e::EXPORT_TAG"},
 453 \&       default => [ @{"$pkg\e::EXPORTS"} ],
 454 \&     },
 455 \&   });
 456 .Ve
 457 .PP
 458 .Vb 3
 459 \&   @{"$new_pkg\e::ISA"} = $class;
 460 \&   return $new_pkg;
 461 \& }
 462 .Ve
 463 .PP
 464 This routine, given the name of an existing package configured to use
 465 Exporter.pm, returns the name of a new package with a Sub::Exporter\-powered
 466 \&\f(CW\*(C`import\*(C'\fR routine.  This lets you write:
 467 .PP
 468 .Vb 4
 469 \&  BEGIN {
 470 \&    require Toolkit;
 471 \&    exporter_upgrade('Toolkit')\->import(exported_sub => { \-as => 'foo' })
 472 \&  }
 473 .Ve
 474 .PP
 475 If you're feeling particularly naughty, this routine could have been declared
 476 in the \s-1UNIVERSAL\s0 package, meaning you could write:
 477 .PP
 478 .Vb 4
 479 \&  BEGIN {
 480 \&    require Toolkit;
 481 \&    Toolkit\->exporter_upgrade\->import(exported_sub => { \-as => 'foo' })
 482 \&  }
 483 .Ve
 484 .PP
 485 The new package will have all the same exporter configuration as the original,
 486 but will support export and group renaming, including exporting into scalar
 487 references.  Further, since Sub::Exporter uses \f(CW\*(C`can\*(C'\fR to find the routine being
 488 exported, the new package may be subclassed and some of its exports replaced.
 489 .SH "AUTHOR"
 490 .IX Header "AUTHOR"
 491 Ricardo \s-1SIGNES\s0, \f(CW\*(C`<rjbs@cpan.org>\*(C'\fR
 492 .SH "COPYRIGHT"
 493 .IX Header "COPYRIGHT"
 494 Copyright 2007, Ricardo \s-1SIGNES\s0.  This is free software;  you can redistribute
 495 it and/or modify it under the same terms as Perl itself.