local-lib5/man/man3/Sub::Exporter::Tutorial.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::Tutorial 3"
 132 .TH Sub::Exporter::Tutorial 3 "2008-11-21" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Sub::Exporter::Tutorial \- a friendly guide to exporting with Sub::Exporter
 135 .SH "DESCRIPTION"
 136 .IX Header "DESCRIPTION"
 137 .Sh "What's an Exporter?"
 138 .IX Subsection "What's an Exporter?"
 139 When you \f(CW\*(C`use\*(C'\fR a module, first it is required, then its \f(CW\*(C`import\*(C'\fR method is
 140 called.  The Perl documentation tells us that the following two lines are
 141 equivalent:
 142 .PP
 143 .Vb 1
 144 \&  use Module LIST;
 145 .Ve
 146 .PP
 147 .Vb 1
 148 \&  BEGIN { require Module; Module\->import(LIST); }
 149 .Ve
 150 .PP
 151 The import method is the module's \fIexporter\fR.
 152 .Sh "The Basics of Sub::Exporter"
 153 .IX Subsection "The Basics of Sub::Exporter"
 154 Sub::Exporter builds a custom exporter which can then be installed into your
 155 module.  It builds this method based on configuration passed to its
 156 \&\f(CW\*(C`setup_exporter\*(C'\fR method.
 157 .PP
 158 A very basic use case might look like this:
 159 .PP
 160 .Vb 3
 161 \&  package Addition;
 162 \&  use Sub::Exporter;
 163 \&  Sub::Exporter::setup_exporter({ exports => [ qw(plus) ]});
 164 .Ve
 165 .PP
 166 .Vb 1
 167 \&  sub plus { my ($x, $y) = @_; return $x + $y; }
 168 .Ve
 169 .PP
 170 This would mean that when someone used your Addition module, they could have
 171 its \f(CW\*(C`plus\*(C'\fR routine imported into their package:
 172 .PP
 173 .Vb 1
 174 \&  use Addition qw(plus);
 175 .Ve
 176 .PP
 177 .Vb 1
 178 \&  my $z = plus(2, 2); # this works, because now plus is in the main package
 179 .Ve
 180 .PP
 181 That syntax to set up the exporter, above, is a little verbose, so for the
 182 simple case of just naming some exports, you can write this:
 183 .PP
 184 .Vb 1
 185 \&  use Sub::Exporter \-setup => { exports => [ qw(plus) ] };
 186 .Ve
 187 .PP
 188 \&...which is the same as the original example \*(-- except that now the exporter is
 189 built and installed at compile time.  Well, that and you typed less.
 190 .Sh "Using Export Groups"
 191 .IX Subsection "Using Export Groups"
 192 You can specify whole groups of things that should be exportable together.
 193 These are called groups.  Exporter calls these tags.  To specify groups, you
 194 just pass a \f(CW\*(C`groups\*(C'\fR key in your exporter configuration:
 195 .PP
 196 .Vb 8
 197 \&  package Food;
 198 \&  use Sub::Exporter \-setup => {
 199 \&    exports => [ qw(apple banana beef fluff lox rabbit) ],
 200 \&    groups  => {
 201 \&      fauna  => [ qw(beef lox rabbit) ],
 202 \&      flora  => [ qw(apple banana) ],
 203 \&    }
 204 \&  };
 205 .Ve
 206 .PP
 207 Now, to import all that delicious foreign meat, your consumer needs only to
 208 write:
 209 .PP
 210 .Vb 2
 211 \&  use Food qw(:fauna);
 212 \&  use Food qw(\-fauna);
 213 .Ve
 214 .PP
 215 Either one of the above is acceptable.  A colon is more traditional, but
 216 barewords with a leading colon can't be enquoted by a fat arrow.  We'll see why
 217 that matters later on.
 218 .PP
 219 Groups can contain other groups.  If you include a group name (with the leading
 220 dash or colon) in a group definition, it will be expanded recursively when the
 221 exporter is called.  The exporter will \fBnot\fR recurse into the same group twice
 222 while expanding groups.
 223 .PP
 224 There are two special groups:  \f(CW\*(C`all\*(C'\fR and \f(CW\*(C`default\*(C'\fR.  The \f(CW\*(C`all\*(C'\fR group is
 225 defined by default, and contains all exportable subs.  You can redefine it,
 226 if you want to export only a subset when all exports are requested.  The
 227 \&\f(CW\*(C`default\*(C'\fR group is the set of routines to export when nothing specific is
 228 requested.  By default, there is no \f(CW\*(C`default\*(C'\fR group.
 229 .Sh "Renaming Your Imports"
 230 .IX Subsection "Renaming Your Imports"
 231 Sometimes you want to import something, but you don't like the name as which
 232 it's imported.  Sub::Exporter can rename your imports for you.  If you wanted
 233 to import \f(CW\*(C`lox\*(C'\fR from the Food package, but you don't like the name, you could
 234 write this:
 235 .PP
 236 .Vb 1
 237 \&  use Food lox => { \-as => 'salmon' };
 238 .Ve
 239 .PP
 240 Now you'd get the \f(CW\*(C`lox\*(C'\fR routine, but it would be called salmon in your
 241 package.  You can also rename entire groups by using the \f(CW\*(C`prefix\*(C'\fR option:
 242 .PP
 243 .Vb 1
 244 \&  use Food \-fauna => { \-prefix => 'cute_little_' };
 245 .Ve
 246 .PP
 247 Now you can call your \f(CW\*(C`cute_little_rabbit\*(C'\fR routine.  (You can also call
 248 \&\f(CW\*(C`cute_little_beef\*(C'\fR, but that hardly seems as enticing.)
 249 .PP
 250 When you define groups, you can include renaming.
 251 .PP
 252 .Vb 6
 253 \&  use Sub::Exporter \-setup => {
 254 \&    exports => [ qw(apple banana beef fluff lox rabbit) ],
 255 \&    groups  => {
 256 \&      fauna  => [ qw(beef lox), rabbit => { \-as => 'coney' } ],
 257 \&    }
 258 \&  };
 259 .Ve
 260 .PP
 261 A prefix on a group like that does the right thing.  This is when it's useful
 262 to use a dash instead of a colon to indicate a group: you can put a fat arrow
 263 between the group and its arguments, then.
 264 .PP
 265 .Vb 1
 266 \&  use Food \-fauna => { \-prefix => 'lovely_' };
 267 .Ve
 268 .PP
 269 .Vb 1
 270 \&  eat( lovely_coney ); # this works
 271 .Ve
 272 .PP
 273 Prefixes also apply recursively.  That means that this code works:
 274 .PP
 275 .Vb 7
 276 \&  use Sub::Exporter \-setup => {
 277 \&    exports => [ qw(apple banana beef fluff lox rabbit) ],
 278 \&    groups  => {
 279 \&      fauna   => [ qw(beef lox), rabbit => { \-as => 'coney' } ],
 280 \&      allowed => [ \-fauna => { \-prefix => 'willing_' }, 'banana' ],
 281 \&    }
 282 \&  };
 283 .Ve
 284 .PP
 285 .Vb 1
 286 \&  ...
 287 .Ve
 288 .PP
 289 .Vb 1
 290 \&  use Food \-allowed => { \-prefix => 'any_' };
 291 .Ve
 292 .PP
 293 .Vb 1
 294 \&  $dinner = any_willing_coney; # yum!
 295 .Ve
 296 .PP
 297 Groups can also be passed a \f(CW\*(C`\-suffix\*(C'\fR argument.
 298 .PP
 299 Finally, if the \f(CW\*(C`\-as\*(C'\fR argument to an exported routine is a reference to a
 300 scalar, a reference to the routine will be placed in that scalar.
 301 .Sh "Building Subroutines to Order"
 302 .IX Subsection "Building Subroutines to Order"
 303 Sometimes, you want to export things that you don't have on hand.  You might
 304 want to offer customized routines built to the specification of your consumer;
 305 that's just good business!  With Sub::Exporter, this is easy.
 306 .PP
 307 To offer subroutines to order, you need to provide a generator when you set up
 308 your exporter.  A generator is just a routine that returns a new routine.
 309 perlref is talking about these when it discusses closures and function
 310 templates. The canonical example of a generator builds a unique incrementor;
 311 here's how you'd do that with Sub::Exporter;
 312 .PP
 313 .Vb 5
 314 \&  package Package::Counter;
 315 \&  use Sub::Exporter \-setup => {
 316 \&    exports => [ counter => sub { my $i = 0; sub { $i++ } } ],
 317 \&    groups  => { default => [ qw(counter) ] },
 318 \&  };
 319 .Ve
 320 .PP
 321 Now anyone can use your Package::Counter module and he'll receive a \f(CW\*(C`counter\*(C'\fR
 322 in his package.  It will count up by one, and will never interfere with anyone
 323 else's counter.
 324 .PP
 325 This isn't very useful, though, unless the consumer can explain what he wants.
 326 This is done, in part, by supplying arguments when importing.  The following
 327 example shows how a generator can take and use arguments:
 328 .PP
 329 .Vb 1
 330 \&  package Package::Counter;
 331 .Ve
 332 .PP
 333 .Vb 6
 334 \&  sub _build_counter {
 335 \&    my ($class, $arg) = @_;
 336 \&    $arg ||= {};
 337 \&    my $i = $arg\->{start} || 0;
 338 \&    return sub { $i++ };
 339 \&  }
 340 .Ve
 341 .PP
 342 .Vb 4
 343 \&  use Sub::Exporter \-setup => {
 344 \&    exports => [ counter => \e'_build_counter' ],
 345 \&    groups  => { default => [ qw(counter) ] },
 346 \&  };
 347 .Ve
 348 .PP
 349 Now, the consumer can (if he wants) specify a starting value for his counter:
 350 .PP
 351 .Vb 1
 352 \&  use Package::Counter counter => { start => 10 };
 353 .Ve
 354 .PP
 355 Arguments to a group are passed along to the generators of routines in that
 356 group, but Sub::Exporter arguments \*(-- anything beginning with a dash \*(-- are
 357 never passed in.  When groups are nested, the arguments are merged as the
 358 groups are expanded.
 359 .PP
 360 Notice, too, that in the example above, we gave a reference to a method \fIname\fR
 361 rather than a method \fIimplementation\fR.  By giving the name rather than the
 362 subroutine, we make it possible for subclasses of our \*(L"Package::Counter\*(R" module
 363 to replace the \f(CW\*(C`_build_counter\*(C'\fR method.
 364 .PP
 365 When a generator is called, it is passed four parameters:
 366 .IP "* the invocant on which the exporter was called" 4
 367 .IX Item "the invocant on which the exporter was called"
 368 .PD 0
 369 .IP "* the name of the export being generated (not the name it's being installed as)" 4
 370 .IX Item "the name of the export being generated (not the name it's being installed as)"
 371 .IP "* the arguments supplied for the routine" 4
 372 .IX Item "the arguments supplied for the routine"
 373 .IP "* the collection of generic arguments" 4
 374 .IX Item "the collection of generic arguments"
 375 .PD
 376 .PP
 377 The fourth item is the last major feature that hasn't been covered.
 378 .Sh "Argument Collectors"
 379 .IX Subsection "Argument Collectors"
 380 Sometimes you will want to accept arguments once that can then be available to
 381 any subroutine that you're going to export.  To do this, you specify
 382 collectors, like this:
 383 .PP
 384 .Vb 6
 385 \&  use Menu::Airline
 386 \&  use Sub::Exporter \-setup => {
 387 \&    exports =>  ... ,
 388 \&    groups  =>  ... ,
 389 \&    collectors => [ qw(allergies ethics) ],
 390 \&  };
 391 .Ve
 392 .PP
 393 Collectors look like normal exports in the import call, but they don't do
 394 anything but collect data which can later be passed to generators.  If the
 395 module was used like this:
 396 .PP
 397 .Vb 1
 398 \&  use Menu::Airline allergies => [ qw(peanuts) ], ethics => [ qw(vegan) ];
 399 .Ve
 400 .PP
 401 \&...the consumer would get a salad.  Also, all the generators would be passed,
 402 as their fourth argument, something like this:
 403 .PP
 404 .Vb 1
 405 \&  { allerges => [ qw(peanuts) ], ethics => [ qw(vegan) ] }
 406 .Ve
 407 .PP
 408 Generators may have arguments in their definition, as well.  These must be code
 409 refs that perform validation of the collected values.  They are passed the
 410 collection value and may return true or false.  If they return false, the
 411 exporter will throw an exception.
 412 .Sh "Generating Many Routines in One Scope"
 413 .IX Subsection "Generating Many Routines in One Scope"
 414 Sometimes it's useful to have multiple routines generated in one scope.  This
 415 way they can share lexical data which is otherwise unavailable.  To do this,
 416 you can supply a generator for a group which returns a hashref of names and
 417 code references.  This generator is passed all the usual data, and the group
 418 may receive the usual \f(CW\*(C`\-prefix\*(C'\fR or \f(CW\*(C`\-suffix\*(C'\fR arguments.
 419 .SH "AUTHOR"
 420 .IX Header "AUTHOR"
 421 Ricardo \s-1SIGNES\s0, \f(CW\*(C`<rjbs@cpan.org>\*(C'\fR
 422 .SH "SEE ALSO"
 423 .IX Header "SEE ALSO"
 424 .IP "* Sub::Exporter for complete documentation and references to other exporters." 4
 425 .IX Item "Sub::Exporter for complete documentation and references to other exporters."
 426 .SH "COPYRIGHT"
 427 .IX Header "COPYRIGHT"
 428 Copyright 2007 Ricardo \s-1SIGNES\s0.  This program is free software;  you can
 429 redistribute it and/or modify it under the same terms as Perl itself.