4 use warnings FATAL => 'all';
7 our $VERSION = '1.002005';
11 my ($package, $file, $line, $level)
12 = ref $target ? @{$target}{qw(package filename line level)}
13 : $target =~ /[^0-9]/ ? ($target)
14 : (undef, undef, undef, $target);
16 my ($p, $fn, $ln) = caller($level + 2);
21 qq{package $package;\n}
22 . ($file ? "#line $line \"$file\"\n" : '')
26 my ($action, $target) = @_;
27 my $version = ref $target && $target->{version};
28 eval _prelude($target)
30 . q[ my $module = shift;]
31 . q[ Module::Runtime::require_module($module);]
32 . (ref $target && exists $target->{version} ? q[ $module->VERSION($version);] : q[])
33 . q[ $module->].$action.q[(@_);]
35 or die "Failed to build action sub to ${action} for ${target}: $@";
39 my ($class, $target, @args) = @_;
40 _make_action(import => $target)->($class, @args);
43 sub unimport::out_of {
44 my ($class, $target, @args) = @_;
45 _make_action(unimport => $target)->($class, @args);
54 Import::Into - Import packages into other packages
58 package My::MultiExporter;
64 Thing1->import::into(scalar caller);
70 Thing1->import::into($target);
71 Thing2->import::into($target, qw(import arguments));
76 Thing1->import::into(1);
80 use base qw(Exporter);
82 shift->export_to_level(1);
83 Thing1->import::into(1);
86 # no My::MultiExporter == no Thing1
88 Thing1->unimport::out_of(scalar caller);
91 People wanting to re-export your module should also be using L<Import::Into>.
92 Any exporter or pragma will work seamlessly.
94 Note: You do B<not> need to make any changes to Thing1 to be able to call
95 C<import::into> on it. This is a global method, and is callable on any
96 package (and in fact on any object as well, although it's rarer that you'd
101 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
102 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
105 Exporting on someone else's behalf is harder. The exporters don't provide a
106 consistent API for this, and pragmas need to have their import method called
107 directly, since they effect the current unit of compilation.
109 C<Import::Into> provides global methods to make this painless.
113 =head2 $package->import::into( $target, @arguments );
115 A global method, callable on any package. Loads and imports the given package
116 into C<$target>. C<@arguments> are passed along to the package's import method.
118 C<$target> can be an package name to export to, an integer for the
119 caller level to export to, or a hashref with the following options:
125 The target package to export to.
129 The apparent filename to export to. Some exporting modules, such as
130 L<autodie> or L<strictures>, care about the filename they are being imported
135 The apparent line number to export to. To be combined with the C<filename>
140 The caller level to export to. This will automatically populate the
141 C<package>, C<filename>, and C<line> options, making it the easiest most
146 A version number to check for the module. The equivalent of specifying the
147 version number on a C<use> line.
151 =head2 $package->unimport::out_of( $target, @arguments );
153 Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport>
154 method instead of C<import>.
156 =head1 WHY USE THIS MODULE
158 The APIs for exporting modules aren't consistent. L<Exporter> subclasses
159 provide export_to_level, but if they overrode their import method all bets
160 are off. L<Sub::Exporter> provides an into parameter but figuring out
161 something used it isn't trivial. Pragmas need to have their C<import> method
162 called directly since they affect the current unit of compilation.
166 However, there is an approach that actually works for all of these types.
168 eval "package $target; use $thing;"
170 will work for anything checking caller, which is everything except pragmas.
171 But it doesn't work for pragmas - pragmas need:
175 because they're designed to affect the code currently being compiled - so
176 within an eval, that's the scope of the eval itself, not the module that
177 just C<use>d you - so
183 doesn't do what you wanted, but
189 will apply L<strict> to the calling file correctly.
191 Of course, now you have two new problems - first, that you still need to
192 know if something's a pragma, and second that you can't use either of
193 these approaches alone on something like L<Moose> or L<Moo> that's both
194 an exporter and a pragma.
196 So, a solution for that is:
199 my $sub = eval "package $target; sub { use_module(shift)->import(\@_) }";
200 $sub->($thing, @import_args);
202 which means that import is called from the right place for pragmas to take
203 effect, and from the right package for caller checking to work - and so
204 behaves correctly for all types of exporter, for pragmas, and for hybrids.
206 Additionally, some import routines check the filename they are being imported
207 to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
208 Old Comments (Not!)> in the eval, which will change what C<caller> reports for
209 the filename when called in the importer. The filename and line number to use
210 in the directive then need to be fetched using C<caller>:
212 my ($target, $file, $line) = caller(1);
216 sub { use_module(shift)->import(\@_) }
218 $sub->($thing, @import_args);
220 And you need to switch between these implementations depending on if you are
221 targeting a specific package, or something in your call stack.
223 Remembering all this, however, is excessively irritating. So I wrote a module
224 so I didn't have to anymore. Loading L<Import::Into> creates a global method
225 C<import::into> which you can call on any package to import it into another
226 package. So now you can simply write:
230 $thing->import::into($target, @import_args);
232 This works because of how perl resolves method calls - a call to a simple
233 method name is resolved against the package of the class or object, so
235 $thing->method_name(@args);
237 is roughly equivalent to:
239 my $code_ref = $thing->can('method_name');
240 $code_ref->($thing, @args);
242 while if a C<::> is found, the lookup is made relative to the package name
243 (i.e. everything before the last C<::>) so
245 $thing->Package::Name::method_name(@args);
247 is roughly equivalent to:
249 my $code_ref = Package::Name->can('method_name');
250 $code_ref->($thing, @args);
252 So since L<Import::Into> defines a method C<into> in package C<import>
253 the syntax reliably calls that.
255 For more craziness of this order, have a look at the article I wrote at
256 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
257 coderef abuse and the C<${\...}> syntax.
263 I gave a lightning talk on this module (and L<curry> and L<Safe::Isa>) at
264 L<YAPC::NA 2013|https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.
266 =head1 ACKNOWLEDGEMENTS
268 Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
269 turned on for all consumers of my code?" and then "why is this not a
274 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
278 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
280 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@gmail.com>
284 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
289 This library is free software and may be distributed under the same terms