4 use warnings FATAL => 'all';
6 our $VERSION = '1.002001'; # 1.2.1
10 my ($package, $file, $line, $level)
11 = ref $target ? @{$target}{qw(package filename line)}
12 : $target =~ /[^0-9]/ ? ($target)
13 : (undef, undef, undef, $target);
15 my ($p, $fn, $ln) = caller($level + 2);
20 qq{package $package;\n}
21 . ($file ? "#line $line \"$file\"\n" : '')
25 my ($action, $target) = @_;
26 my $version = ref $target && $target->{version};
27 my $ver_check = $version ? '$_[0]->VERSION($version);' : '';
28 eval _prelude($target).qq{sub { $ver_check shift->$action(\@_) }}
29 or die "Failed to build action sub to ${action} for ${target}: $@";
33 my ($class, $target, @args) = @_;
34 _make_action(import => $target)->($class, @args);
37 sub unimport::out_of {
38 my ($class, $target, @args) = @_;
39 _make_action(unimport => $target)->($class, @args);
48 Import::Into - import packages into other packages
52 package My::MultiExporter;
61 Thing1->import::into(scalar caller);
67 Thing1->import::into($target);
68 Thing2->import::into($target, qw(import arguments));
73 Thing1->import::into(1);
77 use base qw(Exporter);
79 shift->export_to_level(1);
80 Thing1->import::into(1);
83 # no My::MultiExporter == no Thing1
85 Thing1->unimport::out_of(scalar caller);
88 People wanting to re-export your module should also be using L<Import::Into>.
89 Any exporter or pragma will work seamlessly.
91 Note: You do B<not> need to make any changes to Thing1 to be able to call
92 C<import::into> on it. This is a global method, and is callable on any
93 package (and in fact on any object as well, although it's rarer that you'd
98 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
99 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
102 Exporting on someone else's behalf is harder. The exporters don't provide a
103 consistent API for this, and pragmas need to have their import method called
104 directly, since they effect the current unit of compilation.
106 C<Import::Into> provides global methods to make this painless.
110 =head2 $package->import::into( $target, @arguments );
112 A global method, callable on any package. Imports the given package into
113 C<$target>. C<@arguments> are passed along to the package's import method.
115 C<$target> can be an package name to export to, an integer for the
116 caller level to export to, or a hashref with the following options:
122 The target package to export to.
126 The apparent filename to export to. Some exporting modules, such as
127 L<autodie> or L<strictures>, care about the filename they are being imported
132 The apparent line number to export to. To be combined with the C<filename>
137 The caller level to export to. This will automatically populate the
138 C<package>, C<filename>, and C<line> options, making it the easiest most
143 A version number to check for the module. The equivalent of specifying the
144 version number on a C<use> line.
148 =head2 $package->unimport::out_of( $target, @arguments );
150 Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport>
151 method instead of C<import>.
153 =head1 WHY USE THIS MODULE
155 The APIs for exporting modules aren't consistent. L<Exporter> subclasses
156 provide export_to_level, but if they overrode their import method all bets
157 are off. L<Sub::Exporter> provides an into parameter but figuring out
158 something used it isn't trivial. Pragmas need to have their C<import> method
159 called directly since they affect the current unit of compilation.
163 However, there is an approach that actually works for all of these types.
165 eval "package $target; use $thing;"
167 will work for anything checking caller, which is everything except pragmas.
168 But it doesn't work for pragmas - pragmas need:
172 because they're designed to affect the code currently being compiled - so
173 within an eval, that's the scope of the eval itself, not the module that
174 just C<use>d you - so
180 doesn't do what you wanted, but
186 will apply L<strict> to the calling file correctly.
188 Of course, now you have two new problems - first, that you still need to
189 know if something's a pragma, and second that you can't use either of
190 these approaches alone on something like L<Moose> or L<Moo> that's both
191 an exporter and a pragma.
193 So, a solution for that is:
195 my $sub = eval "package $target; sub { shift->import(\@_) }";
196 $sub->($thing, @import_args);
198 which means that import is called from the right place for pragmas to take
199 effect, and from the right package for caller checking to work - and so
200 behaves correctly for all types of exporter, for pragmas, and for hybrids.
202 Additionally, some import routines check the filename they are being imported
203 to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
204 Old Comments (Not!)> in the eval, which will change what C<caller> reports for
205 the filename when called in the importer. The filename and line number to use
206 in the directive then need to be fetched using C<caller>:
208 my ($target, $file, $line) = caller(1);
212 sub { shift->import(\@_) }
214 $sub->($thing, @import_args);
216 And you need to switch between these implementations depending on if you are
217 targeting a specific package, or something in your call stack.
219 Remembering all this, however, is excessively irritating. So I wrote a module
220 so I didn't have to anymore. Loading L<Import::Into> creates a global method
221 C<import::into> which you can call on any package to import it into another
222 package. So now you can simply write:
226 $thing->import::into($target, @import_args);
228 This works because of how perl resolves method calls - a call to a simple
229 method name is resolved against the package of the class or object, so
231 $thing->method_name(@args);
233 is roughly equivalent to:
235 my $code_ref = $thing->can('method_name');
236 $code_ref->($thing, @args);
238 while if a C<::> is found, the lookup is made relative to the package name
239 (i.e. everything before the last C<::>) so
241 $thing->Package::Name::method_name(@args);
243 is roughly equivalent to:
245 my $code_ref = Package::Name->can('method_name');
246 $code_ref->($thing, @args);
248 So since L<Import::Into> defines a method C<into> in package C<import>
249 the syntax reliably calls that.
251 For more craziness of this order, have a look at the article I wrote at
252 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
253 coderef abuse and the C<${\...}> syntax.
255 Final note: You do still need to ensure that you already loaded C<$thing> - if
256 you're receiving this from a parameter, I recommend using L<Module::Runtime>:
259 use Module::Runtime qw(use_module);
261 use_module($thing)->import::into($target, @import_args);
267 I gave a lightning talk on this module (and L<curry> and L<Safe::Isa>) at
268 L<YAPC::NA 2013|https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.
270 =head1 ACKNOWLEDGEMENTS
272 Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
273 turned on for all consumers of my code?" and then "why is this not a
278 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
282 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
286 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
291 This library is free software and may be distributed under the same terms