Commit | Line | Data |
2afb5246 |
1 | package Import::Into; |
2 | |
3 | use strict; |
4 | use warnings FATAL => 'all'; |
5 | |
35faefa4 |
6 | our $VERSION = '1.001001'; # 1.1.1 |
2afb5246 |
7 | |
324e7017 |
8 | sub _prelude { |
10074211 |
9 | my $target = shift; |
3946b321 |
10 | my ($package, $file, $line) |
5f5f09b1 |
11 | = $target =~ /[^0-9]/ ? ($target) : caller($target + 2); |
324e7017 |
12 | qq{package $package;\n} |
ac6d2081 |
13 | . ($file ? "#line $line \"$file\"\n" : '') |
10074211 |
14 | } |
10074211 |
15 | |
5f5f09b1 |
16 | sub _make_action { |
17 | my ($action, $target) = @_; |
18 | eval _prelude($target).qq{sub { shift->$action(\@_) }} |
19 | or die "Failed to build action sub to ${action} for ${target}: $@"; |
20 | } |
21 | |
2afb5246 |
22 | sub import::into { |
23 | my ($class, $target, @args) = @_; |
5f5f09b1 |
24 | _make_action(import => $target)->($class, @args); |
10074211 |
25 | } |
26 | |
27 | sub unimport::out_of { |
28 | my ($class, $target, @args) = @_; |
5f5f09b1 |
29 | _make_action(unimport => $target)->($class, @args); |
2afb5246 |
30 | } |
31 | |
32 | 1; |
33 | |
34 | =head1 NAME |
35 | |
36 | Import::Into - import packages into other packages |
37 | |
38 | =head1 SYNOPSIS |
39 | |
40 | package My::MultiExporter; |
41 | |
e0ff3439 |
42 | use Import::Into; |
43 | |
2afb5246 |
44 | use Thing1 (); |
45 | use Thing2 (); |
9f39bd72 |
46 | use Thing3 (); |
2afb5246 |
47 | |
48 | sub import { |
49 | my $target = caller; |
50 | Thing1->import::into($target); |
51 | Thing2->import::into($target, qw(import arguments)); |
9f39bd72 |
52 | Thing3->import::into(1); # import to level |
2afb5246 |
53 | } |
54 | |
8c17b6f8 |
55 | Note: you don't need to do anything more clever than this provided you |
56 | document that people wanting to re-export your module should also be using |
57 | L<Import::Into>. In fact, for a single module you can simply do: |
58 | |
59 | sub import { |
60 | ... |
61 | Thing1->import::into(scalar caller); |
62 | } |
63 | |
64 | Notably, this works: |
65 | |
66 | use base qw(Exporter); |
67 | |
68 | sub import { |
69 | shift->export_to_level(1); |
70 | Thing1->import::into(scalar caller); |
71 | } |
72 | |
aa5ad642 |
73 | Note 2: You do B<not> need to do anything to Thing1 to be able to call |
74 | C<import::into> on it. This is a global method, and is callable on any |
75 | package (and in fact on any object as well, although it's rarer that you'd |
76 | want to do that). |
77 | |
9f39bd72 |
78 | If you provide C<import::into> with an integer instead of a package name, it |
79 | will be used as the number of stack frames to skip to find where to export to. |
80 | This has the advantage of preserving the apparent filename and line number |
81 | being exported to, which some modules (L<autodie>, L<strictures>) check. |
82 | |
10074211 |
83 | Finally, we also provide an C<unimport::out_of> to allow the exporting of the |
84 | effect of C<no>: |
85 | |
c501842c |
86 | # unimport::out_of was added in 1.1.0 (1.001000) |
10074211 |
87 | sub unimport { |
88 | Moose->unimport::out_of(scalar caller); # no MyThing == no Moose |
89 | } |
90 | |
aa5ad642 |
91 | If how and why this all works is of interest to you, please read on to the |
92 | description immediately below. |
93 | |
e0ff3439 |
94 | =head1 DESCRIPTION |
95 | |
96 | Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>, |
97 | some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things |
98 | are pragmas. |
99 | |
100 | If you want to re-export other things, you have to know which is which. |
101 | L<Exporter> subclasses provide export_to_level, but if they overrode their |
102 | import method all bets are off. L<Sub::Exporter> provides an into parameter |
103 | but figuring out something used it isn't trivial. Pragmas need to have |
104 | their C<import> method called directly since they affect the current unit of |
105 | compilation. |
106 | |
107 | It's ... annoying. |
108 | |
109 | However, there is an approach that actually works for all of these types. |
110 | |
111 | eval "package $target; use $thing;" |
112 | |
113 | will work for anything checking caller, which is everything except pragmas. |
114 | But it doesn't work for pragmas - pragmas need: |
115 | |
116 | $thing->import; |
117 | |
8c17b6f8 |
118 | because they're designed to affect the code currently being compiled - so |
119 | within an eval, that's the scope of the eval itself, not the module that |
120 | just C<use>d you - so |
121 | |
122 | sub import { |
123 | eval "use strict;" |
124 | } |
125 | |
126 | doesn't do what you wanted, but |
127 | |
128 | sub import { |
129 | strict->import; |
130 | } |
131 | |
132 | will apply L<strict> to the calling file correctly. |
133 | |
134 | Of course, now you have two new problems - first, that you still need to |
135 | know if something's a pragma, and second that you can't use either of |
136 | these approaches alone on something like L<Moose> or L<Moo> that's both |
137 | an exporter and a pragma. |
138 | |
ba1c5bf0 |
139 | So, a solution for that is: |
e0ff3439 |
140 | |
141 | my $sub = eval "package $target; sub { shift->import(\@_) }"; |
142 | $sub->($thing, @import_args); |
143 | |
144 | which means that import is called from the right place for pragmas to take |
8c17b6f8 |
145 | effect, and from the right package for caller checking to work - and so |
146 | behaves correctly for all types of exporter, for pragmas, and for hybrids. |
e0ff3439 |
147 | |
ba1c5bf0 |
148 | Additionally, some import routines check the filename they are being imported |
149 | to. This can be dealt with by generating a L<#line directive|perlsyn/Plain |
150 | Old Comments (Not!)> in the eval, which will change what C<caller> reports for |
151 | the filename when called in the importer. The filename and line number to use |
152 | in the directive then need to be fetched using C<caller>: |
153 | |
995d8262 |
154 | my ($target, $file, $line) = caller(1); |
ba1c5bf0 |
155 | my $sub = eval qq{ |
156 | package $target; |
157 | #line $line "$file" |
158 | sub { shift->import(\@_) } |
159 | }; |
160 | $sub->($thing, @import_args); |
161 | |
e0ff3439 |
162 | Remembering all this, however, is excessively irritating. So I wrote a module |
aa5ad642 |
163 | so I didn't have to anymore. Loading L<Import::Into> creates a global method |
164 | C<import::into> which you can call on any package to import it into another |
e0ff3439 |
165 | package. So now you can simply write: |
166 | |
167 | use Import::Into; |
168 | |
169 | $thing->import::into($target, @import_args); |
170 | |
aa5ad642 |
171 | This works because of how perl resolves method calls - a call to a simple |
172 | method name is resolved against the package of the class or object, so |
173 | |
174 | $thing->method_name(@args); |
175 | |
176 | is roughly equivalent to: |
177 | |
178 | my $code_ref = $thing->can('method_name'); |
179 | $code_ref->($thing, @args); |
180 | |
181 | while if a C<::> is found, the lookup is made relative to the package name |
182 | (i.e. everything before the last C<::>) so |
183 | |
184 | $thing->Package::Name::method_name(@args); |
185 | |
186 | is roughly equivalent to: |
187 | |
188 | my $code_ref = Package::Name->can('method_name'); |
189 | $code_ref->($thing, @args); |
190 | |
191 | So since L<Import::Into> defines a method C<into> in package C<import> |
192 | the syntax reliably calls that. |
193 | |
194 | For more craziness of this order, have a look at the article I wrote at |
195 | L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers |
196 | coderef abuse and the C<${\...}> syntax. |
197 | |
198 | Final note: You do still need to ensure that you already loaded C<$thing> - if |
199 | you're receiving this from a parameter, I recommend using L<Module::Runtime>: |
e0ff3439 |
200 | |
201 | use Import::Into; |
202 | use Module::Runtime qw(use_module); |
203 | |
204 | use_module($thing)->import::into($target, @import_args); |
205 | |
206 | And that's it. |
207 | |
95ecfed2 |
208 | =head1 ACKNOWLEDGEMENTS |
209 | |
210 | Thanks to Getty for asking "how can I get C<< use strict; use warnings; >> |
211 | turned on for all consumers of my code?" and then "why is this not a |
212 | module?!". |
213 | |
2afb5246 |
214 | =head1 AUTHOR |
215 | |
216 | mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk> |
217 | |
e0ff3439 |
218 | =head1 CONTRIBUTORS |
219 | |
93bb9005 |
220 | haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org> |
e0ff3439 |
221 | |
2afb5246 |
222 | =head1 COPYRIGHT |
223 | |
aa5ad642 |
224 | Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS> |
2afb5246 |
225 | as listed above. |
226 | |
227 | =head1 LICENSE |
228 | |
229 | This library is free software and may be distributed under the same terms |
230 | as perl itself. |