1Import::Into(3) User Contributed Perl Documentation Import::Into(3)
2
6 Import::Into - Import packages into other packages
7
9 package My::MultiExporter;
10 use Import::Into;
12 # simple
14 sub import {
15 Thing1->import::into(scalar caller);
16 }
17 # multiple
19 sub import {
20 my $target = caller;
21 Thing1->import::into($target);
22 Thing2->import::into($target, qw(import arguments));
23 }
24 # by level
26 sub import {
27 Thing1->import::into(1);
28 }
29 # with exporter
31 use base qw(Exporter);
32 sub import {
33 shift->export_to_level(1);
34 Thing1->import::into(1);
35 }
36 # no My::MultiExporter == no Thing1
38 sub unimport {
39 Thing1->unimport::out_of(scalar caller);
40 }
41 People wanting to re-export your module should also be using
43 Import::Into. Any exporter or pragma will work seamlessly.
44 Note: You do not need to make any changes to Thing1 to be able to call
46 "import::into" on it. This is a global method, and is callable on any
47 package (and in fact on any object as well, although it's rarer that
48 you'd want to do that).
49
51 Writing exporters is a pain. Some use Exporter, some use Sub::Exporter,
52 some use Moose::Exporter, some use Exporter::Declare ... and some
53 things are pragmas.
54 Exporting on someone else's behalf is harder. The exporters don't
56 provide a consistent API for this, and pragmas need to have their
57 import method called directly, since they effect the current unit of
58 compilation.
59 "Import::Into" provides global methods to make this painless.
61
63 $package->import::into( $target, @arguments );
64 A global method, callable on any package. Loads and imports the given
65 package into $target. @arguments are passed along to the package's
66 import method.
67 $target can be an package name to export to, an integer for the caller
69 level to export to, or a hashref with the following options:
70 package
72 The target package to export to.
73 filename
75 The apparent filename to export to. Some exporting modules, such
76 as autodie or strictures, care about the filename they are being
77 imported to.
78 line
80 The apparent line number to export to. To be combined with the
81 "filename" option.
82 level
84 The caller level to export to. This will automatically populate
85 the "package", "filename", and "line" options, making it the
86 easiest most constent option.
87 version
89 A version number to check for the module. The equivalent of
90 specifying the version number on a "use" line.
91 $package->unimport::out_of( $target, @arguments );
93 Equivalent to "import::into", but dispatches to $package's "unimport"
94 method instead of "import".
95
97 The APIs for exporting modules aren't consistent. Exporter subclasses
98 provide export_to_level, but if they overrode their import method all
99 bets are off. Sub::Exporter provides an into parameter but figuring
100 out something used it isn't trivial. Pragmas need to have their
101 "import" method called directly since they affect the current unit of
102 compilation.
103 It's ... annoying.
105 However, there is an approach that actually works for all of these
107 types.
108 eval "package $target; use $thing;"
110 will work for anything checking caller, which is everything except
112 pragmas. But it doesn't work for pragmas - pragmas need:
113 $thing->import;
115 because they're designed to affect the code currently being compiled -
117 so within an eval, that's the scope of the eval itself, not the module
118 that just "use"d you - so
119 sub import {
121 eval "use strict;"
122 }
123 doesn't do what you wanted, but
125 sub import {
127 strict->import;
128 }
129 will apply strict to the calling file correctly.
131 Of course, now you have two new problems - first, that you still need
133 to know if something's a pragma, and second that you can't use either
134 of these approaches alone on something like Moose or Moo that's both an
135 exporter and a pragma.
136 So, a solution for that is:
138 use Module::Runtime;
140 my $sub = eval "package $target; sub { use_module(shift)->import(\@_) }";
141 $sub->($thing, @import_args);
142 which means that import is called from the right place for pragmas to
144 take effect, and from the right package for caller checking to work -
145 and so behaves correctly for all types of exporter, for pragmas, and
146 for hybrids.
147 Additionally, some import routines check the filename they are being
149 imported to. This can be dealt with by generating a #line directive in
150 the eval, which will change what "caller" reports for the filename when
151 called in the importer. The filename and line number to use in the
152 directive then need to be fetched using "caller":
153 my ($target, $file, $line) = caller(1);
155 my $sub = eval qq{
156 package $target;
157 #line $line "$file"
158 sub { use_module(shift)->import(\@_) }
159 };
160 $sub->($thing, @import_args);
161 And you need to switch between these implementations depending on if
163 you are targeting a specific package, or something in your call stack.
164 Remembering all this, however, is excessively irritating. So I wrote a
166 module so I didn't have to anymore. Loading Import::Into creates a
167 global method "import::into" which you can call on any package to
168 import it into another package. So now you can simply write:
169 use Import::Into;
171 $thing->import::into($target, @import_args);
173 This works because of how perl resolves method calls - a call to a
175 simple method name is resolved against the package of the class or
176 object, so
177 $thing->method_name(@args);
179 is roughly equivalent to:
181 my $code_ref = $thing->can('method_name');
183 $code_ref->($thing, @args);
184 while if a "::" is found, the lookup is made relative to the package
186 name (i.e. everything before the last "::") so
187 $thing->Package::Name::method_name(@args);
189 is roughly equivalent to:
191 my $code_ref = Package::Name->can('method_name');
193 $code_ref->($thing, @args);
194 So since Import::Into defines a method "into" in package "import" the
196 syntax reliably calls that.
197 For more craziness of this order, have a look at the article I wrote at
199 <http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
200 coderef abuse and the "${\...}" syntax.
201 And that's it.
203
205 I gave a lightning talk on this module (and curry and Safe::Isa) at
206 YAPC::NA 2013 <https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.
207
209 Thanks to Getty for asking "how can I get "use strict; use warnings;"
210 turned on for all consumers of my code?" and then "why is this not a
211 module?!".
212
214 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
215
217 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
218 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@gmail.com>
220
222 Copyright (c) 2012 the Import::Into "AUTHOR" and "CONTRIBUTORS" as
223 listed above.
224
226 This library is free software and may be distributed under the same
227 terms as perl itself.
228perl v5.28.0 2015-08-28 Import::Into(3)