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);
46 Import::Into - import packages into other packages
50 package My::MultiExporter;
59 Thing1->import::into(scalar caller);
65 Thing1->import::into($target);
66 Thing2->import::into($target, qw(import arguments));
71 Thing1->import::into(1);
75 use base qw(Exporter);
77 shift->export_to_level(1);
78 Thing1->import::into(1);
81 # no My::MultiExporter == no Thing1
83 Thing1->unimport::out_of(scalar caller);
86 You don't need to do anything more clever than this provided you
87 document that people wanting to re-export your module should also be using
90 Note: You do B<not> need to make ayny changes to Thing1 to be able to call
91 C<import::into> on it. This is a global method, and is callable on any
92 package (and in fact on any object as well, although it's rarer that you'd
97 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
98 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
101 Exporting on someone else's behalf is harder. The exporters don't provide a
102 consistent API for this, and pragmas need to have their import method called
103 directly, since they effect the current unit of compilation.
105 C<Import::Into> provides global methods to make this painless.
109 =head2 $package->import::into( $target, @arguments );
111 A global method, callable on any package. Imports the given package into
112 C<$target>. C<@arguments> are passed along to the package's import method.
114 C<$target> can be an package name to export to, an integer for the caller level to export to, or a hashref with the following options:
120 The target package to export to.
124 The apparent filename to export to. Some exporting modules, such as L<autodie> or L<strictures>, care about the filename they are being imported to.
128 The apparent line number to export to. To be combined with the C<filename> option.
132 The caller level to export to. This will automatically populate the C<package>, C<filename>, and C<line> options, making it the easiest most constent option.
136 A version number to check for the module. The equivalent of specifying the version number on a C<use> line.
140 =head2 $package->unimport::out_of( $target, @arguments );
142 Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport> method instead of C<import>.
144 =head1 WHY USE THIS MODULE
146 The APIs for exporting modules aren't consistent. L<Exporter> subclasses
147 provide export_to_level, but if they overrode their import method all bets
148 are off. L<Sub::Exporter> provides an into parameter but figuring out
149 something used it isn't trivial. Pragmas need to have their C<import> method
150 called directly since they affect the current unit of compilation.
154 However, there is an approach that actually works for all of these types.
156 eval "package $target; use $thing;"
158 will work for anything checking caller, which is everything except pragmas.
159 But it doesn't work for pragmas - pragmas need:
163 because they're designed to affect the code currently being compiled - so
164 within an eval, that's the scope of the eval itself, not the module that
165 just C<use>d you - so
171 doesn't do what you wanted, but
177 will apply L<strict> to the calling file correctly.
179 Of course, now you have two new problems - first, that you still need to
180 know if something's a pragma, and second that you can't use either of
181 these approaches alone on something like L<Moose> or L<Moo> that's both
182 an exporter and a pragma.
184 So, a solution for that is:
186 my $sub = eval "package $target; sub { shift->import(\@_) }";
187 $sub->($thing, @import_args);
189 which means that import is called from the right place for pragmas to take
190 effect, and from the right package for caller checking to work - and so
191 behaves correctly for all types of exporter, for pragmas, and for hybrids.
193 Additionally, some import routines check the filename they are being imported
194 to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
195 Old Comments (Not!)> in the eval, which will change what C<caller> reports for
196 the filename when called in the importer. The filename and line number to use
197 in the directive then need to be fetched using C<caller>:
199 my ($target, $file, $line) = caller(1);
203 sub { shift->import(\@_) }
205 $sub->($thing, @import_args);
207 And you need to switch between these implementations depending on if you are
208 targetting a specific package, or something in your call stack.
210 Remembering all this, however, is excessively irritating. So I wrote a module
211 so I didn't have to anymore. Loading L<Import::Into> creates a global method
212 C<import::into> which you can call on any package to import it into another
213 package. So now you can simply write:
217 $thing->import::into($target, @import_args);
219 This works because of how perl resolves method calls - a call to a simple
220 method name is resolved against the package of the class or object, so
222 $thing->method_name(@args);
224 is roughly equivalent to:
226 my $code_ref = $thing->can('method_name');
227 $code_ref->($thing, @args);
229 while if a C<::> is found, the lookup is made relative to the package name
230 (i.e. everything before the last C<::>) so
232 $thing->Package::Name::method_name(@args);
234 is roughly equivalent to:
236 my $code_ref = Package::Name->can('method_name');
237 $code_ref->($thing, @args);
239 So since L<Import::Into> defines a method C<into> in package C<import>
240 the syntax reliably calls that.
242 For more craziness of this order, have a look at the article I wrote at
243 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
244 coderef abuse and the C<${\...}> syntax.
246 Final note: You do still need to ensure that you already loaded C<$thing> - if
247 you're receiving this from a parameter, I recommend using L<Module::Runtime>:
250 use Module::Runtime qw(use_module);
252 use_module($thing)->import::into($target, @import_args);
256 =head1 ACKNOWLEDGEMENTS
258 Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
259 turned on for all consumers of my code?" and then "why is this not a
264 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
268 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
272 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
277 This library is free software and may be distributed under the same terms