← Index
NYTProf Performance Profile   « block view • line view • sub view »
For bin/dpath
  Run on Tue Jun 5 15:31:33 2012
Reported on Tue Jun 5 15:31:52 2012

Filename/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm
StatementsExecuted 200 statements in 14.1ms
Subroutines
Calls P F Exclusive
Time
Inclusive
Time
Subroutine
1112.99ms20.2msSub::Exporter::::BEGIN@7Sub::Exporter::BEGIN@7
222278µs2.61msSub::Exporter::::__ANON__[:756]Sub::Exporter::__ANON__[:756]
211266µs2.02msSub::Exporter::::_rewrite_build_configSub::Exporter::_rewrite_build_config
111252µs252µsData::DPath::::BEGIN@1 Data::DPath::BEGIN@1
211188µs1.67msSub::Exporter::::_do_importSub::Exporter::_do_import
211180µs349µsSub::Exporter::::_collect_collectionsSub::Exporter::_collect_collections
211144µs176µsSub::Exporter::::_expand_groupsSub::Exporter::_expand_groups
21196µs521µsSub::Exporter::::default_installerSub::Exporter::default_installer
21184µs951µsSub::Exporter::::default_generatorSub::Exporter::default_generator
22183µs2.10msSub::Exporter::::build_exporterSub::Exporter::build_exporter
11178µs111µsSub::Exporter::::__ANON__[:544]Sub::Exporter::__ANON__[:544]
11168µs68µsSub::Exporter::::BEGIN@636Sub::Exporter::BEGIN@636
11167µs1.60msSub::Exporter::::setup_exporterSub::Exporter::setup_exporter
21158µs58µsSub::Exporter::::_mk_collection_builderSub::Exporter::_mk_collection_builder
21157µs57µsSub::Exporter::::_key_intersectionSub::Exporter::_key_intersection
21154µs74µsSub::Exporter::::_assert_collector_names_okSub::Exporter::_assert_collector_names_ok
11134µs52µsData::DPath::::BEGIN@2.8 Data::DPath::BEGIN@2.8
11134µs95µsSub::Exporter::::BEGIN@9Sub::Exporter::BEGIN@9
21132µs32µsSub::Exporter::::_group_nameSub::Exporter::_group_name
11129µs59µsData::DPath::::BEGIN@3 Data::DPath::BEGIN@3
11128µs28µsSub::Exporter::::_setupSub::Exporter::_setup
11120µs20µsSub::Exporter::::CORE:matchSub::Exporter::CORE:match (opcode)
11119µs840µsSub::Exporter::::__ANON__[:937]Sub::Exporter::__ANON__[:937]
11115µs15µsSub::Exporter::::BEGIN@8Sub::Exporter::BEGIN@8
11114µs14µsSub::Exporter::::BEGIN@6Sub::Exporter::BEGIN@6
0000s0sSub::Exporter::::__ANON__[:773]Sub::Exporter::__ANON__[:773]
0000s0sSub::Exporter::::_expand_groupSub::Exporter::_expand_group
0000s0sSub::Exporter::::default_exporterSub::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
12411µs1252µs
# spent 252µs within Data::DPath::BEGIN@1 which was called: # once (252µs+0s) by Data::DPath::BEGIN@48 at line 1
use 5.006;
# spent 252µs making 1 call to Data::DPath::BEGIN@1
2291µs269µs
# spent 52µs (34+17) within Data::DPath::BEGIN@2.8 which was called: # once (34µs+17µs) by Data::DPath::BEGIN@48 at line 2
use strict;
# spent 52µs making 1 call to Data::DPath::BEGIN@2.8 # spent 17µs making 1 call to strict::import
32139µs290µs
# spent 59µs (29+31) within Data::DPath::BEGIN@3 which was called: # once (29µs+31µs) by Data::DPath::BEGIN@48 at line 3
use warnings;
# spent 59µs making 1 call to Data::DPath::BEGIN@3 # spent 30µs making 1 call to warnings::import
4package Sub::Exporter;
5
6282µs114µs
# spent 14µs within Sub::Exporter::BEGIN@6 which was called: # once (14µs+0s) by Data::DPath::BEGIN@48 at line 6
use Carp ();
# spent 14µs making 1 call to Sub::Exporter::BEGIN@6
72334µs120.2ms
# spent 20.2ms (2.99+17.2) within Sub::Exporter::BEGIN@7 which was called: # once (2.99ms+17.2ms) by Data::DPath::BEGIN@48 at line 7
use Data::OptList ();
# spent 20.2ms making 1 call to Sub::Exporter::BEGIN@7
82107µs115µs
# spent 15µs within Sub::Exporter::BEGIN@8 which was called: # once (15µs+0s) by Data::DPath::BEGIN@48 at line 8
use Params::Util ();
# spent 15µs making 1 call to Sub::Exporter::BEGIN@8
935.37ms2156µs
# spent 95µs (34+61) within Sub::Exporter::BEGIN@9 which was called: # once (34µs+61µs) by Data::DPath::BEGIN@48 at line 9
use Sub::Install 0.92 ();
# spent 95µs making 1 call to Sub::Exporter::BEGIN@9 # spent 61µ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
2114µsour $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 32µs within Sub::Exporter::_group_name which was called 2 times, avg 16µs/call: # 2 times (32µs+0s) by Sub::Exporter::_expand_groups at line 421, avg 16µs/call
sub _group_name {
40426µs my ($name) = @_;
405
406273µs 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 176µs (144+32) within Sub::Exporter::_expand_groups which was called 2 times, avg 88µs/call: # 2 times (144µs+32µs) by Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:756] at line 742, avg 88µs/call
sub _expand_groups {
41529µs my ($class, $config, $groups, $collection, $seen, $merge) = @_;
41625µs $seen ||= {};
41722µs $merge ||= {};
41827µs my @groups = @$groups;
419
420218µs for my $i (reverse 0 .. $#groups) {
421218µs232µs if (my $group_name = _group_name($groups[$i][0])) {
# spent 32µs making 2 calls to Sub::Exporter::_group_name, avg 16µs/call
422 my $seen = { %$seen }; # faux-dynamic scoping
423
424 splice @groups, $i, 1,
425 _expand_group($class, $config, $groups[$i], $collection, $seen, $merge);
426 } else {
427 # there's nothing to munge in this export's args
428218µs 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
452233µs return \@groups;
453}
454
455# \@group is a name/value pair from an opt list.
456sub _expand_group {
457 my ($class, $config, $group, $collection, $seen, $merge) = @_;
458 $merge ||= {};
459
460 my ($group_name, $group_arg) = @$group;
461 $group_name = _group_name($group_name);
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
481 if (
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
506 = Data::OptList::mkopt($exports, "$group_name exports");
507
508 return @{
509 _expand_groups($class, $config, $exports, $collection, $seen, $merge)
510 };
511 }
512}
513
514
# spent 58µs within Sub::Exporter::_mk_collection_builder which was called 2 times, avg 29µs/call: # 2 times (58µs+0s) by Sub::Exporter::_collect_collections at line 560, avg 29µs/call
sub _mk_collection_builder {
51525µs my ($col, $etc) = @_;
51627µs my ($config, $import_args, $class, $into) = @$etc;
517
51821µs my %seen;
519
# spent 111µs (78+33) within Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:544] which was called: # once (78µs+33µs) by Sub::Exporter::_collect_collections at line 562
sub {
52012µs my ($collection) = @_;
52112µs my ($name, $value) = @$collection;
522
52315µs Carp::croak "collection $name provided multiple times in import"
524 if $seen{ $name }++;
525
52616µs if (ref(my $hook = $config->{collectors}{$name})) {
527110µs my $arg = {
528 name => $name,
529 config => $config,
530 import_args => $import_args,
531 class => $class,
532 into => $into,
533 };
534
53516µs my $error_msg = "collection $name failed validation";
536128µs15µs if (Params::Util::_SCALAR0($hook)) { ## no critic Private
# spent 5µs making 1 call to Params::Util::_SCALAR0
537 Carp::croak $error_msg unless $class->$$hook($value, $arg);
538 } else {
53916µs128µs Carp::croak $error_msg unless $hook->($value, $arg);
# spent 28µs making 1 call to Sub::Exporter::_setup
540 }
541 }
542
543116µs $col->{ $name } = $value;
544 }
545270µs}
546
547# Given a config and pre-canonicalized importer args, remove collections from
548# the args and return them.
549
# spent 349µs (180+169) within Sub::Exporter::_collect_collections which was called 2 times, avg 174µs/call: # 2 times (180µs+169µs) by Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:756] at line 740, avg 174µs/call
sub _collect_collections {
55028µs my ($config, $import_args, $class, $into) = @_;
551
552 my @collections
553 = map { splice @$import_args, $_, 1 }
554238µs grep { exists $config->{collectors}{ $import_args->[$_][0] } }
555 reverse 0 .. $#$import_args;
556
55726µs unshift @collections, [ INIT => {} ] if $config->{collectors}{INIT};
558
55924µs my $col = {};
560218µs258µs my $builder = _mk_collection_builder($col, \@_);
# spent 58µs making 2 calls to Sub::Exporter::_mk_collection_builder, avg 29µs/call
561210µs for my $collection (@collections) {
562110µs1111µs $builder->($collection)
# spent 111µs making 1 call to Sub::Exporter::__ANON__[Sub/Exporter.pm:544]
563 }
564
5652120µs 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 1.60ms (67µs+1.54) within Sub::Exporter::setup_exporter which was called: # once (67µs+1.54ms) by Data::DPath::BEGIN@48 at line 938
sub setup_exporter {
59415µs my ($config) = @_;
595
59614µs Carp::croak 'into and into_level may not both be supplied to exporter'
597 if exists $config->{into} and exists $config->{into_level};
598
59916µs my $as = delete $config->{as} || 'import';
60016µs my $into
601 = exists $config->{into} ? delete $config->{into}
602 : exists $config->{into_level} ? caller(delete $config->{into_level})
603 : caller(0);
604
60517µs11.28ms my $import = build_exporter($config);
# spent 1.28ms making 1 call to Sub::Exporter::build_exporter
606
607128µs1256µs Sub::Install::reinstall_sub({
# spent 256µs making 1 call to Sub::Install::__ANON__[Sub/Install.pm:132]
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 57µs within Sub::Exporter::_key_intersection which was called 2 times, avg 29µs/call: # 2 times (57µs+0s) by Sub::Exporter::_rewrite_build_config at line 681, avg 29µs/call
sub _key_intersection {
62625µs my ($x, $y) = @_;
627228µs my %seen = map { $_ => 1 } keys %$x;
628235µs 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.
63511µsmy %valid_config_key;
636
# spent 68µs within Sub::Exporter::BEGIN@636 which was called: # once (68µs+0s) by Data::DPath::BEGIN@48 at line 641
BEGIN {
637 %valid_config_key =
638172µs map { $_ => 1 }
639 qw(as collectors installer generator exports groups into into_level),
640 qw(exporter), # deprecated
64115.67ms168µs}
# spent 68µs making 1 call to Sub::Exporter::BEGIN@636
642
643
# spent 74µs (54+20) within Sub::Exporter::_assert_collector_names_ok which was called 2 times, avg 37µs/call: # 2 times (54µs+20µs) by Sub::Exporter::_rewrite_build_config at line 679, avg 37µs/call
sub _assert_collector_names_ok {
64425µs my ($collectors) = @_;
645
646378µs120µs for my $reserved_name (grep { /\A[_A-Z]+\z/ } keys %$collectors) {
# spent 20µ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 2.02ms (266µs+1.75) within Sub::Exporter::_rewrite_build_config which was called 2 times, avg 1.01ms/call: # 2 times (266µs+1.75ms) by Sub::Exporter::build_exporter at line 709, avg 1.01ms/call
sub _rewrite_build_config {
65324µs my ($config) = @_;
654
655230µs if (my @keys = grep { not exists $valid_config_key{$_} } keys %$config) {
656 Carp::croak "unknown options (@keys) passed to Sub::Exporter";
657 }
658
65924µs 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.
66324µs 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
66824µs 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
67129µs for (qw(exports collectors)) {
672464µs41.18ms $config->{$_} = Data::OptList::mkopt_hash(
# spent 1.18ms making 4 calls to Data::OptList::mkopt_hash, avg 295µs/call
673 $config->{$_},
674 $_,
675 [ 'CODE', 'SCALAR' ],
676 );
677 }
678
679217µs274µs _assert_collector_names_ok($config->{collectors});
# spent 74µs making 2 calls to Sub::Exporter::_assert_collector_names_ok, avg 37µs/call
680
681223µs257µs if (my @names = _key_intersection(@$config{qw(exports collectors)})) {
# spent 57µs making 2 calls to Sub::Exporter::_key_intersection, avg 29µs/call
682 Carp::croak "names (@names) used in both collections and exports";
683 }
684
685227µs2442µs $config->{groups} = Data::OptList::mkopt_hash(
# spent 442µs making 2 calls to Data::OptList::mkopt_hash, avg 221µ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
69729µs $config->{groups}{default} ||= [];
698
699 # by default, build an all-inclusive 'all' group
70023µs $config->{groups}{all} ||= [ keys %{ $config->{exports} } ];
701
70228µs $config->{generator} ||= \&default_generator;
703226µs $config->{installer} ||= \&default_installer;
704}
705
706
# spent 2.10ms (83µs+2.02) within Sub::Exporter::build_exporter which was called 2 times, avg 1.05ms/call: # once (46µs+1.24ms) by Sub::Exporter::setup_exporter at line 605 # once (38µs+783µs) by Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:937] at line 937
sub build_exporter {
70725µs my ($config) = @_;
708
709210µs22.02ms _rewrite_build_config($config);
# spent 2.02ms making 2 calls to Sub::Exporter::_rewrite_build_config, avg 1.01ms/call
710
711
# spent 2.61ms (278µs+2.33) within Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:756] which was called 2 times, avg 1.30ms/call: # once (112µs+1.69ms) by Data::DPath::BEGIN@48 at line 48 of Data/DPath.pm # once (167µs+639µs) by main::BEGIN@10 at line 10 of bin/dpath
my $import = sub {
71227µs my ($class) = shift;
713
714 # XXX: clean this up -- rjbs, 2006-03-16
71528µs my $special = (ref $_[0]) ? shift(@_) : {};
71626µs 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
71924µs 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
724218µs 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
73129µs my $generator = delete $special->{generator} || $config->{generator};
73224µs my $installer = delete $special->{installer} || $config->{installer};
733
734 # this builds a AOA, where the inner arrays are [ name => value_ref ]
735221µs2139µs my $import_args = Data::OptList::mkopt([ @_ ]);
# spent 139µs making 2 calls to Data::OptList::mkopt, avg 70µs/call
736
737 # is this right? defaults first or collectors first? -- rjbs, 2006-06-24
73823µs $import_args = [ [ -default => undef ] ] unless @$import_args;
739
740217µs2349µs my $collection = _collect_collections($config, $import_args, $class, $into);
# spent 349µs making 2 calls to Sub::Exporter::_collect_collections, avg 174µs/call
741
742216µs2176µs my $to_import = _expand_groups($class, $config, $import_args, $collection);
# spent 176µs making 2 calls to Sub::Exporter::_expand_groups, avg 88µs/call
743
744 # now, finally $import_arg is really the "to do" list
745266µs21.67ms _do_import(
# spent 1.67ms making 2 calls to Sub::Exporter::_do_import, avg 833µ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 );
756247µs };
757
758227µs return $import;
759}
760
761
# spent 1.67ms (188µs+1.48) within Sub::Exporter::_do_import which was called 2 times, avg 833µs/call: # 2 times (188µs+1.48ms) by Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:756] at line 745, avg 833µs/call
sub _do_import {
76226µs my ($arg, $to_import) = @_;
763
76421µs my @todo;
765
76628µs for my $pair (@$to_import) {
76725µs my ($name, $import_arg) = @$pair;
768
76923µs my ($generator, $as);
770
771221µs15µs if ($import_arg and Params::Util::_CODELIKE($import_arg)) { ## no critic
# spent 5µs making 1 call to Params::Util::_CODELIKE
772 # This is the case when a group generator has inserted name/code pairs.
773 $generator = sub { $import_arg };
774 $as = $name;
775 } else {
776211µs $import_arg = { $import_arg ? %$import_arg : () };
777
77828µs Carp::croak qq("$name" is not exported by the $arg->{class} module)
779 unless exists $arg->{config}{exports}{$name};
780
78126µs $generator = $arg->{config}{exports}{$name};
782
783215µs $as = exists $import_arg->{-as} ? (delete $import_arg->{-as}) : $name;
784 }
785
786238µs2951µs my $code = $arg->{generator}->(
# spent 951µs making 2 calls to Sub::Exporter::default_generator, avg 475µs/call
787 {
788 class => $arg->{class},
789 name => $name,
790 arg => $import_arg,
791 col => $arg->{col},
792 generator => $generator,
793 }
794 );
795
796215µs push @todo, $as, $code;
797 }
798
799250µs2521µs $arg->{installer}->(
# spent 521µs making 2 calls to Sub::Exporter::default_installer, avg 261µ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 951µs (84+867) within Sub::Exporter::default_generator which was called 2 times, avg 475µs/call: # 2 times (84µs+867µs) by Sub::Exporter::_do_import at line 786, avg 475µs/call
sub default_generator {
84424µs my ($arg) = @_;
845211µs my ($class, $name, $generator) = @$arg{qw(class name generator)};
846
84722µs if (not defined $generator) {
848 my $code = $class->can($name)
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
856269µs4867µs return $generator->($class, $name, $arg->{arg}, $arg->{col})
# spent 840µs making 1 call to Sub::Exporter::__ANON__[Sub/Exporter.pm:937] # spent 18µs making 1 call to Data::DPath::build_dpath # spent 10µs making 2 calls to Params::Util::_CODELIKE, avg 5µ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 521µs (96+425) within Sub::Exporter::default_installer which was called 2 times, avg 261µs/call: # 2 times (96µs+425µs) by Sub::Exporter::_do_import at line 799, avg 261µs/call
sub default_installer {
88325µs my ($arg, $to_export) = @_;
884
885243µs for (my $i = 0; $i < @$to_export; $i += 2) {
886211µs 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
89128µs if (ref $as eq 'SCALAR') {
892 $$as = $code;
893 } elsif (ref $as) {
894 Carp::croak "invalid reference type for $as: " . ref $as;
895 } else {
896228µs2425µs Sub::Install::reinstall_sub({
# spent 425µs making 2 calls to Sub::Install::__ANON__[Sub/Install.pm:132], avg 213µ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),
937117µs1821µs
# spent 840µs (19+821) within Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:937] which was called: # once (19µs+821µs) by Sub::Exporter::default_generator at line 856
_import => sub { build_exporter($_[2]) },
# spent 821µs making 1 call to Sub::Exporter::build_exporter
938152µs11.60ms ],
# spent 1.60ms 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 28µs within Sub::Exporter::_setup which was called: # once (28µs+0s) by Sub::Exporter::__ANON__[/home/ss5/perl5/perlbrew/perls/perl-5.14.1/lib/site_perl/5.14.1/Sub/Exporter.pm:544] at line 539
sub _setup {
94613µs my ($value, $arg) = @_;
947
94813µs if (ref $value eq 'HASH') {
949116µs push @{ $arg->{import_args} }, [ _import => { -as => 'import', %$value } ];
950116µs 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
1101133µs"jn8:32"; # <-- magic true value
 
# spent 20µs within Sub::Exporter::CORE:match which was called: # once (20µs+0s) by Sub::Exporter::_assert_collector_names_ok at line 646
sub Sub::Exporter::CORE:match; # opcode