9 use Sub::Install 0.92 ();
13 Sub::Exporter - a sophisticated exporter for custom-built routines
21 our $VERSION = '0.982';
25 Sub::Exporter must be used in two places. First, in an exporting module:
27 # in the exporting module:
28 package Text::Tweaker;
29 use Sub::Exporter -setup => {
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,
36 collectors => [ 'defaults' ],
39 Then, in an importing module:
41 # in the importing module:
44 indent => { margin => 5 },
45 reformat => { width => 79, justify => 'full', -as => 'prettify_text' },
46 defaults => { eol => 'CRLF' };
48 With this setup, the importing module ends up with three routines: C<squish>,
49 C<indent>, and C<prettify_text>. The latter two have been built to the
50 specifications of the importer -- they are not just copies of the code in the
55 B<ACHTUNG!> If you're not familiar with Exporter or exporting, read
56 L<Sub::Exporter::Tutorial> first!
58 =head2 Why Generators?
60 The biggest benefit of Sub::Exporter over existing exporters (including the
61 ubiquitous Exporter.pm) is its ability to build new coderefs for export, rather
62 than to simply export code identical to that found in the exporting package.
64 If your module's consumers get a routine that works like this:
66 use Data::Analyze qw(analyze);
67 my $value = analyze($data, $tolerance, $passes);
69 and they constantly pass only one or two different set of values for the
70 non-C<$data> arguments, your code can benefit from Sub::Exporter. By writing a
71 simple generator, you can let them do this, instead:
74 analyze => { tolerance => 0.10, passes => 10, -as => analyze10 },
75 analyze => { tolerance => 0.15, passes => 50, -as => analyze50 };
77 my $value = analyze10($data);
79 The generator for that would look something like this:
82 my ($class, $name, $arg) = @_;
86 my $tolerance = shift || $arg->{tolerance};
87 my $passes = shift || $arg->{passes};
89 analyze($data, $tolerance, $passes);
93 Your module's user now has to do less work to benefit from it -- and remember,
94 you're often your own user! Investing in customized subroutines is an
95 investment in future laziness.
97 This also avoids a common form of ugliness seen in many modules: package-level
98 configuration. That is, you might have seen something like the above
101 use Data::Analyze qw(analyze);
102 $Data::Analyze::default_tolerance = 0.10;
103 $Data::Analyze::default_passes = 10;
105 This might save time, until you have multiple modules using Data::Analyze.
106 Because there is only one global configuration, they step on each other's toes
107 and your code begins to have mysterious errors.
109 Generators can also allow you to export class methods to be called as
112 package Data::Methodical;
113 use Sub::Exporter -setup => { exports => { some_method => \&_curry_class } };
116 my ($class, $name) = @_;
117 sub { $class->$name(@_); };
120 Because of the way that exporters and Sub::Exporter work, any package that
121 inherits from Data::Methodical can inherit its exporter and override its
122 C<some_method>. If a user imports C<some_method> from that package, he'll
123 receive a subroutine that calls the method on the subclass, rather than on
124 Data::Methodical itself.
126 =head2 Other Customizations
128 Building custom routines with generators isn't the only way that Sub::Exporters
129 allows the importing code to refine its use of the exported routines. They may
130 also be renamed to avoid naming collisions.
132 Consider the following code:
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
138 The programmer has inadvertantly imported two C<sin> routines. The solution,
139 in Exporter.pm-based modules, would be to import only one and then call the
140 other by its fully-qualified name. Alternately, the importer could write a
141 routine that did so, or could mess about with typeglobs.
143 How much easier to write:
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_' };
149 and to have at one's disposal C<offense> and C<trig_sin> -- not to mention
150 C<trig_cos> and C<trig_tan>.
152 =head1 EXPORTER CONFIGURATION
154 You can configure an exporter for your package by using Sub::Exporter like so:
158 -setup => { exports => [ qw(function1 function2 function3) ] };
160 This is the simplest way to use the exporter, and is basically equivalent to
164 use base qw(Exporter);
165 our @EXPORT_OK = qw(function1 function2 function2);
167 Any basic use of Sub::Exporter will look like this:
170 use Sub::Exporter -setup => \%config;
172 The following keys are valid in C<%config>:
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
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
183 In addition to the basic options above, a few more advanced options may be
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
189 In other words: Sub::Exporter installs a C<import> routine which, when called,
190 exports routines to the calling namespace. The C<into> and C<into_level>
191 options change where those exported routines are installed.
193 generator - a callback used to produce the code that will be installed
194 default: Sub::Exporter::default_generator
196 installer - a callback used to install the code produced by the generator
197 default: Sub::Exporter::default_installer
199 For information on how these callbacks are used, see the documentation for
200 C<L</default_generator>> and C<L</default_installer>>.
202 =head2 Export Configuration
204 The C<exports> list may be provided as an array reference or a hash reference.
205 The list is processed in such a way that the following are equivalent:
207 { exports => [ qw(foo bar baz), quux => \&quux_generator ] }
210 { foo => undef, bar => undef, baz => undef, quux => \&quux_generator } }
212 Generators are code that return coderefs. They are called with four
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
220 Given the configuration in the L</SYNOPSIS>, the following C<use> statement:
223 reformat => { -as => 'make_narrow', width => 33 },
224 defaults => { eol => 'CR' };
226 would result in the following call to C<&build_reformatter>:
228 my $code = build_reformatter(
231 { width => 33 }, # note that -as is not passed in
232 { defaults => { eol => 'CR' } },
235 The returned coderef (C<$code>) would then be installed as C<make_narrow> in the
238 Instead of providing a coderef in the configuration, a reference to a method
239 name may be provided. This method will then be called on the invocant of the
240 C<import> method. (In this case, we do not pass the C<$class> parameter, as it
243 =head2 Group Configuration
245 The C<groups> list can be passed in the same forms as C<exports>. Groups must
246 have values to be meaningful, which may either list exports that make up the
247 group (optionally with arguments) or may provide a way to build the group.
249 The simpler case is the first: a group definition is a list of exports. Here's
250 the example that could go in exporter in the L</SYNOPSIS>.
253 default => [ qw(reformat) ],
254 shorteners => [ qw(squish trim) ],
257 reformat => { -as => 'email_format', width => 72 }
261 Groups are imported by specifying their name prefixed be either a dash or a
262 colon. This line of code would import the C<shorteners> group:
264 use Text::Tweaker qw(-shorteners);
266 Arguments passed to a group when importing are merged into the groups options
267 and passed to any relevant generators. Groups can contain other groups, but
268 looping group structures are ignored.
270 The other possible value for a group definition, a coderef, allows one
271 generator to build several exportable routines simultaneously. This is useful
272 when many routines must share enclosed lexical variables. The coderef must
273 return a hash reference. The keys will be used as export names and the values
274 are the subs that will be exported.
276 This example shows a simple use of the group generator.
278 package Data::Crypto;
279 use Sub::Exporter -setup => { groups => { cipher => \&build_cipher_group } };
281 sub build_cipher_group {
282 my ($class, $group, $arg) = @_;
283 my ($encode, $decode) = build_codec($arg->{secret});
284 return { cipher => $encode, decipher => $decode };
287 The C<cipher> and C<decipher> routines are built in a group because they are
288 built together by code which encloses their secret in their environment.
290 =head3 Default Groups
292 If a module that uses Sub::Exporter is C<use>d with no arguments, it will try
293 to export the group named C<default>. If that group has not been specifically
294 configured, it will be empty, and nothing will happen.
296 Another group is also created if not defined: C<all>. The C<all> group
297 contains all the exports from the exports list.
299 =head2 Collector Configuration
301 The C<collectors> entry in the exporter configuration gives names which, when
302 found in the import call, have their values collected and passed to every
305 For example, the C<build_analyzer> generator that we saw above could be
309 my ($class, $name, $arg, $col) = @_;
313 my $tolerance = shift || $arg->{tolerance} || $col->{defaults}{tolerance};
314 my $passes = shift || $arg->{passes} || $col->{defaults}{passes};
316 analyze($data, $tolerance, $passes);
320 That would allow the import to specify global defaults for his imports:
324 analyze => { tolerance => 0.10, -as => analyze10 },
325 analyze => { tolerance => 0.15, passes => 50, -as => analyze50 },
326 defaults => { passes => 10 };
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);
332 If values are provided in the C<collectors> list during exporter setup, they
333 must be code references, and are used to validate the importer's values. The
334 validator is called when the collection is found, and if it returns false, an
335 exception is thrown. We could ensure that no one tries to set a global data
338 collectors => { defaults => sub { return (exists $_[0]->{data}) ? 0 : 1 } }
340 Collector coderefs can also be used as hooks to perform arbitrary actions
341 before anything is exported.
343 When the coderef is called, it is passed the value of the collection and a
344 hashref containing the following entries:
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
352 Collectors with all-caps names (that is, made up of underscore or capital A
353 through Z) are reserved for special use. The only currently implemented
354 special collector is C<INIT>, whose hook (if present in the exporter
355 configuration) is always run before any other hook.
357 =head1 CALLING THE EXPORTER
359 Arguments to the exporter (that is, the arguments after the module name in a
360 C<use> statement) are parsed as follows:
362 First, the collectors gather any collections found in the arguments. Any
363 reference type may be given as the value for a collector. For each collection
364 given in the arguments, its validator (if any) is called.
366 Next, groups are expanded. If the group is implemented by a group generator,
367 the generator is called. There are two special arguments which, if given to a
368 group, have special meaning:
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
373 Finally, individual export generators are called and all subs, generated or
374 otherwise, are installed in the calling package. There is only one special
375 argument for export generators:
377 -as - where to install the exported sub
379 Normally, C<-as> will contain an alternate name for the routine. It may,
380 however, contain a reference to a scalar. If that is the case, a reference the
381 generated routine will be placed in the scalar referenced by C<-as>. It will
382 not be installed into the calling package.
384 =head2 Special Exporter Arguments
386 The generated exporter accept some special options, which may be passed as the
387 first argument, in a hashref.
396 These override the same-named configuration options described in L</EXPORTER
401 # Given a potential import name, this returns the group name -- if it's got a
406 return if (index q{-:}, (substr $name, 0, 1)) == -1;
407 return substr $name, 1;
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.
415 my ($class, $config, $groups, $collection, $seen, $merge) = @_;
418 my @groups = @$groups;
420 for my $i (reverse 0 .. $#groups) {
421 if (my $group_name = _group_name($groups[$i][0])) {
422 my $seen = { %$seen }; # faux-dynamic scoping
424 splice @groups, $i, 1,
425 _expand_group($class, $config, $groups[$i], $collection, $seen, $merge);
427 # there's nothing to munge in this export's args
428 next unless my %merge = %$merge;
430 # we have things to merge in; do so
431 my $prefix = (delete $merge{-prefix}) || '';
432 my $suffix = (delete $merge{-suffix}) || '';
435 Params::Util::_CODELIKE($groups[$i][1]) ## no critic Private
437 Params::Util::_SCALAR0($groups[$i][1]) ## no critic Private
439 # this entry was build by a group generator
440 $groups[$i][0] = $prefix . $groups[$i][0] . $suffix;
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;
447 $groups[$i][1] = { %{ $groups[$i][1] }, %merge, -as => $as };
455 # \@group is a name/value pair from an opt list.
457 my ($class, $config, $group, $collection, $seen, $merge) = @_;
460 my ($group_name, $group_arg) = @$group;
461 $group_name = _group_name($group_name);
463 Carp::croak qq(group "$group_name" is not exported by the $class module)
464 unless exists $config->{groups}{$group_name};
466 return if $seen->{$group_name}++;
468 if (ref $group_arg) {
469 my $prefix = (delete $merge->{-prefix}||'') . ($group_arg->{-prefix}||'');
470 my $suffix = ($group_arg->{-suffix}||'') . (delete $merge->{-suffix}||'');
474 ($prefix ? (-prefix => $prefix) : ()),
475 ($suffix ? (-suffix => $suffix) : ()),
479 my $exports = $config->{groups}{$group_name};
482 Params::Util::_CODELIKE($exports) ## no critic Private
484 Params::Util::_SCALAR0($exports) ## no critic Private
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};
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);
497 Carp::croak qq(group generator "$group_name" did not return a hashref)
498 if ref $group ne 'HASH';
500 my $stuff = [ map { [ $_ => $group->{$_} ] } keys %$group ];
502 _expand_groups($class, $config, $stuff, $collection, $seen, $merge)
506 = Data::OptList::mkopt($exports, "$group_name exports");
509 _expand_groups($class, $config, $exports, $collection, $seen, $merge)
514 sub _mk_collection_builder {
515 my ($col, $etc) = @_;
516 my ($config, $import_args, $class, $into) = @$etc;
520 my ($collection) = @_;
521 my ($name, $value) = @$collection;
523 Carp::croak "collection $name provided multiple times in import"
526 if (ref(my $hook = $config->{collectors}{$name})) {
530 import_args => $import_args,
535 my $error_msg = "collection $name failed validation";
536 if (Params::Util::_SCALAR0($hook)) { ## no critic Private
537 Carp::croak $error_msg unless $class->$$hook($value, $arg);
539 Carp::croak $error_msg unless $hook->($value, $arg);
543 $col->{ $name } = $value;
547 # Given a config and pre-canonicalized importer args, remove collections from
548 # the args and return them.
549 sub _collect_collections {
550 my ($config, $import_args, $class, $into) = @_;
553 = map { splice @$import_args, $_, 1 }
554 grep { exists $config->{collectors}{ $import_args->[$_][0] } }
555 reverse 0 .. $#$import_args;
557 unshift @collections, [ INIT => {} ] if $config->{collectors}{INIT};
560 my $builder = _mk_collection_builder($col, \@_);
561 for my $collection (@collections) {
562 $builder->($collection)
570 =head2 setup_exporter
572 This routine builds and installs an C<import> routine. It is called with one
573 argument, a hashref containing the exporter configuration. Using this, it
574 builds an exporter and installs it into the calling package with the name
575 "import." In addition to the normal exporter configuration, a few named
576 arguments may be passed in the hashref:
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
582 By default the exporter is installed with the name C<import> into the immediate
583 caller of C<setup_exporter>. In other words, if your package calls
584 C<setup_exporter> without providing any of the three above arguments, it will
585 have an C<import> routine installed.
587 Providing both C<into> and C<into_level> will cause an exception to be thrown.
589 The exporter is built by C<L</build_exporter>>.
596 Carp::croak 'into and into_level may not both be supplied to exporter'
597 if exists $config->{into} and exists $config->{into_level};
599 my $as = delete $config->{as} || 'import';
601 = exists $config->{into} ? delete $config->{into}
602 : exists $config->{into_level} ? caller(delete $config->{into_level})
605 my $import = build_exporter($config);
607 Sub::Install::reinstall_sub({
614 =head2 build_exporter
616 Given a standard exporter configuration, this routine builds and returns an
617 exporter -- that is, a subroutine that can be installed as a class method to
618 perform exporting on request.
620 Usually, this method is called by C<L</setup_exporter>>, which then installs
621 the exporter as a package's import routine.
625 sub _key_intersection {
627 my %seen = map { $_ => 1 } keys %$x;
628 my @names = grep { $seen{$_} } keys %$y;
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.
635 my %valid_config_key;
639 qw(as collectors installer generator exports groups into into_level),
640 qw(exporter), # deprecated
643 sub _assert_collector_names_ok {
644 my ($collectors) = @_;
646 for my $reserved_name (grep { /\A[_A-Z]+\z/ } keys %$collectors) {
647 Carp::croak "unknown reserved collector name: $reserved_name"
648 if $reserved_name ne 'INIT';
652 sub _rewrite_build_config {
655 if (my @keys = grep { not exists $valid_config_key{$_} } keys %$config) {
656 Carp::croak "unknown options (@keys) passed to Sub::Exporter";
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};
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};
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};
671 for (qw(exports collectors)) {
672 $config->{$_} = Data::OptList::mkopt_hash(
675 [ 'CODE', 'SCALAR' ],
679 _assert_collector_names_ok($config->{collectors});
681 if (my @names = _key_intersection(@$config{qw(exports collectors)})) {
682 Carp::croak "names (@names) used in both collections and exports";
685 $config->{groups} = Data::OptList::mkopt_hash(
689 'HASH', # standard opt list
690 'ARRAY', # standard opt list
691 'CODE', # group generator
692 'SCALAR', # name of group generation method
696 # by default, export nothing
697 $config->{groups}{default} ||= [];
699 # by default, build an all-inclusive 'all' group
700 $config->{groups}{all} ||= [ keys %{ $config->{exports} } ];
702 $config->{generator} ||= \&default_generator;
703 $config->{installer} ||= \&default_installer;
709 _rewrite_build_config($config);
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};
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};
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})
731 my $generator = delete $special->{generator} || $config->{generator};
732 my $installer = delete $special->{installer} || $config->{installer};
734 # this builds a AOA, where the inner arrays are [ name => value_ref ]
735 my $import_args = Data::OptList::mkopt([ @_ ]);
737 # is this right? defaults first or collectors first? -- rjbs, 2006-06-24
738 $import_args = [ [ -default => undef ] ] unless @$import_args;
740 my $collection = _collect_collections($config, $import_args, $class, $into);
742 my $to_import = _expand_groups($class, $config, $import_args, $collection);
744 # now, finally $import_arg is really the "to do" list
751 generator => $generator,
752 installer => $installer,
762 my ($arg, $to_import) = @_;
766 for my $pair (@$to_import) {
767 my ($name, $import_arg) = @$pair;
769 my ($generator, $as);
771 if ($import_arg and Params::Util::_CODELIKE($import_arg)) { ## no critic
772 # This is the case when a group generator has inserted name/code pairs.
773 $generator = sub { $import_arg };
776 $import_arg = { $import_arg ? %$import_arg : () };
778 Carp::croak qq("$name" is not exported by the $arg->{class} module)
779 unless exists $arg->{config}{exports}{$name};
781 $generator = $arg->{config}{exports}{$name};
783 $as = exists $import_arg->{-as} ? (delete $import_arg->{-as}) : $name;
786 my $code = $arg->{generator}->(
788 class => $arg->{class},
792 generator => $generator,
796 push @todo, $as, $code;
801 class => $arg->{class},
802 into => $arg->{into},
809 ## Cute idea, possibly for future use: also supply an "unimport" for:
810 ## no Module::Whatever qw(arg arg arg);
812 # my (undef, undef, undef, undef, undef, $as, $into) = @_;
814 # if (ref $as eq 'SCALAR') {
816 # } elsif (ref $as) {
817 # Carp::croak "invalid reference type for $as: " . ref $as;
820 # delete &{$into . '::' . $as};
824 =head2 default_generator
826 This is Sub::Exporter's default generator. It takes bits of configuration that
827 have been gathered during the import and turns them into a coderef that can be
830 my $code = default_generator(\%arg);
832 Passed arguments are:
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
839 generator - the generator to be used to build the export (code or scalar ref)
843 sub default_generator {
845 my ($class, $name, $generator) = @$arg{qw(class name generator)};
847 if (not defined $generator) {
848 my $code = $class->can($name)
849 or Carp::croak "can't locate exported subroutine $name via $class";
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})
857 if Params::Util::_CODELIKE($generator); ## no critic Private
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});
864 =head2 default_installer
866 This is Sub::Exporter's default installer. It does what Sub::Exporter
867 promises: it installs code into the target package.
869 default_installer(\%arg, \@to_export);
871 Passed arguments are:
873 into - the package into which exports should be delivered
875 C<@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
877 scalar reference, the scalar reference is made to point to the code reference
882 sub default_installer {
883 my ($arg, $to_export) = @_;
885 for (my $i = 0; $i < @$to_export; $i += 2) {
886 my ($as, $code) = @$to_export[ $i, $i+1 ];
888 # Allow as isa ARRAY to push onto an array?
889 # Allow into isa HASH to install name=>code into hash?
891 if (ref $as eq 'SCALAR') {
894 Carp::croak "invalid reference type for $as: " . ref $as;
896 Sub::Install::reinstall_sub({
898 into => $arg->{into},
905 sub default_exporter {
906 Carp::cluck "default_exporter is deprecated; call default_installer instead; the semantics are identical";
907 goto &default_installer;
912 Sub::Exporter also offers its own exports: the C<setup_exporter> and
913 C<build_exporter> routines described above. It also provides a special "setup"
914 collector, which will set up an exporter using the parameters passed to it.
916 Note that the "setup" collector (seen in examples like the L</SYNOPSIS> above)
917 uses C<build_exporter>, not C<setup_exporter>. This means that the special
918 arguments like "into" and "as" for C<setup_exporter> are not accepted here.
919 Instead, you may write something like:
922 { into => 'Target::Package' },
929 Finding a good reason for wanting to do this is left as as exercise for the
936 qw(setup_exporter build_exporter),
937 _import => sub { build_exporter($_[2]) },
940 all => [ qw(setup_exporter build_export) ],
942 collectors => { -setup => \&_setup },
946 my ($value, $arg) = @_;
948 if (ref $value eq 'HASH') {
949 push @{ $arg->{import_args} }, [ _import => { -as => 'import', %$value } ];
951 } elsif (ref $value eq 'ARRAY') {
952 push @{ $arg->{import_args} },
953 [ _import => { -as => 'import', exports => $value } ];
961 There are a whole mess of exporters on the CPAN. The features included in
962 Sub::Exporter set it apart from any existing Exporter. Here's a summary of
963 some other exporters and how they compare.
967 =item * L<Exporter> and co.
969 This is the standard Perl exporter. Its interface is a little clunky, but it's
970 fast and ubiquitous. It can do some things that Sub::Exporter can't: it can
971 export things other than routines, it can import "everything in this group
972 except this symbol," and some other more esoteric things. These features seem
973 to go nearly entirely unused.
975 It always exports things exactly as they appear in the exporting module; it
976 can't rename or customize routines. Its groups ("tags") can't be nested.
978 L<Exporter::Lite> is a whole lot like Exporter, but it does significantly less:
979 it supports exporting symbols, but not groups, pattern matching, or negation.
981 The fact that Sub::Exporter can't export symbols other than subroutines is
982 a good idea, not a missing feature.
984 For simple uses, setting up Sub::Exporter is about as easy as Exporter. For
985 complex uses, Sub::Exporter makes hard things possible, which would not be
986 possible with Exporter.
988 When using a module that uses Sub::Exporter, users familiar with Exporter will
989 probably see no difference in the basics. These two lines do about the same
990 thing in whether the exporting module uses Exporter or Sub::Exporter.
992 use Some::Module qw(foo bar baz);
993 use Some::Module qw(foo :bar baz);
995 The definition for exporting in Exporter.pm might look like this:
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) ]);
1002 Using Sub::Exporter, it would look like this:
1004 package Some::Module;
1005 use Sub::Exporter -setup => {
1006 exports => [ qw(foo bar baz quux) ],
1007 groups => { bar => [ qw(bar baz) ]}
1010 Sub::Exporter respects inheritance, so that a package may export inherited
1011 routines, and will export the most inherited version. Exporting methods
1012 without currying away the invocant is a bad idea, but Sub::Exporter allows you
1013 to do just that -- and anyway, there are other uses for this feature, like
1014 packages of exported subroutines which use inheritance specifically to allow
1015 more specialized, but similar, packages.
1017 L<Exporter::Easy> provides a wrapper around the standard Exporter. It makes it
1018 simpler to build groups, but doesn't provide any more functionality. Because
1019 it is a front-end to Exporter, it will store your exporter's configuration in
1020 global package variables.
1022 =item * Attribute-Based Exporters
1024 Some exporters use attributes to mark variables to export. L<Exporter::Simple>
1025 supports exporting any kind of symbol, and supports groups. Using a module
1026 like Exporter or Sub::Exporter, it's easy to look at one place and see what is
1027 exported, but it's impossible to look at a variable definition and see whether
1028 it is exported by that alone. Exporter::Simple makes this trade in reverse:
1029 each variable's declaration includes its export definition, but there is no one
1030 place to look to find a manifest of exports.
1032 More importantly, Exporter::Simple does not add any new features to those of
1033 Exporter. In fact, like Exporter::Easy, it is just a front-end to Exporter, so
1034 it ends up storing its configuration in global package variables. (This means
1035 that there is one place to look for your exporter's manifest, actually. You
1036 can inspect the C<@EXPORT> package variables, and other related package
1037 variables, at runtime.)
1039 L<Perl6::Export> isn't actually attribute based, but looks similar. Its syntax
1040 is borrowed from Perl 6, and implemented by a source filter. It is a prototype
1041 of an interface that is still being designed. It should probably be avoided
1042 for production work. On the other hand, L<Perl6::Export::Attrs> implements
1043 Perl 6-like exporting, but translates it into Perl 5 by providing attributes.
1045 =item * Other Exporters
1047 L<Exporter::Renaming> wraps the standard Exporter to allow it to export symbols
1050 L<Class::Exporter> performs a special kind of routine generation, giving each
1051 importing package an instance of your class, and then exporting the instance's
1052 methods as normal routines. (Sub::Exporter, of course, can easily emulate this
1053 behavior, as shown above.)
1055 L<Exporter::Tidy> implements a form of renaming (using its C<_map> argument)
1056 and of prefixing, and implements groups. It also avoids using package
1057 variables for its configuration.
1067 =item * write a set of longer, more demonstrative examples
1069 =item * solidify the "custom exporter" interface (see C<&default_exporter>)
1071 =item * add an "always" group
1077 Ricardo SIGNES, C<< <rjbs@cpan.org> >>
1081 Hans Dieter Pearcey provided helpful advice while I was writing Sub::Exporter.
1082 Ian Langworth and Shawn Sorichetti asked some good questions and hepled me
1083 improve my documentation quite a bit. Yuval Kogman helped me find a bunch of
1090 Please report any bugs or feature requests through the web interface at
1091 L<http://rt.cpan.org>. I will be notified, and then you'll automatically be
1092 notified of progress on your bug as I make changes.
1096 Copyright 2006-2007, Ricardo SIGNES. This program is free software; you can
1097 redistribute it and/or modify it under the same terms as Perl itself.
1101 "jn8:32"; # <-- magic true value