Commit | Line | Data |
2afb5246 |
1 | package Import::Into; |
2 | |
3 | use strict; |
4 | use warnings FATAL => 'all'; |
cc087979 |
5 | use Module::Runtime; |
2afb5246 |
6 | |
5e33875d |
7 | our $VERSION = '1.002005'; |
2afb5246 |
8 | |
324e7017 |
9 | sub _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 |
25 | sub _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 |
38 | sub import::into { |
39 | my ($class, $target, @args) = @_; |
5f5f09b1 |
40 | _make_action(import => $target)->($class, @args); |
10074211 |
41 | } |
42 | |
43 | sub unimport::out_of { |
44 | my ($class, $target, @args) = @_; |
5f5f09b1 |
45 | _make_action(unimport => $target)->($class, @args); |
2afb5246 |
46 | } |
47 | |
48 | 1; |
74957c98 |
49 | |
50 | __END__ |
51 | |
2afb5246 |
52 | =head1 NAME |
53 | |
e6231601 |
54 | Import::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 |
91 | People wanting to re-export your module should also be using L<Import::Into>. |
92 | Any exporter or pragma will work seamlessly. |
074eb8db |
93 | |
74957c98 |
94 | Note: You do B<not> need to make any changes to Thing1 to be able to call |
074eb8db |
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 |
97 | want to do that). |
aa5ad642 |
98 | |
e0ff3439 |
99 | =head1 DESCRIPTION |
100 | |
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 |
103 | are pragmas. |
104 | |
074eb8db |
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. |
108 | |
109 | C<Import::Into> provides global methods to make this painless. |
110 | |
111 | =head1 METHODS |
112 | |
113 | =head2 $package->import::into( $target, @arguments ); |
114 | |
cc087979 |
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. |
074eb8db |
117 | |
74957c98 |
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: |
074eb8db |
120 | |
121 | =over 4 |
122 | |
123 | =item package |
124 | |
125 | The target package to export to. |
126 | |
127 | =item filename |
128 | |
74957c98 |
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 |
131 | to. |
074eb8db |
132 | |
133 | =item line |
134 | |
74957c98 |
135 | The apparent line number to export to. To be combined with the C<filename> |
136 | option. |
074eb8db |
137 | |
138 | =item level |
139 | |
74957c98 |
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 |
142 | constent option. |
074eb8db |
143 | |
144 | =item version |
145 | |
74957c98 |
146 | A version number to check for the module. The equivalent of specifying the |
147 | version number on a C<use> line. |
074eb8db |
148 | |
149 | =back |
150 | |
151 | =head2 $package->unimport::out_of( $target, @arguments ); |
152 | |
74957c98 |
153 | Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport> |
154 | method instead of C<import>. |
074eb8db |
155 | |
156 | =head1 WHY USE THIS MODULE |
157 | |
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. |
e0ff3439 |
163 | |
164 | It's ... annoying. |
165 | |
166 | However, there is an approach that actually works for all of these types. |
167 | |
168 | eval "package $target; use $thing;" |
169 | |
170 | will work for anything checking caller, which is everything except pragmas. |
171 | But it doesn't work for pragmas - pragmas need: |
172 | |
173 | $thing->import; |
174 | |
8c17b6f8 |
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 |
178 | |
179 | sub import { |
180 | eval "use strict;" |
181 | } |
182 | |
183 | doesn't do what you wanted, but |
184 | |
185 | sub import { |
186 | strict->import; |
187 | } |
188 | |
189 | will apply L<strict> to the calling file correctly. |
190 | |
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. |
195 | |
ba1c5bf0 |
196 | So, 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 | |
202 | which means that import is called from the right place for pragmas to take |
8c17b6f8 |
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. |
e0ff3439 |
205 | |
ba1c5bf0 |
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>: |
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 |
220 | And you need to switch between these implementations depending on if you are |
08c85698 |
221 | targeting a specific package, or something in your call stack. |
06bd142d |
222 | |
e0ff3439 |
223 | Remembering all this, however, is excessively irritating. So I wrote a module |
aa5ad642 |
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 |
e0ff3439 |
226 | package. So now you can simply write: |
227 | |
228 | use Import::Into; |
229 | |
230 | $thing->import::into($target, @import_args); |
231 | |
aa5ad642 |
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 |
234 | |
235 | $thing->method_name(@args); |
236 | |
237 | is roughly equivalent to: |
238 | |
239 | my $code_ref = $thing->can('method_name'); |
240 | $code_ref->($thing, @args); |
241 | |
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 |
244 | |
245 | $thing->Package::Name::method_name(@args); |
246 | |
247 | is roughly equivalent to: |
248 | |
249 | my $code_ref = Package::Name->can('method_name'); |
250 | $code_ref->($thing, @args); |
251 | |
252 | So since L<Import::Into> defines a method C<into> in package C<import> |
253 | the syntax reliably calls that. |
254 | |
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. |
258 | |
e0ff3439 |
259 | And that's it. |
260 | |
9bf478b2 |
261 | =head1 SEE ALSO |
262 | |
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>. |
265 | |
95ecfed2 |
266 | =head1 ACKNOWLEDGEMENTS |
267 | |
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 |
270 | module?!". |
271 | |
2afb5246 |
272 | =head1 AUTHOR |
273 | |
274 | mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk> |
275 | |
e0ff3439 |
276 | =head1 CONTRIBUTORS |
277 | |
93bb9005 |
278 | haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org> |
e0ff3439 |
279 | |
cc087979 |
280 | Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@gmail.com> |
281 | |
2afb5246 |
282 | =head1 COPYRIGHT |
283 | |
aa5ad642 |
284 | Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS> |
2afb5246 |
285 | as listed above. |
286 | |
287 | =head1 LICENSE |
288 | |
289 | This library is free software and may be distributed under the same terms |
290 | as perl itself. |
74957c98 |
291 | |
292 | =cut |