4 use warnings FATAL => 'all';
6 our $VERSION = '1.001001'; # 1.1.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 You don't need to do anything more clever than this provided you
89 document that people wanting to re-export your module should also be using
92 Note: You do B<not> need to make any changes to Thing1 to be able to call
93 C<import::into> on it. This is a global method, and is callable on any
94 package (and in fact on any object as well, although it's rarer that you'd
99 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
100 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
103 Exporting on someone else's behalf is harder. The exporters don't provide a
104 consistent API for this, and pragmas need to have their import method called
105 directly, since they effect the current unit of compilation.
107 C<Import::Into> provides global methods to make this painless.
111 =head2 $package->import::into( $target, @arguments );
113 A global method, callable on any package. Imports the given package into
114 C<$target>. C<@arguments> are passed along to the package's import method.
116 C<$target> can be an package name to export to, an integer for the
117 caller level to export to, or a hashref with the following options:
123 The target package to export to.
127 The apparent filename to export to. Some exporting modules, such as
128 L<autodie> or L<strictures>, care about the filename they are being imported
133 The apparent line number to export to. To be combined with the C<filename>
138 The caller level to export to. This will automatically populate the
139 C<package>, C<filename>, and C<line> options, making it the easiest most
144 A version number to check for the module. The equivalent of specifying the
145 version number on a C<use> line.
149 =head2 $package->unimport::out_of( $target, @arguments );
151 Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport>
152 method instead of C<import>.
154 =head1 WHY USE THIS MODULE
156 The APIs for exporting modules aren't consistent. L<Exporter> subclasses
157 provide export_to_level, but if they overrode their import method all bets
158 are off. L<Sub::Exporter> provides an into parameter but figuring out
159 something used it isn't trivial. Pragmas need to have their C<import> method
160 called directly since they affect the current unit of compilation.
164 However, there is an approach that actually works for all of these types.
166 eval "package $target; use $thing;"
168 will work for anything checking caller, which is everything except pragmas.
169 But it doesn't work for pragmas - pragmas need:
173 because they're designed to affect the code currently being compiled - so
174 within an eval, that's the scope of the eval itself, not the module that
175 just C<use>d you - so
181 doesn't do what you wanted, but
187 will apply L<strict> to the calling file correctly.
189 Of course, now you have two new problems - first, that you still need to
190 know if something's a pragma, and second that you can't use either of
191 these approaches alone on something like L<Moose> or L<Moo> that's both
192 an exporter and a pragma.
194 So, a solution for that is:
196 my $sub = eval "package $target; sub { shift->import(\@_) }";
197 $sub->($thing, @import_args);
199 which means that import is called from the right place for pragmas to take
200 effect, and from the right package for caller checking to work - and so
201 behaves correctly for all types of exporter, for pragmas, and for hybrids.
203 Additionally, some import routines check the filename they are being imported
204 to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
205 Old Comments (Not!)> in the eval, which will change what C<caller> reports for
206 the filename when called in the importer. The filename and line number to use
207 in the directive then need to be fetched using C<caller>:
209 my ($target, $file, $line) = caller(1);
213 sub { shift->import(\@_) }
215 $sub->($thing, @import_args);
217 And you need to switch between these implementations depending on if you are
218 targetting a specific package, or something in your call stack.
220 Remembering all this, however, is excessively irritating. So I wrote a module
221 so I didn't have to anymore. Loading L<Import::Into> creates a global method
222 C<import::into> which you can call on any package to import it into another
223 package. So now you can simply write:
227 $thing->import::into($target, @import_args);
229 This works because of how perl resolves method calls - a call to a simple
230 method name is resolved against the package of the class or object, so
232 $thing->method_name(@args);
234 is roughly equivalent to:
236 my $code_ref = $thing->can('method_name');
237 $code_ref->($thing, @args);
239 while if a C<::> is found, the lookup is made relative to the package name
240 (i.e. everything before the last C<::>) so
242 $thing->Package::Name::method_name(@args);
244 is roughly equivalent to:
246 my $code_ref = Package::Name->can('method_name');
247 $code_ref->($thing, @args);
249 So since L<Import::Into> defines a method C<into> in package C<import>
250 the syntax reliably calls that.
252 For more craziness of this order, have a look at the article I wrote at
253 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
254 coderef abuse and the C<${\...}> syntax.
256 Final note: You do still need to ensure that you already loaded C<$thing> - if
257 you're receiving this from a parameter, I recommend using L<Module::Runtime>:
260 use Module::Runtime qw(use_module);
262 use_module($thing)->import::into($target, @import_args);
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>
282 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
287 This library is free software and may be distributed under the same terms