Commit | Line | Data |
3fea05b9 |
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. |