1Import::Into(3)       User Contributed Perl Documentation      Import::Into(3)
2
3
4

NAME

6       Import::Into - Import packages into other packages
7

SYNOPSIS

9         package My::MultiExporter;
10
11         use Import::Into;
12
13         # simple
14         sub import {
15           Thing1->import::into(scalar caller);
16         }
17
18         # multiple
19         sub import {
20           my $target = caller;
21           Thing1->import::into($target);
22           Thing2->import::into($target, qw(import arguments));
23         }
24
25         # by level
26         sub import {
27           Thing1->import::into(1);
28         }
29
30         # with exporter
31         use base qw(Exporter);
32         sub import {
33           shift->export_to_level(1);
34           Thing1->import::into(1);
35         }
36
37         # no My::MultiExporter == no Thing1
38         sub unimport {
39           Thing1->unimport::out_of(scalar caller);
40         }
41
42       People wanting to re-export your module should also be using
43       Import::Into.  Any exporter or pragma will work seamlessly.
44
45       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

DESCRIPTION

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
55       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
60       "Import::Into" provides global methods to make this painless.
61

METHODS

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
68       $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
71       package
72           The target package to export to.
73
74       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
79       line
80           The apparent line number to export to.  To be combined with the
81           "filename" option.
82
83       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
88       version
89           A version number to check for the module.  The equivalent of
90           specifying the version number on a "use" line.
91
92   $package->unimport::out_of( $target, @arguments );
93       Equivalent to "import::into", but dispatches to $package's "unimport"
94       method instead of "import".
95

WHY USE THIS MODULE

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
104       It's ... annoying.
105
106       However, there is an approach that actually works for all of these
107       types.
108
109         eval "package $target; use $thing;"
110
111       will work for anything checking caller, which is everything except
112       pragmas.  But it doesn't work for pragmas - pragmas need:
113
114         $thing->import;
115
116       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
120         sub import {
121           eval "use strict;"
122         }
123
124       doesn't do what you wanted, but
125
126         sub import {
127           strict->import;
128         }
129
130       will apply strict to the calling file correctly.
131
132       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
137       So, a solution for that is:
138
139         use Module::Runtime;
140         my $sub = eval "package $target; sub { use_module(shift)->import(\@_) }";
141         $sub->($thing, @import_args);
142
143       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
148       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
154         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
162       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
165       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
170         use Import::Into;
171
172         $thing->import::into($target, @import_args);
173
174       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
178         $thing->method_name(@args);
179
180       is roughly equivalent to:
181
182         my $code_ref = $thing->can('method_name');
183         $code_ref->($thing, @args);
184
185       while if a "::" is found, the lookup is made relative to the package
186       name (i.e. everything before the last "::") so
187
188         $thing->Package::Name::method_name(@args);
189
190       is roughly equivalent to:
191
192         my $code_ref = Package::Name->can('method_name');
193         $code_ref->($thing, @args);
194
195       So since Import::Into defines a method "into" in package "import" the
196       syntax reliably calls that.
197
198       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
202       And that's it.
203

SEE ALSO

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

ACKNOWLEDGEMENTS

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

AUTHOR

214       mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
215

CONTRIBUTORS

217       haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
218
219       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

LICENSE

226       This library is free software and may be distributed under the same
227       terms as perl itself.
228
229
230
231perl v5.32.0                      2020-07-28                   Import::Into(3)
Impressum