VERSION's caller should also match given location
[p5sagit/Import-Into.git] / lib / Import / Into.pm
CommitLineData
2afb5246 1package Import::Into;
2
3use strict;
4use warnings FATAL => 'all';
cc087979 5use Module::Runtime;
2afb5246 6
f48235db 7our $VERSION = '1.002004';
2afb5246 8
324e7017 9sub _prelude {
10074211 10 my $target = shift;
568eef3e 11 my ($package, $file, $line, $level)
bd74adea 12 = ref $target ? @{$target}{qw(package filename line level)}
568eef3e 13 : $target =~ /[^0-9]/ ? ($target)
14 : (undef, undef, undef, $target);
15 if (defined $level) {
16 my ($p, $fn, $ln) = caller($level + 2);
17 $package ||= $p;
18 $file ||= $fn;
19 $line ||= $ln;
20 }
324e7017 21 qq{package $package;\n}
ac6d2081 22 . ($file ? "#line $line \"$file\"\n" : '')
10074211 23}
10074211 24
5f5f09b1 25sub _make_action {
26 my ($action, $target) = @_;
568eef3e 27 my $version = ref $target && $target->{version};
cc087979 28 eval _prelude($target)
7a9ec1de 29 . q[sub {]
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[(@_);]
34 . q[}]
5f5f09b1 35 or die "Failed to build action sub to ${action} for ${target}: $@";
36}
37
2afb5246 38sub import::into {
39 my ($class, $target, @args) = @_;
5f5f09b1 40 _make_action(import => $target)->($class, @args);
10074211 41}
42
43sub unimport::out_of {
44 my ($class, $target, @args) = @_;
5f5f09b1 45 _make_action(unimport => $target)->($class, @args);
2afb5246 46}
47
481;
74957c98 49
50__END__
51
2afb5246 52=head1 NAME
53
e6231601 54Import::Into - Import packages into other packages
2afb5246 55
56=head1 SYNOPSIS
57
58 package My::MultiExporter;
59
e0ff3439 60 use Import::Into;
61
074eb8db 62 # simple
63 sub import {
64 Thing1->import::into(scalar caller);
65 }
66
67 # multiple
2afb5246 68 sub import {
69 my $target = caller;
70 Thing1->import::into($target);
71 Thing2->import::into($target, qw(import arguments));
72 }
73
074eb8db 74 # by level
8c17b6f8 75 sub import {
074eb8db 76 Thing1->import::into(1);
8c17b6f8 77 }
78
074eb8db 79 # with exporter
8c17b6f8 80 use base qw(Exporter);
8c17b6f8 81 sub import {
82 shift->export_to_level(1);
074eb8db 83 Thing1->import::into(1);
8c17b6f8 84 }
85
074eb8db 86 # no My::MultiExporter == no Thing1
10074211 87 sub unimport {
074eb8db 88 Thing1->unimport::out_of(scalar caller);
10074211 89 }
90
2b421571 91People wanting to re-export your module should also be using L<Import::Into>.
92Any exporter or pragma will work seamlessly.
074eb8db 93
74957c98 94Note: You do B<not> need to make any changes to Thing1 to be able to call
074eb8db 95C<import::into> on it. This is a global method, and is callable on any
96package (and in fact on any object as well, although it's rarer that you'd
97want to do that).
aa5ad642 98
e0ff3439 99=head1 DESCRIPTION
100
101Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
102some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
103are pragmas.
104
074eb8db 105Exporting on someone else's behalf is harder. The exporters don't provide a
106consistent API for this, and pragmas need to have their import method called
107directly, since they effect the current unit of compilation.
108
109C<Import::Into> provides global methods to make this painless.
110
111=head1 METHODS
112
113=head2 $package->import::into( $target, @arguments );
114
cc087979 115A global method, callable on any package. Loads and imports the given package
116into C<$target>. C<@arguments> are passed along to the package's import method.
074eb8db 117
74957c98 118C<$target> can be an package name to export to, an integer for the
119caller level to export to, or a hashref with the following options:
074eb8db 120
121=over 4
122
123=item package
124
125The target package to export to.
126
127=item filename
128
74957c98 129The apparent filename to export to. Some exporting modules, such as
130L<autodie> or L<strictures>, care about the filename they are being imported
131to.
074eb8db 132
133=item line
134
74957c98 135The apparent line number to export to. To be combined with the C<filename>
136option.
074eb8db 137
138=item level
139
74957c98 140The caller level to export to. This will automatically populate the
141C<package>, C<filename>, and C<line> options, making it the easiest most
142constent option.
074eb8db 143
144=item version
145
74957c98 146A version number to check for the module. The equivalent of specifying the
147version number on a C<use> line.
074eb8db 148
149=back
150
151=head2 $package->unimport::out_of( $target, @arguments );
152
74957c98 153Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport>
154method instead of C<import>.
074eb8db 155
156=head1 WHY USE THIS MODULE
157
158The APIs for exporting modules aren't consistent. L<Exporter> subclasses
159provide export_to_level, but if they overrode their import method all bets
160are off. L<Sub::Exporter> provides an into parameter but figuring out
161something used it isn't trivial. Pragmas need to have their C<import> method
162called directly since they affect the current unit of compilation.
e0ff3439 163
164It's ... annoying.
165
166However, there is an approach that actually works for all of these types.
167
168 eval "package $target; use $thing;"
169
170will work for anything checking caller, which is everything except pragmas.
171But it doesn't work for pragmas - pragmas need:
172
173 $thing->import;
174
8c17b6f8 175because they're designed to affect the code currently being compiled - so
176within an eval, that's the scope of the eval itself, not the module that
177just C<use>d you - so
178
179 sub import {
180 eval "use strict;"
181 }
182
183doesn't do what you wanted, but
184
185 sub import {
186 strict->import;
187 }
188
189will apply L<strict> to the calling file correctly.
190
191Of course, now you have two new problems - first, that you still need to
192know if something's a pragma, and second that you can't use either of
193these approaches alone on something like L<Moose> or L<Moo> that's both
194an exporter and a pragma.
195
ba1c5bf0 196So, a solution for that is:
e0ff3439 197
cc087979 198 use Module::Runtime;
199 my $sub = eval "package $target; sub { use_module(shift)->import(\@_) }";
e0ff3439 200 $sub->($thing, @import_args);
201
202which means that import is called from the right place for pragmas to take
8c17b6f8 203effect, and from the right package for caller checking to work - and so
204behaves correctly for all types of exporter, for pragmas, and for hybrids.
e0ff3439 205
ba1c5bf0 206Additionally, some import routines check the filename they are being imported
207to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
208Old Comments (Not!)> in the eval, which will change what C<caller> reports for
209the filename when called in the importer. The filename and line number to use
210in the directive then need to be fetched using C<caller>:
211
995d8262 212 my ($target, $file, $line) = caller(1);
ba1c5bf0 213 my $sub = eval qq{
214 package $target;
215 #line $line "$file"
cc087979 216 sub { use_module(shift)->import(\@_) }
ba1c5bf0 217 };
218 $sub->($thing, @import_args);
219
06bd142d 220And you need to switch between these implementations depending on if you are
08c85698 221targeting a specific package, or something in your call stack.
06bd142d 222
e0ff3439 223Remembering all this, however, is excessively irritating. So I wrote a module
aa5ad642 224so I didn't have to anymore. Loading L<Import::Into> creates a global method
225C<import::into> which you can call on any package to import it into another
e0ff3439 226package. So now you can simply write:
227
228 use Import::Into;
229
230 $thing->import::into($target, @import_args);
231
aa5ad642 232This works because of how perl resolves method calls - a call to a simple
233method name is resolved against the package of the class or object, so
234
235 $thing->method_name(@args);
236
237is roughly equivalent to:
238
239 my $code_ref = $thing->can('method_name');
240 $code_ref->($thing, @args);
241
242while if a C<::> is found, the lookup is made relative to the package name
243(i.e. everything before the last C<::>) so
244
245 $thing->Package::Name::method_name(@args);
246
247is roughly equivalent to:
248
249 my $code_ref = Package::Name->can('method_name');
250 $code_ref->($thing, @args);
251
252So since L<Import::Into> defines a method C<into> in package C<import>
253the syntax reliably calls that.
254
255For more craziness of this order, have a look at the article I wrote at
256L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
257coderef abuse and the C<${\...}> syntax.
258
e0ff3439 259And that's it.
260
9bf478b2 261=head1 SEE ALSO
262
263I gave a lightning talk on this module (and L<curry> and L<Safe::Isa>) at
264L<YAPC::NA 2013|https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.
265
95ecfed2 266=head1 ACKNOWLEDGEMENTS
267
268Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
269turned on for all consumers of my code?" and then "why is this not a
270module?!".
271
2afb5246 272=head1 AUTHOR
273
274mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
275
e0ff3439 276=head1 CONTRIBUTORS
277
93bb9005 278haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
e0ff3439 279
cc087979 280Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@gmail.com>
281
2afb5246 282=head1 COPYRIGHT
283
aa5ad642 284Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
2afb5246 285as listed above.
286
287=head1 LICENSE
288
289This library is free software and may be distributed under the same terms
290as perl itself.
74957c98 291
292=cut