4 use warnings FATAL => 'all';
6 our $VERSION = '1.001001'; # 1.1.1
10 my ($package, $file, $line)
11 = $target =~ /[^0-9]/ ? ($target) : caller($target + 2);
12 qq{package $package;\n}
13 . ($file ? "#line $line \"$file\"\n" : '')
17 my ($action, $target) = @_;
18 eval _prelude($target).qq{sub { shift->$action(\@_) }}
19 or die "Failed to build action sub to ${action} for ${target}: $@";
23 my ($class, $target, @args) = @_;
24 _make_action(import => $target)->($class, @args);
27 sub unimport::out_of {
28 my ($class, $target, @args) = @_;
29 _make_action(unimport => $target)->($class, @args);
36 Import::Into - import packages into other packages
40 package My::MultiExporter;
50 Thing1->import::into($target);
51 Thing2->import::into($target, qw(import arguments));
52 Thing3->import::into(1); # import to level
55 Note: you don't need to do anything more clever than this provided you
56 document that people wanting to re-export your module should also be using
57 L<Import::Into>. In fact, for a single module you can simply do:
61 Thing1->import::into(scalar caller);
66 use base qw(Exporter);
69 shift->export_to_level(1);
70 Thing1->import::into(scalar caller);
73 Note 2: You do B<not> need to do anything to Thing1 to be able to call
74 C<import::into> on it. This is a global method, and is callable on any
75 package (and in fact on any object as well, although it's rarer that you'd
78 If you provide C<import::into> with an integer instead of a package name, it
79 will be used as the number of stack frames to skip to find where to export to.
80 This has the advantage of preserving the apparent filename and line number
81 being exported to, which some modules (L<autodie>, L<strictures>) check.
83 Finally, we also provide an C<unimport::out_of> to allow the exporting of the
86 # unimport::out_of was added in 1.1.0 (1.001000)
88 Moose->unimport::out_of(scalar caller); # no MyThing == no Moose
91 If how and why this all works is of interest to you, please read on to the
92 description immediately below.
96 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
97 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
100 If you want to re-export other things, you have to know which is which.
101 L<Exporter> subclasses provide export_to_level, but if they overrode their
102 import method all bets are off. L<Sub::Exporter> provides an into parameter
103 but figuring out something used it isn't trivial. Pragmas need to have
104 their C<import> method called directly since they affect the current unit of
109 However, there is an approach that actually works for all of these types.
111 eval "package $target; use $thing;"
113 will work for anything checking caller, which is everything except pragmas.
114 But it doesn't work for pragmas - pragmas need:
118 because they're designed to affect the code currently being compiled - so
119 within an eval, that's the scope of the eval itself, not the module that
120 just C<use>d you - so
126 doesn't do what you wanted, but
132 will apply L<strict> to the calling file correctly.
134 Of course, now you have two new problems - first, that you still need to
135 know if something's a pragma, and second that you can't use either of
136 these approaches alone on something like L<Moose> or L<Moo> that's both
137 an exporter and a pragma.
139 So, a solution for that is:
141 my $sub = eval "package $target; sub { shift->import(\@_) }";
142 $sub->($thing, @import_args);
144 which means that import is called from the right place for pragmas to take
145 effect, and from the right package for caller checking to work - and so
146 behaves correctly for all types of exporter, for pragmas, and for hybrids.
148 Additionally, some import routines check the filename they are being imported
149 to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
150 Old Comments (Not!)> in the eval, which will change what C<caller> reports for
151 the filename when called in the importer. The filename and line number to use
152 in the directive then need to be fetched using C<caller>:
154 my ($terget, $file, $line) = caller(1);
158 sub { shift->import(\@_) }
160 $sub->($thing, @import_args);
162 Remembering all this, however, is excessively irritating. So I wrote a module
163 so I didn't have to anymore. Loading L<Import::Into> creates a global method
164 C<import::into> which you can call on any package to import it into another
165 package. So now you can simply write:
169 $thing->import::into($target, @import_args);
171 This works because of how perl resolves method calls - a call to a simple
172 method name is resolved against the package of the class or object, so
174 $thing->method_name(@args);
176 is roughly equivalent to:
178 my $code_ref = $thing->can('method_name');
179 $code_ref->($thing, @args);
181 while if a C<::> is found, the lookup is made relative to the package name
182 (i.e. everything before the last C<::>) so
184 $thing->Package::Name::method_name(@args);
186 is roughly equivalent to:
188 my $code_ref = Package::Name->can('method_name');
189 $code_ref->($thing, @args);
191 So since L<Import::Into> defines a method C<into> in package C<import>
192 the syntax reliably calls that.
194 For more craziness of this order, have a look at the article I wrote at
195 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
196 coderef abuse and the C<${\...}> syntax.
198 Final note: You do still need to ensure that you already loaded C<$thing> - if
199 you're receiving this from a parameter, I recommend using L<Module::Runtime>:
202 use Module::Runtime qw(use_module);
204 use_module($thing)->import::into($target, @import_args);
208 =head1 ACKNOWLEDGEMENTS
210 Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
211 turned on for all consumers of my code?" and then "why is this not a
216 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
220 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
224 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
229 This library is free software and may be distributed under the same terms