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;
60 Thing1->import::into($target);
61 Thing2->import::into($target, qw(import arguments));
62 Thing3->import::into(1); # import to level
65 Note: you don't need to do anything more clever than this provided you
66 document that people wanting to re-export your module should also be using
67 L<Import::Into>. In fact, for a single module you can simply do:
71 Thing1->import::into(scalar caller);
76 use base qw(Exporter);
79 shift->export_to_level(1);
80 Thing1->import::into(scalar caller);
83 Note 2: You do B<not> need to do anything to Thing1 to be able to call
84 C<import::into> on it. This is a global method, and is callable on any
85 package (and in fact on any object as well, although it's rarer that you'd
88 If you provide C<import::into> with an integer instead of a package name, it
89 will be used as the number of stack frames to skip to find where to export to.
90 This has the advantage of preserving the apparent filename and line number
91 being exported to, which some modules (L<autodie>, L<strictures>) check.
93 Finally, we also provide an C<unimport::out_of> to allow the exporting of the
96 # unimport::out_of was added in 1.1.0 (1.001000)
98 Moose->unimport::out_of(scalar caller); # no MyThing == no Moose
101 If how and why this all works is of interest to you, please read on to the
102 description immediately below.
106 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
107 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
110 If you want to re-export other things, you have to know which is which.
111 L<Exporter> subclasses provide export_to_level, but if they overrode their
112 import method all bets are off. L<Sub::Exporter> provides an into parameter
113 but figuring out something used it isn't trivial. Pragmas need to have
114 their C<import> method called directly since they affect the current unit of
119 However, there is an approach that actually works for all of these types.
121 eval "package $target; use $thing;"
123 will work for anything checking caller, which is everything except pragmas.
124 But it doesn't work for pragmas - pragmas need:
128 because they're designed to affect the code currently being compiled - so
129 within an eval, that's the scope of the eval itself, not the module that
130 just C<use>d you - so
136 doesn't do what you wanted, but
142 will apply L<strict> to the calling file correctly.
144 Of course, now you have two new problems - first, that you still need to
145 know if something's a pragma, and second that you can't use either of
146 these approaches alone on something like L<Moose> or L<Moo> that's both
147 an exporter and a pragma.
149 So, a solution for that is:
151 my $sub = eval "package $target; sub { shift->import(\@_) }";
152 $sub->($thing, @import_args);
154 which means that import is called from the right place for pragmas to take
155 effect, and from the right package for caller checking to work - and so
156 behaves correctly for all types of exporter, for pragmas, and for hybrids.
158 Additionally, some import routines check the filename they are being imported
159 to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
160 Old Comments (Not!)> in the eval, which will change what C<caller> reports for
161 the filename when called in the importer. The filename and line number to use
162 in the directive then need to be fetched using C<caller>:
164 my ($target, $file, $line) = caller(1);
168 sub { shift->import(\@_) }
170 $sub->($thing, @import_args);
172 Remembering all this, however, is excessively irritating. So I wrote a module
173 so I didn't have to anymore. Loading L<Import::Into> creates a global method
174 C<import::into> which you can call on any package to import it into another
175 package. So now you can simply write:
179 $thing->import::into($target, @import_args);
181 This works because of how perl resolves method calls - a call to a simple
182 method name is resolved against the package of the class or object, so
184 $thing->method_name(@args);
186 is roughly equivalent to:
188 my $code_ref = $thing->can('method_name');
189 $code_ref->($thing, @args);
191 while if a C<::> is found, the lookup is made relative to the package name
192 (i.e. everything before the last C<::>) so
194 $thing->Package::Name::method_name(@args);
196 is roughly equivalent to:
198 my $code_ref = Package::Name->can('method_name');
199 $code_ref->($thing, @args);
201 So since L<Import::Into> defines a method C<into> in package C<import>
202 the syntax reliably calls that.
204 For more craziness of this order, have a look at the article I wrote at
205 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
206 coderef abuse and the C<${\...}> syntax.
208 Final note: You do still need to ensure that you already loaded C<$thing> - if
209 you're receiving this from a parameter, I recommend using L<Module::Runtime>:
212 use Module::Runtime qw(use_module);
214 use_module($thing)->import::into($target, @import_args);
218 =head1 ACKNOWLEDGEMENTS
220 Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
221 turned on for all consumers of my code?" and then "why is this not a
226 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
230 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
234 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
239 This library is free software and may be distributed under the same terms