← Index
NYTProf Performance Profile   « block view • line view • sub view »
For 05.Domain_and_Item.t
  Run on Tue May 4 17:21:41 2010
Reported on Tue May 4 17:22:54 2010

File /usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm
Statements Executed 24096
Statement Execution Time 30.5ms
Subroutines — ordered by exclusive time
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
76117.72ms56.1msSub::Exporter::::_do_import Sub::Exporter::_do_import
76115.53ms33.3msSub::Exporter::::default_installer Sub::Exporter::default_installer
886115.37ms15.0msSub::Exporter::::default_generator Sub::Exporter::default_generator
201214.97ms12.3msSub::Exporter::::_expand_groups Sub::Exporter::_expand_groups
7615122.19ms73.1msSub::Exporter::::__ANON__[:756] Sub::Exporter::__ANON__[:756]
125112.01ms10.7msSub::Exporter::::_expand_group Sub::Exporter::_expand_group
1136211.84ms1.84msSub::Exporter::::_group_name Sub::Exporter::_group_name
76111.35ms2.00msSub::Exporter::::_collect_collections Sub::Exporter::_collect_collections
7611587µs587µsSub::Exporter::::_mk_collection_builder Sub::Exporter::_mk_collection_builder
111549µs3.41msSub::Exporter::::BEGIN@7 Sub::Exporter::BEGIN@7
1311534µs4.96msSub::Exporter::::_rewrite_build_config Sub::Exporter::_rewrite_build_config
1311167µs167µsSub::Exporter::::_key_intersection Sub::Exporter::_key_intersection
1343129µs5.09msSub::Exporter::::build_exporter Sub::Exporter::build_exporter
382372µs72µsDevel::GlobalDestruction::::in_global_destructionDevel::GlobalDestruction::in_global_destruction (xsub)
131158µs62µsSub::Exporter::::_assert_collector_names_ok Sub::Exporter::_assert_collector_names_ok
21137µs59µsSub::Exporter::::__ANON__[:544] Sub::Exporter::__ANON__[:544]
22227µs583µsSub::Exporter::::setup_exporter Sub::Exporter::setup_exporter
11127µs27µsDevel::GlobalDestruction::::BEGIN@1Devel::GlobalDestruction::BEGIN@1
21120µs20µsSub::Exporter::::_setup Sub::Exporter::_setup
11113µs13µsSub::Exporter::::BEGIN@636 Sub::Exporter::BEGIN@636
2119µs287µsSub::Exporter::::__ANON__[:937] Sub::Exporter::__ANON__[:937]
1117µs19µsSub::Exporter::::BEGIN@9 Sub::Exporter::BEGIN@9
1116µs9µsDevel::GlobalDestruction::::BEGIN@2Devel::GlobalDestruction::BEGIN@2
1116µs15µsDevel::GlobalDestruction::::BEGIN@3Devel::GlobalDestruction::BEGIN@3
1113µs3µsSub::Exporter::::BEGIN@8 Sub::Exporter::BEGIN@8
1123µs3µsSub::Exporter::::CORE:match Sub::Exporter::CORE:match (opcode)
1113µs3µsSub::Exporter::::BEGIN@6 Sub::Exporter::BEGIN@6
0000s0sSub::Exporter::::__ANON__[:773] Sub::Exporter::__ANON__[:773]
0000s0sSub::Exporter::::default_exporter Sub::Exporter::default_exporter
Call graph for these subroutines as a Graphviz dot language file.
Line State
ments
Time
on line
Calls Time
in subs
Code
1335µs127µs
# spent 27µs within Devel::GlobalDestruction::BEGIN@1 which was called # once (27µs+0s) by Devel::GlobalDestruction::BEGIN@26 at line 1
use 5.006;
# spent 27µs making 1 call to Devel::GlobalDestruction::BEGIN@1
2317µs212µs
# spent 9µs (6+3) within Devel::GlobalDestruction::BEGIN@2 which was called # once (6µs+3µs) by Devel::GlobalDestruction::BEGIN@26 at line 2
use strict;
# spent 9µs making 1 call to Devel::GlobalDestruction::BEGIN@2 # spent 3µs making 1 call to strict::import
3322µs224µs
# spent 15µs (6+9) within Devel::GlobalDestruction::BEGIN@3 which was called # once (6µs+9µs) by Devel::GlobalDestruction::BEGIN@26 at line 3
use warnings;
# spent 15µs making 1 call to Devel::GlobalDestruction::BEGIN@3 # spent 9µs making 1 call to warnings::import
4package Sub::Exporter;
5
6315µs13µs
# spent 3µs within Sub::Exporter::BEGIN@6 which was called # once (3µs+0s) by Devel::GlobalDestruction::BEGIN@26 at line 6
use Carp ();
# spent 3µs making 1 call to Sub::Exporter::BEGIN@6
73106µs13.41ms
# spent 3.41ms (549µs+2.86) within Sub::Exporter::BEGIN@7 which was called # once (549µs+2.86ms) by Devel::GlobalDestruction::BEGIN@26 at line 7
use Data::OptList ();
# spent 3.41ms making 1 call to Sub::Exporter::BEGIN@7
8318µs13µs
# spent 3µs within Sub::Exporter::BEGIN@8 which was called # once (3µs+0s) by Devel::GlobalDestruction::BEGIN@26 at line 8
use Params::Util ();
# spent 3µs making 1 call to Sub::Exporter::BEGIN@8
93902µs231µs
# spent 19µs (7+12) within Sub::Exporter::BEGIN@9 which was called # once (7µs+12µs) by Devel::GlobalDestruction::BEGIN@26 at line 9
use Sub::Install 0.92 ();
# spent 19µs making 1 call to Sub::Exporter::BEGIN@9 # spent 12µs making 1 call to UNIVERSAL::VERSION
10
11=head1 NAME
12
13Sub::Exporter - a sophisticated exporter for custom-built routines
14
15=head1 VERSION
16
17version 0.982
18
19=cut
20
211800nsour $VERSION = '0.982';
22
23=head1 SYNOPSIS
24
25Sub::Exporter must be used in two places. First, in an exporting module:
26
27 # in the exporting module:
28 package Text::Tweaker;
29 use Sub::Exporter -setup => {
30 exports => [
31 qw(squish titlecase), # always works the same way
32 reformat => \&build_reformatter, # generator to build exported function
33 trim => \&build_trimmer,
34 indent => \&build_indenter,
35 ],
36 collectors => [ 'defaults' ],
37 };
38
39Then, in an importing module:
40
41 # in the importing module:
42 use Text::Tweaker
43 'squish',
44 indent => { margin => 5 },
45 reformat => { width => 79, justify => 'full', -as => 'prettify_text' },
46 defaults => { eol => 'CRLF' };
47
48With this setup, the importing module ends up with three routines: C<squish>,
49C<indent>, and C<prettify_text>. The latter two have been built to the
50specifications of the importer -- they are not just copies of the code in the
51exporting package.
52
53=head1 DESCRIPTION
54
55B<ACHTUNG!> If you're not familiar with Exporter or exporting, read
56L<Sub::Exporter::Tutorial> first!
57
58=head2 Why Generators?
59
60The biggest benefit of Sub::Exporter over existing exporters (including the
61ubiquitous Exporter.pm) is its ability to build new coderefs for export, rather
62than to simply export code identical to that found in the exporting package.
63
64If your module's consumers get a routine that works like this:
65
66 use Data::Analyze qw(analyze);
67 my $value = analyze($data, $tolerance, $passes);
68
69and they constantly pass only one or two different set of values for the
70non-C<$data> arguments, your code can benefit from Sub::Exporter. By writing a
71simple generator, you can let them do this, instead:
72
73 use Data::Analyze
74 analyze => { tolerance => 0.10, passes => 10, -as => analyze10 },
75 analyze => { tolerance => 0.15, passes => 50, -as => analyze50 };
76
77 my $value = analyze10($data);
78
79The generator for that would look something like this:
80
81 sub build_analyzer {
82 my ($class, $name, $arg) = @_;
83
84 return sub {
85 my $data = shift;
86 my $tolerance = shift || $arg->{tolerance};
87 my $passes = shift || $arg->{passes};
88
89 analyze($data, $tolerance, $passes);
90 }
91 }
92
93Your module's user now has to do less work to benefit from it -- and remember,
94you're often your own user! Investing in customized subroutines is an
95investment in future laziness.
96
97This also avoids a common form of ugliness seen in many modules: package-level
98configuration. That is, you might have seen something like the above
99implemented like so:
100
101 use Data::Analyze qw(analyze);
102 $Data::Analyze::default_tolerance = 0.10;
103 $Data::Analyze::default_passes = 10;
104
105This might save time, until you have multiple modules using Data::Analyze.
106Because there is only one global configuration, they step on each other's toes
107and your code begins to have mysterious errors.
108
109Generators can also allow you to export class methods to be called as
110subroutines:
111
112 package Data::Methodical;
113 use Sub::Exporter -setup => { exports => { some_method => \&_curry_class } };
114
115 sub _curry_class {
116 my ($class, $name) = @_;
117 sub { $class->$name(@_); };
118 }
119
120Because of the way that exporters and Sub::Exporter work, any package that
121inherits from Data::Methodical can inherit its exporter and override its
122C<some_method>. If a user imports C<some_method> from that package, he'll
123receive a subroutine that calls the method on the subclass, rather than on
124Data::Methodical itself.
125
126=head2 Other Customizations
127
128Building custom routines with generators isn't the only way that Sub::Exporters
129allows the importing code to refine its use of the exported routines. They may
130also be renamed to avoid naming collisions.
131
132Consider the following code:
133
134 # this program determines to which circle of Hell you will be condemned
135 use Morality qw(sin virtue); # for calculating viciousness
136 use Math::Trig qw(:all); # for dealing with circles
137
138The programmer has inadvertantly imported two C<sin> routines. The solution,
139in Exporter.pm-based modules, would be to import only one and then call the
140other by its fully-qualified name. Alternately, the importer could write a
141routine that did so, or could mess about with typeglobs.
142
143How much easier to write:
144
145 # this program determines to which circle of Hell you will be condemned
146 use Morality qw(virtue), sin => { -as => 'offense' };
147 use Math::Trig -all => { -prefix => 'trig_' };
148
149and to have at one's disposal C<offense> and C<trig_sin> -- not to mention
150C<trig_cos> and C<trig_tan>.
151
152=head1 EXPORTER CONFIGURATION
153
154You can configure an exporter for your package by using Sub::Exporter like so:
155
156 package Tools;
157 use Sub::Exporter
158 -setup => { exports => [ qw(function1 function2 function3) ] };
159
160This is the simplest way to use the exporter, and is basically equivalent to
161this:
162
163 package Tools;
164 use base qw(Exporter);
165 our @EXPORT_OK = qw(function1 function2 function2);
166
167Any basic use of Sub::Exporter will look like this:
168
169 package Tools;
170 use Sub::Exporter -setup => \%config;
171
172The following keys are valid in C<%config>:
173
174 exports - a list of routines to provide for exporting; each routine may be
175 followed by generator
176 groups - a list of groups to provide for exporting; each must be followed by
177 either (a) a list of exports, possibly with arguments for each
178 export, or (b) a generator
179
180 collectors - a list of names into which values are collected for use in
181 routine generation; each name may be followed by a validator
182
183In addition to the basic options above, a few more advanced options may be
184passed:
185
186 into_level - how far up the caller stack to look for a target (default 0)
187 into - an explicit target (package) into which to export routines
188
189In other words: Sub::Exporter installs a C<import> routine which, when called,
190exports routines to the calling namespace. The C<into> and C<into_level>
191options change where those exported routines are installed.
192
193 generator - a callback used to produce the code that will be installed
194 default: Sub::Exporter::default_generator
195
196 installer - a callback used to install the code produced by the generator
197 default: Sub::Exporter::default_installer
198
199For information on how these callbacks are used, see the documentation for
200C<L</default_generator>> and C<L</default_installer>>.
201
202=head2 Export Configuration
203
204The C<exports> list may be provided as an array reference or a hash reference.
205The list is processed in such a way that the following are equivalent:
206
207 { exports => [ qw(foo bar baz), quux => \&quux_generator ] }
208
209 { exports =>
210 { foo => undef, bar => undef, baz => undef, quux => \&quux_generator } }
211
212Generators are code that return coderefs. They are called with four
213parameters:
214
215 $class - the class whose exporter has been called (the exporting class)
216 $name - the name of the export for which the routine is being build
217 \%arg - the arguments passed for this export
218 \%col - the collections for this import
219
220Given the configuration in the L</SYNOPSIS>, the following C<use> statement:
221
222 use Text::Tweaker
223 reformat => { -as => 'make_narrow', width => 33 },
224 defaults => { eol => 'CR' };
225
226would result in the following call to C<&build_reformatter>:
227
228 my $code = build_reformatter(
229 'Text::Tweaker',
230 'reformat',
231 { width => 33 }, # note that -as is not passed in
232 { defaults => { eol => 'CR' } },
233 );
234
235The returned coderef (C<$code>) would then be installed as C<make_narrow> in the
236calling package.
237
238Instead of providing a coderef in the configuration, a reference to a method
239name may be provided. This method will then be called on the invocant of the
240C<import> method. (In this case, we do not pass the C<$class> parameter, as it
241would be redundant.)
242
243=head2 Group Configuration
244
245The C<groups> list can be passed in the same forms as C<exports>. Groups must
246have values to be meaningful, which may either list exports that make up the
247group (optionally with arguments) or may provide a way to build the group.
248
249The simpler case is the first: a group definition is a list of exports. Here's
250the example that could go in exporter in the L</SYNOPSIS>.
251
252 groups => {
253 default => [ qw(reformat) ],
254 shorteners => [ qw(squish trim) ],
255 email_safe => [
256 'indent',
257 reformat => { -as => 'email_format', width => 72 }
258 ],
259 },
260
261Groups are imported by specifying their name prefixed be either a dash or a
262colon. This line of code would import the C<shorteners> group:
263
264 use Text::Tweaker qw(-shorteners);
265
266Arguments passed to a group when importing are merged into the groups options
267and passed to any relevant generators. Groups can contain other groups, but
268looping group structures are ignored.
269
270The other possible value for a group definition, a coderef, allows one
271generator to build several exportable routines simultaneously. This is useful
272when many routines must share enclosed lexical variables. The coderef must
273return a hash reference. The keys will be used as export names and the values
274are the subs that will be exported.
275
276This example shows a simple use of the group generator.
277
278 package Data::Crypto;
279 use Sub::Exporter -setup => { groups => { cipher => \&build_cipher_group } };
280
281 sub build_cipher_group {
282 my ($class, $group, $arg) = @_;
283 my ($encode, $decode) = build_codec($arg->{secret});
284 return { cipher => $encode, decipher => $decode };
285 }
286
287The C<cipher> and C<decipher> routines are built in a group because they are
288built together by code which encloses their secret in their environment.
289
290=head3 Default Groups
291
292If a module that uses Sub::Exporter is C<use>d with no arguments, it will try
293to export the group named C<default>. If that group has not been specifically
294configured, it will be empty, and nothing will happen.
295
296Another group is also created if not defined: C<all>. The C<all> group
297contains all the exports from the exports list.
298
299=head2 Collector Configuration
300
301The C<collectors> entry in the exporter configuration gives names which, when
302found in the import call, have their values collected and passed to every
303generator.
304
305For example, the C<build_analyzer> generator that we saw above could be
306rewritten as:
307
308 sub build_analyzer {
309 my ($class, $name, $arg, $col) = @_;
310
311 return sub {
312 my $data = shift;
313 my $tolerance = shift || $arg->{tolerance} || $col->{defaults}{tolerance};
314 my $passes = shift || $arg->{passes} || $col->{defaults}{passes};
315
316 analyze($data, $tolerance, $passes);
317 }
318 }
319
320That would allow the import to specify global defaults for his imports:
321
322 use Data::Analyze
323 'analyze',
324 analyze => { tolerance => 0.10, -as => analyze10 },
325 analyze => { tolerance => 0.15, passes => 50, -as => analyze50 },
326 defaults => { passes => 10 };
327
328 my $A = analyze10($data); # equivalent to analyze($data, 0.10, 10);
329 my $C = analyze50($data); # equivalent to analyze($data, 0.15, 10);
330 my $B = analyze($data, 0.20); # equivalent to analyze($data, 0.20, 10);
331
332If values are provided in the C<collectors> list during exporter setup, they
333must be code references, and are used to validate the importer's values. The
334validator is called when the collection is found, and if it returns false, an
335exception is thrown. We could ensure that no one tries to set a global data
336default easily:
337
338 collectors => { defaults => sub { return (exists $_[0]->{data}) ? 0 : 1 } }
339
340Collector coderefs can also be used as hooks to perform arbitrary actions
341before anything is exported.
342
343When the coderef is called, it is passed the value of the collection and a
344hashref containing the following entries:
345
346 name - the name of the collector
347 config - the exporter configuration (hashref)
348 import_args - the arguments passed to the exporter, sans collections (aref)
349 class - the package on which the importer was called
350 into - the package into which exports will be exported
351
352Collectors with all-caps names (that is, made up of underscore or capital A
353through Z) are reserved for special use. The only currently implemented
354special collector is C<INIT>, whose hook (if present in the exporter
355configuration) is always run before any other hook.
356
357=head1 CALLING THE EXPORTER
358
359Arguments to the exporter (that is, the arguments after the module name in a
360C<use> statement) are parsed as follows:
361
362First, the collectors gather any collections found in the arguments. Any
363reference type may be given as the value for a collector. For each collection
364given in the arguments, its validator (if any) is called.
365
366Next, groups are expanded. If the group is implemented by a group generator,
367the generator is called. There are two special arguments which, if given to a
368group, have special meaning:
369
370 -prefix - a string to prepend to any export imported from this group
371 -suffix - a string to append to any export imported from this group
372
373Finally, individual export generators are called and all subs, generated or
374otherwise, are installed in the calling package. There is only one special
375argument for export generators:
376
377 -as - where to install the exported sub
378
379Normally, C<-as> will contain an alternate name for the routine. It may,
380however, contain a reference to a scalar. If that is the case, a reference the
381generated routine will be placed in the scalar referenced by C<-as>. It will
382not be installed into the calling package.
383
384=head2 Special Exporter Arguments
385
386The generated exporter accept some special options, which may be passed as the
387first argument, in a hashref.
388
389These options are:
390
391 into_level
392 into
393 generator
394 installer
395
396These override the same-named configuration options described in L</EXPORTER
397CONFIGURATION>.
398
399=cut
400
401# Given a potential import name, this returns the group name -- if it's got a
402# group prefix.
403
# spent 1.84ms within Sub::Exporter::_group_name which was called 1136 times, avg 2µs/call: # 1011 times (1.65ms+0s) by Sub::Exporter::_expand_groups at line 421, avg 2µs/call # 125 times (187µs+0s) by Sub::Exporter::_expand_group at line 461, avg 1µs/call
sub _group_name {
40425222.51ms my ($name) = @_;
405
406 return if (index q{-:}, (substr $name, 0, 1)) == -1;
407 return substr $name, 1;
408}
409
410# \@groups is a canonicalized opt list of exports and groups this returns
411# another canonicalized opt list with groups replaced with relevant exports.
412# \%seen is groups we've already expanded and can ignore.
413# \%merge is merged options from the group we're descending through.
414
# spent 12.3ms (4.97+7.36) within Sub::Exporter::_expand_groups which was called 201 times, avg 61µs/call: # 125 times (3.69ms+-3.69ms) by Sub::Exporter::_expand_group at line 509, avg 0s/call # 76 times (1.28ms+11.0ms) by Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:756] at line 742, avg 162µs/call
sub _expand_groups {
41512061.19ms my ($class, $config, $groups, $collection, $seen, $merge) = @_;
416 $seen ||= {};
417 $merge ||= {};
418 my @groups = @$groups;
419
420 for my $i (reverse 0 .. $#groups) {
42121472.46ms10111.65ms if (my $group_name = _group_name($groups[$i][0])) {
# spent 1.65ms making 1011 calls to Sub::Exporter::_group_name, avg 2µs/call
422 my $seen = { %$seen }; # faux-dynamic scoping
423
424 splice @groups, $i, 1,
# spent 18.0ms making 125 calls to Sub::Exporter::_expand_group, avg 144µs/call, recursion: max depth 1, time 7.32ms
425 _expand_group($class, $config, $groups[$i], $collection, $seen, $merge);
426 } else {
427 # there's nothing to munge in this export's args
428 next unless my %merge = %$merge;
429
430 # we have things to merge in; do so
431 my $prefix = (delete $merge{-prefix}) || '';
432 my $suffix = (delete $merge{-suffix}) || '';
433
434 if (
435 Params::Util::_CODELIKE($groups[$i][1]) ## no critic Private
436 or
437 Params::Util::_SCALAR0($groups[$i][1]) ## no critic Private
438 ) {
439 # this entry was build by a group generator
440 $groups[$i][0] = $prefix . $groups[$i][0] . $suffix;
441 } else {
442 my $as
443 = ref $groups[$i][1]{-as} ? $groups[$i][1]{-as}
444 : $groups[$i][1]{-as} ? $prefix . $groups[$i][1]{-as} . $suffix
445 : $prefix . $groups[$i][0] . $suffix;
446
447 $groups[$i][1] = { %{ $groups[$i][1] }, %merge, -as => $as };
448 }
449 }
450 }
451
452 return \@groups;
453}
454
455# \@group is a name/value pair from an opt list.
456
# spent 10.7ms (2.01+8.70) within Sub::Exporter::_expand_group which was called 125 times, avg 86µs/call: # 125 times (2.01ms+8.70ms) by Sub::Exporter::_expand_groups at line 424, avg 86µs/call
sub _expand_group {
45711251.07ms my ($class, $config, $group, $collection, $seen, $merge) = @_;
458 $merge ||= {};
459
460 my ($group_name, $group_arg) = @$group;
461 $group_name = _group_name($group_name);
# spent 187µs making 125 calls to Sub::Exporter::_group_name, avg 1µs/call
462
463 Carp::croak qq(group "$group_name" is not exported by the $class module)
464 unless exists $config->{groups}{$group_name};
465
466 return if $seen->{$group_name}++;
467
468 if (ref $group_arg) {
469 my $prefix = (delete $merge->{-prefix}||'') . ($group_arg->{-prefix}||'');
470 my $suffix = ($group_arg->{-suffix}||'') . (delete $merge->{-suffix}||'');
471 $merge = {
472 %$merge,
473 %$group_arg,
474 ($prefix ? (-prefix => $prefix) : ()),
475 ($suffix ? (-suffix => $suffix) : ()),
476 };
477 }
478
479 my $exports = $config->{groups}{$group_name};
480
481250692µs250187µs if (
# spent 116µs making 125 calls to Params::Util::_CODELIKE, avg 929ns/call # spent 71µs making 125 calls to Params::Util::_SCALAR0, avg 565ns/call
482 Params::Util::_CODELIKE($exports) ## no critic Private
483 or
484 Params::Util::_SCALAR0($exports) ## no critic Private
485 ) {
486 # I'm not very happy with this code for hiding -prefix and -suffix, but
487 # it's needed, and I'm not sure, offhand, how to make it better.
488 # -- rjbs, 2006-12-05
489 my $group_arg = $merge ? { %$merge } : {};
490 delete $group_arg->{-prefix};
491 delete $group_arg->{-suffix};
492
493 my $group = Params::Util::_CODELIKE($exports) ## no critic Private
494 ? $exports->($class, $group_name, $group_arg, $collection)
495 : $class->$$exports($group_name, $group_arg, $collection);
496
497 Carp::croak qq(group generator "$group_name" did not return a hashref)
498 if ref $group ne 'HASH';
499
500 my $stuff = [ map { [ $_ => $group->{$_} ] } keys %$group ];
501 return @{
502 _expand_groups($class, $config, $stuff, $collection, $seen, $merge)
503 };
504 } else {
505 $exports
# spent 3.32ms making 125 calls to Data::OptList::mkopt, avg 27µs/call
506 = Data::OptList::mkopt($exports, "$group_name exports");
507
508 return @{
509 _expand_groups($class, $config, $exports, $collection, $seen, $merge)
# spent 12.3ms making 125 calls to Sub::Exporter::_expand_groups, avg 99µs/call, recursion: max depth 2, time 12.3ms
510 };
511 }
512}
513
514
# spent 587µs within Sub::Exporter::_mk_collection_builder which was called 76 times, avg 8µs/call: # 76 times (587µs+0s) by Sub::Exporter::_collect_collections at line 560, avg 8µs/call
sub _mk_collection_builder {
515304655µs my ($col, $etc) = @_;
516 my ($config, $import_args, $class, $into) = @$etc;
517
518 my %seen;
519
# spent 59µs (37+22) within Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:544] which was called 2 times, avg 29µs/call: # 2 times (37µs+22µs) by Sub::Exporter::_collect_collections at line 562, avg 29µs/call
sub {
5201013µs my ($collection) = @_;
521 my ($name, $value) = @$collection;
522
523 Carp::croak "collection $name provided multiple times in import"
524 if $seen{ $name }++;
525
526621µs if (ref(my $hook = $config->{collectors}{$name})) {
527 my $arg = {
528 name => $name,
529 config => $config,
530 import_args => $import_args,
531 class => $class,
532 into => $into,
533 };
534
535 my $error_msg = "collection $name failed validation";
53623µs22µs if (Params::Util::_SCALAR0($hook)) { ## no critic Private
# spent 2µs making 2 calls to Params::Util::_SCALAR0, avg 800ns/call
537 Carp::croak $error_msg unless $class->$$hook($value, $arg);
538 } else {
539 Carp::croak $error_msg unless $hook->($value, $arg);
# spent 20µs making 2 calls to Sub::Exporter::_setup, avg 10µs/call
540 }
541 }
542
543 $col->{ $name } = $value;
544 }
545}
546
547# Given a config and pre-canonicalized importer args, remove collections from
548# the args and return them.
549
# spent 2.00ms (1.35+645µs) within Sub::Exporter::_collect_collections which was called 76 times, avg 26µs/call: # 76 times (1.35ms+645µs) by Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:756] at line 740, avg 26µs/call
sub _collect_collections {
5505321.30ms my ($config, $import_args, $class, $into) = @_;
551
552 my @collections
553 = map { splice @$import_args, $_, 1 }
554 grep { exists $config->{collectors}{ $import_args->[$_][0] } }
555 reverse 0 .. $#$import_args;
556
557 unshift @collections, [ INIT => {} ] if $config->{collectors}{INIT};
558
559 my $col = {};
560 my $builder = _mk_collection_builder($col, \@_);
# spent 587µs making 76 calls to Sub::Exporter::_mk_collection_builder, avg 8µs/call
561 for my $collection (@collections) {
56223µs259µs $builder->($collection)
# spent 59µs making 2 calls to Sub::Exporter::__ANON__[Sub/Exporter.pm:544], avg 29µs/call
563 }
564
565 return $col;
566}
567
568=head1 SUBROUTINES
569
570=head2 setup_exporter
571
572This routine builds and installs an C<import> routine. It is called with one
573argument, a hashref containing the exporter configuration. Using this, it
574builds an exporter and installs it into the calling package with the name
575"import." In addition to the normal exporter configuration, a few named
576arguments may be passed in the hashref:
577
578 into - into what package should the exporter be installed
579 into_level - into what level up the stack should the exporter be installed
580 as - what name should the installed exporter be given
581
582By default the exporter is installed with the name C<import> into the immediate
583caller of C<setup_exporter>. In other words, if your package calls
584C<setup_exporter> without providing any of the three above arguments, it will
585have an C<import> routine installed.
586
587Providing both C<into> and C<into_level> will cause an exception to be thrown.
588
589The exporter is built by C<L</build_exporter>>.
590
591=cut
592
593
# spent 583µs (27+556) within Sub::Exporter::setup_exporter which was called 2 times, avg 292µs/call: # once (13µs+279µs) by Moose::Meta::Attribute::BEGIN@17 at line 31 of Moose/Util.pm # once (14µs+277µs) by Devel::GlobalDestruction::BEGIN@26 at line 938
sub setup_exporter {
5941223µs my ($config) = @_;
595
596 Carp::croak 'into and into_level may not both be supplied to exporter'
597 if exists $config->{into} and exists $config->{into_level};
598
599 my $as = delete $config->{as} || 'import';
600 my $into
601 = exists $config->{into} ? delete $config->{into}
602 : exists $config->{into_level} ? caller(delete $config->{into_level})
603 : caller(0);
604
605 my $import = build_exporter($config);
# spent 434µs making 2 calls to Sub::Exporter::build_exporter, avg 217µs/call
606
607 Sub::Install::reinstall_sub({
# spent 122µs making 2 calls to Sub::Install::__ANON__[Sub/Install.pm:132], avg 61µs/call
608 code => $import,
609 into => $into,
610 as => $as,
611 });
612}
613
614=head2 build_exporter
615
616Given a standard exporter configuration, this routine builds and returns an
617exporter -- that is, a subroutine that can be installed as a class method to
618perform exporting on request.
619
620Usually, this method is called by C<L</setup_exporter>>, which then installs
621the exporter as a package's import routine.
622
623=cut
624
625
# spent 167µs within Sub::Exporter::_key_intersection which was called 13 times, avg 13µs/call: # 13 times (167µs+0s) by Sub::Exporter::_rewrite_build_config at line 681, avg 13µs/call
sub _key_intersection {
62639170µs my ($x, $y) = @_;
627 my %seen = map { $_ => 1 } keys %$x;
628 my @names = grep { $seen{$_} } keys %$y;
629}
630
631# Given the config passed to setup_exporter, which contains sugary opt list
632# data, rewrite the opt lists into hashes, catch a few kinds of invalid
633# configurations, and set up defaults. Since the config is a reference, it's
634# rewritten in place.
6351200nsmy %valid_config_key;
636
# spent 13µs within Sub::Exporter::BEGIN@636 which was called # once (13µs+0s) by Devel::GlobalDestruction::BEGIN@26 at line 641
BEGIN {
637 %valid_config_key =
638115µs map { $_ => 1 }
639 qw(as collectors installer generator exports groups into into_level),
640 qw(exporter), # deprecated
64111.01ms113µs}
# spent 13µs making 1 call to Sub::Exporter::BEGIN@636
642
643
# spent 62µs (58+3) within Sub::Exporter::_assert_collector_names_ok which was called 13 times, avg 5µs/call: # 13 times (58µs+3µs) by Sub::Exporter::_rewrite_build_config at line 679, avg 5µs/call
sub _assert_collector_names_ok {
6442665µs my ($collectors) = @_;
645
64618µs13µs for my $reserved_name (grep { /\A[_A-Z]+\z/ } keys %$collectors) {
# spent 3µs making 1 call to Sub::Exporter::CORE:match
647 Carp::croak "unknown reserved collector name: $reserved_name"
648 if $reserved_name ne 'INIT';
649 }
650}
651
652
# spent 4.96ms (534µs+4.43) within Sub::Exporter::_rewrite_build_config which was called 13 times, avg 382µs/call: # 13 times (534µs+4.43ms) by Sub::Exporter::build_exporter at line 709, avg 382µs/call
sub _rewrite_build_config {
653169324µs my ($config) = @_;
654
655 if (my @keys = grep { not exists $valid_config_key{$_} } keys %$config) {
656 Carp::croak "unknown options (@keys) passed to Sub::Exporter";
657 }
658
659 Carp::croak q(into and into_level may not both be supplied to exporter)
660 if exists $config->{into} and exists $config->{into_level};
661
662 # XXX: Remove after deprecation period.
663 if ($config->{exporter}) {
664 Carp::cluck "'exporter' argument to build_exporter is deprecated. Use 'installer' instead; the semantics are identical.";
665 $config->{installer} = delete $config->{exporter};
666 }
667
668 Carp::croak q(into and into_level may not both be supplied to exporter)
669 if exists $config->{into} and exists $config->{into_level};
670
671 for (qw(exports collectors)) {
67226130µs263.80ms $config->{$_} = Data::OptList::mkopt_hash(
# spent 3.80ms making 26 calls to Data::OptList::mkopt_hash, avg 146µs/call
673 $config->{$_},
674 $_,
675 [ 'CODE', 'SCALAR' ],
676 );
677 }
678
679 _assert_collector_names_ok($config->{collectors});
# spent 62µs making 13 calls to Sub::Exporter::_assert_collector_names_ok, avg 5µs/call
680
681 if (my @names = _key_intersection(@$config{qw(exports collectors)})) {
# spent 167µs making 13 calls to Sub::Exporter::_key_intersection, avg 13µs/call
682 Carp::croak "names (@names) used in both collections and exports";
683 }
684
685 $config->{groups} = Data::OptList::mkopt_hash(
# spent 401µs making 13 calls to Data::OptList::mkopt_hash, avg 31µs/call
686 $config->{groups},
687 'groups',
688 [
689 'HASH', # standard opt list
690 'ARRAY', # standard opt list
691 'CODE', # group generator
692 'SCALAR', # name of group generation method
693 ]
694 );
695
696 # by default, export nothing
697 $config->{groups}{default} ||= [];
698
699 # by default, build an all-inclusive 'all' group
700 $config->{groups}{all} ||= [ keys %{ $config->{exports} } ];
701
702 $config->{generator} ||= \&default_generator;
703 $config->{installer} ||= \&default_installer;
704}
705
706
# spent 5.09ms (129µs+4.96) within Sub::Exporter::build_exporter which was called 13 times, avg 392µs/call: # 5 times (56µs+1.59ms) by Moose::Exporter::build_import_methods at line 52 of Moose/Exporter.pm, avg 329µs/call # 4 times (40µs+2.70ms) by MooseX::Types::Base::import at line 90 of MooseX/Types/Base.pm, avg 684µs/call # 2 times (16µs+418µs) by Sub::Exporter::setup_exporter at line 605, avg 217µs/call # 2 times (17µs+261µs) by Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:937] at line 937, avg 139µs/call
sub build_exporter {
70752125µs my ($config) = @_;
708
709 _rewrite_build_config($config);
# spent 4.96ms making 13 calls to Sub::Exporter::_rewrite_build_config, avg 382µs/call
710
711
# spent 73.1ms (2.19+70.9) within Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:756] which was called 76 times, avg 962µs/call: # 59 times (1.70ms+61.8ms) by Moose::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/darwin-2level/Moose/Exporter.pm:389] at line 382 of Moose/Exporter.pm, avg 1.08ms/call # 4 times (141µs+7.04ms) by MooseX::Types::Base::import at line 114 of MooseX/Types/Base.pm, avg 1.80ms/call # once (23µs+350µs) by B::Hooks::EndOfScope::BEGIN@11 at line 11 of B/Hooks/EndOfScope.pm # once (26µs+286µs) by Devel::GlobalDestruction::BEGIN@26 at line 26 of Devel/GlobalDestruction.pm # once (36µs+199µs) by Moose::Meta::Role::BEGIN@10 at line 10 of Moose/Meta/Role.pm # once (34µs+167µs) by Moose::Meta::Role::Application::ToClass::BEGIN@7 at line 7 of Moose/Meta/Role/Application/ToClass.pm # once (23µs+154µs) by namespace::clean::BEGIN@14 at line 14 of namespace/clean.pm # once (27µs+142µs) by Moose::Meta::TypeConstraint::DuckType::BEGIN@9 at line 9 of Moose/Meta/TypeConstraint/DuckType.pm # once (35µs+132µs) by Moose::Exporter::BEGIN@14 at line 14 of Moose/Exporter.pm # once (36µs+120µs) by Moose::Util::BEGIN@7 at line 7 of Moose/Util.pm # once (21µs+114µs) by Class::MOP::Class::BEGIN@15 at line 15 of Class/MOP/Class.pm # once (23µs+112µs) by MooseX::Types::Base::BEGIN@12 at line 12 of MooseX/Types/Base.pm # once (20µs+111µs) by Moose::Meta::Role::BEGIN@21 at line 21 of Moose/Meta/Role.pm # once (25µs+89µs) by Moose::Meta::Role::Method::Conflicting::BEGIN@7 at line 7 of Moose/Meta/Role/Method/Conflicting.pm # once (28µs+70µs) by Moose::Role::BEGIN@8 at line 8 of Moose/Role.pm
my $import = sub {
7129121.83ms my ($class) = shift;
713
714 # XXX: clean this up -- rjbs, 2006-03-16
715 my $special = (ref $_[0]) ? shift(@_) : {};
716 Carp::croak q(into and into_level may not both be supplied to exporter)
717 if exists $special->{into} and exists $special->{into_level};
718
719 if ($special->{exporter}) {
720 Carp::cluck "'exporter' special import argument is deprecated. Use 'installer' instead; the semantics are identical.";
721 $special->{installer} = delete $special->{exporter};
722 }
723
724 my $into
725 = defined $special->{into} ? delete $special->{into}
726 : defined $special->{into_level} ? caller(delete $special->{into_level})
727 : defined $config->{into} ? $config->{into}
728 : defined $config->{into_level} ? caller($config->{into_level})
729 : caller(0);
730
731 my $generator = delete $special->{generator} || $config->{generator};
732 my $installer = delete $special->{installer} || $config->{installer};
733
734 # this builds a AOA, where the inner arrays are [ name => value_ref ]
735 my $import_args = Data::OptList::mkopt([ @_ ]);
# spent 554µs making 76 calls to Data::OptList::mkopt, avg 7µs/call
736
737 # is this right? defaults first or collectors first? -- rjbs, 2006-06-24
738 $import_args = [ [ -default => undef ] ] unless @$import_args;
739
740 my $collection = _collect_collections($config, $import_args, $class, $into);
# spent 2.00ms making 76 calls to Sub::Exporter::_collect_collections, avg 26µs/call
741
742 my $to_import = _expand_groups($class, $config, $import_args, $collection);
# spent 12.3ms making 76 calls to Sub::Exporter::_expand_groups, avg 162µs/call
743
744 # now, finally $import_arg is really the "to do" list
745 _do_import(
# spent 56.1ms making 76 calls to Sub::Exporter::_do_import, avg 738µs/call
746 {
747 class => $class,
748 col => $collection,
749 config => $config,
750 into => $into,
751 generator => $generator,
752 installer => $installer,
753 },
754 $to_import,
755 );
756 };
757
758 return $import;
759}
760
761
# spent 56.1ms (7.72+48.3) within Sub::Exporter::_do_import which was called 76 times, avg 738µs/call: # 76 times (7.72ms+48.3ms) by Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:756] at line 745, avg 738µs/call
sub _do_import {
762304499µs my ($arg, $to_import) = @_;
763
764 my @todo;
765
766 for my $pair (@$to_import) {
76744304.11ms my ($name, $import_arg) = @$pair;
768
769 my ($generator, $as);
770
77135441.44ms22µs if ($import_arg and Params::Util::_CODELIKE($import_arg)) { ## no critic
# spent 2µs making 2 calls to Params::Util::_CODELIKE, avg 850ns/call
772 # This is the case when a group generator has inserted name/code pairs.
773 $generator = sub { $import_arg };
774 $as = $name;
775 } else {
776 $import_arg = { $import_arg ? %$import_arg : () };
777
778 Carp::croak qq("$name" is not exported by the $arg->{class} module)
779 unless exists $arg->{config}{exports}{$name};
780
781 $generator = $arg->{config}{exports}{$name};
782
783 $as = exists $import_arg->{-as} ? (delete $import_arg->{-as}) : $name;
784 }
785
786 my $code = $arg->{generator}->(
# spent 15.0ms making 886 calls to Sub::Exporter::default_generator, avg 17µs/call
787 {
788 class => $arg->{class},
789 name => $name,
790 arg => $import_arg,
791 col => $arg->{col},
792 generator => $generator,
793 }
794 );
795
796 push @todo, $as, $code;
797 }
798
799 $arg->{installer}->(
# spent 33.3ms making 76 calls to Sub::Exporter::default_installer, avg 438µs/call
800 {
801 class => $arg->{class},
802 into => $arg->{into},
803 col => $arg->{col},
804 },
805 \@todo,
806 );
807}
808
809## Cute idea, possibly for future use: also supply an "unimport" for:
810## no Module::Whatever qw(arg arg arg);
811# sub _unexport {
812# my (undef, undef, undef, undef, undef, $as, $into) = @_;
813#
814# if (ref $as eq 'SCALAR') {
815# undef $$as;
816# } elsif (ref $as) {
817# Carp::croak "invalid reference type for $as: " . ref $as;
818# } else {
819# no strict 'refs';
820# delete &{$into . '::' . $as};
821# }
822# }
823
824=head2 default_generator
825
826This is Sub::Exporter's default generator. It takes bits of configuration that
827have been gathered during the import and turns them into a coderef that can be
828installed.
829
830 my $code = default_generator(\%arg);
831
832Passed arguments are:
833
834 class - the class on which the import method was called
835 name - the name of the export being generated
836 arg - the arguments to the generator
837 col - the collections
838
839 generator - the generator to be used to build the export (code or scalar ref)
840
841=cut
842
843
# spent 15.0ms (5.37+9.68) within Sub::Exporter::default_generator which was called 886 times, avg 17µs/call: # 886 times (5.37ms+9.68ms) by Sub::Exporter::_do_import at line 786, avg 17µs/call
sub default_generator {
84435375.24ms my ($arg) = @_;
845 my ($class, $name, $generator) = @$arg{qw(class name generator)};
846
8471466µs if (not defined $generator) {
848 my $code = $class->can($name)
# spent 13µs making 7 calls to UNIVERSAL::can, avg 2µs/call
849 or Carp::croak "can't locate exported subroutine $name via $class";
850 return $code;
851 }
852
853 # I considered making this "$class->$generator(" but it seems that
854 # overloading precedence would turn an overloaded-as-code generator object
855 # into a string before code. -- rjbs, 2006-06-11
856 return $generator->($class, $name, $arg->{arg}, $arg->{col})
# spent 7.33ms making 384 calls to Moose::Exporter::__ANON__[Moose/Exporter.pm:263], avg 19µs/call # spent 485µs making 372 calls to Moose::Exporter::__ANON__[Moose/Exporter.pm:193], avg 1µs/call # spent 435µs making 35 calls to MooseX::Types::Base::__ANON__[MooseX/Types/Base.pm:72], avg 12µs/call # spent 349µs making 879 calls to Params::Util::_CODELIKE, avg 397ns/call # spent 310µs making 21 calls to Moose::Exporter::__ANON__[Moose/Exporter.pm:241], avg 15µs/call # spent 287µs making 2 calls to Sub::Exporter::__ANON__[Sub/Exporter.pm:937], avg 144µs/call # spent 266µs making 35 calls to MooseX::Types::Base::__ANON__[MooseX/Types/Base.pm:77], avg 8µs/call # spent 199µs making 30 calls to MooseX::Types::Base::__ANON__[MooseX/Types/Base.pm:85], avg 7µs/call
857 if Params::Util::_CODELIKE($generator); ## no critic Private
858
859 # This "must" be a scalar reference, to a generator method name.
860 # -- rjbs, 2006-12-05
861 return $class->$$generator($name, $arg->{arg}, $arg->{col});
862}
863
864=head2 default_installer
865
866This is Sub::Exporter's default installer. It does what Sub::Exporter
867promises: it installs code into the target package.
868
869 default_installer(\%arg, \@to_export);
870
871Passed arguments are:
872
873 into - the package into which exports should be delivered
874
875C<@to_export> is a list of name/value pairs. The default exporter assigns code
876(the values) to named slots (the names) in the given package. If the name is a
877scalar reference, the scalar reference is made to point to the code reference
878instead.
879
880=cut
881
882
# spent 33.3ms (5.53+27.8) within Sub::Exporter::default_installer which was called 76 times, avg 438µs/call: # 76 times (5.53ms+27.8ms) by Sub::Exporter::_do_import at line 799, avg 438µs/call
sub default_installer {
883228254µs my ($arg, $to_export) = @_;
884
88517721.07ms for (my $i = 0; $i < @$to_export; $i += 2) {
88611.07ms my ($as, $code) = @$to_export[ $i, $i+1 ];
887
888 # Allow as isa ARRAY to push onto an array?
889 # Allow into isa HASH to install name=>code into hash?
890
8918861.96ms if (ref $as eq 'SCALAR') {
892 $$as = $code;
893 } elsif (ref $as) {
894 Carp::croak "invalid reference type for $as: " . ref $as;
895 } else {
896 Sub::Install::reinstall_sub({
# spent 27.8ms making 886 calls to Sub::Install::__ANON__[Sub/Install.pm:132], avg 31µs/call
897 code => $code,
898 into => $arg->{into},
899 as => $as
900 });
901 }
902 }
903}
904
905sub default_exporter {
906 Carp::cluck "default_exporter is deprecated; call default_installer instead; the semantics are identical";
907 goto &default_installer;
908}
909
910=head1 EXPORTS
911
912Sub::Exporter also offers its own exports: the C<setup_exporter> and
913C<build_exporter> routines described above. It also provides a special "setup"
914collector, which will set up an exporter using the parameters passed to it.
915
916Note that the "setup" collector (seen in examples like the L</SYNOPSIS> above)
917uses C<build_exporter>, not C<setup_exporter>. This means that the special
918arguments like "into" and "as" for C<setup_exporter> are not accepted here.
919Instead, you may write something like:
920
921 use Sub::Exporter
922 { into => 'Target::Package' },
923 -setup => {
924 -as => 'do_import',
925 exports => [ ... ],
926 }
927 ;
928
929Finding a good reason for wanting to do this is left as as exercise for the
930reader.
931
932=cut
933
934setup_exporter({
935 exports => [
936 qw(setup_exporter build_exporter),
937211µs2278µs
# spent 287µs (9+278) within Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:937] which was called 2 times, avg 144µs/call: # 2 times (9µs+278µs) by Sub::Exporter::default_generator at line 856, avg 144µs/call
_import => sub { build_exporter($_[2]) },
# spent 278µs making 2 calls to Sub::Exporter::build_exporter, avg 139µs/call
938111µs1291µs ],
# spent 291µs making 1 call to Sub::Exporter::setup_exporter
939 groups => {
940 all => [ qw(setup_exporter build_export) ],
941 },
942 collectors => { -setup => \&_setup },
943});
944
945
# spent 20µs within Sub::Exporter::_setup which was called 2 times, avg 10µs/call: # 2 times (20µs+0s) by Sub::Exporter::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/Sub/Exporter.pm:544] at line 539, avg 10µs/call
sub _setup {
94643µs my ($value, $arg) = @_;
947
948420µs if (ref $value eq 'HASH') {
949 push @{ $arg->{import_args} }, [ _import => { -as => 'import', %$value } ];
950 return 1;
951 } elsif (ref $value eq 'ARRAY') {
952 push @{ $arg->{import_args} },
953 [ _import => { -as => 'import', exports => $value } ];
954 return 1;
955 }
956 return;
957}
958
959=head1 COMPARISONS
960
961There are a whole mess of exporters on the CPAN. The features included in
962Sub::Exporter set it apart from any existing Exporter. Here's a summary of
963some other exporters and how they compare.
964
965=over
966
967=item * L<Exporter> and co.
968
969This is the standard Perl exporter. Its interface is a little clunky, but it's
970fast and ubiquitous. It can do some things that Sub::Exporter can't: it can
971export things other than routines, it can import "everything in this group
972except this symbol," and some other more esoteric things. These features seem
973to go nearly entirely unused.
974
975It always exports things exactly as they appear in the exporting module; it
976can't rename or customize routines. Its groups ("tags") can't be nested.
977
978L<Exporter::Lite> is a whole lot like Exporter, but it does significantly less:
979it supports exporting symbols, but not groups, pattern matching, or negation.
980
981The fact that Sub::Exporter can't export symbols other than subroutines is
982a good idea, not a missing feature.
983
984For simple uses, setting up Sub::Exporter is about as easy as Exporter. For
985complex uses, Sub::Exporter makes hard things possible, which would not be
986possible with Exporter.
987
988When using a module that uses Sub::Exporter, users familiar with Exporter will
989probably see no difference in the basics. These two lines do about the same
990thing in whether the exporting module uses Exporter or Sub::Exporter.
991
992 use Some::Module qw(foo bar baz);
993 use Some::Module qw(foo :bar baz);
994
995The definition for exporting in Exporter.pm might look like this:
996
997 package Some::Module;
998 use base qw(Exporter);
999 our @EXPORT_OK = qw(foo bar baz quux);
1000 our %EXPORT_TAGS = (bar => [ qw(bar baz) ]);
1001
1002Using Sub::Exporter, it would look like this:
1003
1004 package Some::Module;
1005 use Sub::Exporter -setup => {
1006 exports => [ qw(foo bar baz quux) ],
1007 groups => { bar => [ qw(bar baz) ]}
1008 };
1009
1010Sub::Exporter respects inheritance, so that a package may export inherited
1011routines, and will export the most inherited version. Exporting methods
1012without currying away the invocant is a bad idea, but Sub::Exporter allows you
1013to do just that -- and anyway, there are other uses for this feature, like
1014packages of exported subroutines which use inheritance specifically to allow
1015more specialized, but similar, packages.
1016
1017L<Exporter::Easy> provides a wrapper around the standard Exporter. It makes it
1018simpler to build groups, but doesn't provide any more functionality. Because
1019it is a front-end to Exporter, it will store your exporter's configuration in
1020global package variables.
1021
1022=item * Attribute-Based Exporters
1023
1024Some exporters use attributes to mark variables to export. L<Exporter::Simple>
1025supports exporting any kind of symbol, and supports groups. Using a module
1026like Exporter or Sub::Exporter, it's easy to look at one place and see what is
1027exported, but it's impossible to look at a variable definition and see whether
1028it is exported by that alone. Exporter::Simple makes this trade in reverse:
1029each variable's declaration includes its export definition, but there is no one
1030place to look to find a manifest of exports.
1031
1032More importantly, Exporter::Simple does not add any new features to those of
1033Exporter. In fact, like Exporter::Easy, it is just a front-end to Exporter, so
1034it ends up storing its configuration in global package variables. (This means
1035that there is one place to look for your exporter's manifest, actually. You
1036can inspect the C<@EXPORT> package variables, and other related package
1037variables, at runtime.)
1038
1039L<Perl6::Export> isn't actually attribute based, but looks similar. Its syntax
1040is borrowed from Perl 6, and implemented by a source filter. It is a prototype
1041of an interface that is still being designed. It should probably be avoided
1042for production work. On the other hand, L<Perl6::Export::Attrs> implements
1043Perl 6-like exporting, but translates it into Perl 5 by providing attributes.
1044
1045=item * Other Exporters
1046
1047L<Exporter::Renaming> wraps the standard Exporter to allow it to export symbols
1048with changed names.
1049
1050L<Class::Exporter> performs a special kind of routine generation, giving each
1051importing package an instance of your class, and then exporting the instance's
1052methods as normal routines. (Sub::Exporter, of course, can easily emulate this
1053behavior, as shown above.)
1054
1055L<Exporter::Tidy> implements a form of renaming (using its C<_map> argument)
1056and of prefixing, and implements groups. It also avoids using package
1057variables for its configuration.
1058
1059=back
1060
1061=head1 TODO
1062
1063=cut
1064
1065=over
1066
1067=item * write a set of longer, more demonstrative examples
1068
1069=item * solidify the "custom exporter" interface (see C<&default_exporter>)
1070
1071=item * add an "always" group
1072
1073=back
1074
1075=head1 AUTHOR
1076
1077Ricardo SIGNES, C<< <rjbs@cpan.org> >>
1078
1079=head1 THANKS
1080
1081Hans Dieter Pearcey provided helpful advice while I was writing Sub::Exporter.
1082Ian Langworth and Shawn Sorichetti asked some good questions and hepled me
1083improve my documentation quite a bit. Yuval Kogman helped me find a bunch of
1084little problems.
1085
1086Thanks, guys!
1087
1088=head1 BUGS
1089
1090Please report any bugs or feature requests through the web interface at
1091L<http://rt.cpan.org>. I will be notified, and then you'll automatically be
1092notified of progress on your bug as I make changes.
1093
1094=head1 COPYRIGHT
1095
1096Copyright 2006-2007, Ricardo SIGNES. This program is free software; you can
1097redistribute it and/or modify it under the same terms as Perl itself.
1098
1099=cut
1100
1101111µs"jn8:32"; # <-- magic true value
# spent 72µs within Devel::GlobalDestruction::in_global_destruction which was called 38 times, avg 2µs/call: # 36 times (59µs+0s) by Moose::Object::__ANON__[/usr/local/lib/perl5/site_perl/5.10.1/darwin-2level/Moose/Object.pm:94] at line 93 of Moose/Object.pm, avg 2µs/call # 2 times (13µs+0s) by Class::MOP::Class::DESTROY at line 242 of Class/MOP/Class.pm, avg 6µs/call
sub Devel::GlobalDestruction::in_global_destruction; # xsub
# spent 3µs within Sub::Exporter::CORE:match which was called # once (3µs+0s) by Sub::Exporter::_assert_collector_names_ok at line 646 of Sub/Exporter.pm
sub Sub::Exporter::CORE:match; # xsub