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