/usr/share/perl5/Import/Into.pm is in libimport-into-perl 1.002000-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 | package Import::Into;
use strict;
use warnings FATAL => 'all';
our $VERSION = '1.002000'; # 1.2.0
sub _prelude {
my $target = shift;
my ($package, $file, $line, $level)
= ref $target ? @{$target}{qw(package filename line)}
: $target =~ /[^0-9]/ ? ($target)
: (undef, undef, undef, $target);
if (defined $level) {
my ($p, $fn, $ln) = caller($level + 2);
$package ||= $p;
$file ||= $fn;
$line ||= $ln;
}
qq{package $package;\n}
. ($file ? "#line $line \"$file\"\n" : '')
}
sub _make_action {
my ($action, $target) = @_;
my $version = ref $target && $target->{version};
my $ver_check = $version ? '$_[0]->VERSION($version);' : '';
eval _prelude($target).qq{sub { $ver_check shift->$action(\@_) }}
or die "Failed to build action sub to ${action} for ${target}: $@";
}
sub import::into {
my ($class, $target, @args) = @_;
_make_action(import => $target)->($class, @args);
}
sub unimport::out_of {
my ($class, $target, @args) = @_;
_make_action(unimport => $target)->($class, @args);
}
1;
__END__
=head1 NAME
Import::Into - import packages into other packages
=head1 SYNOPSIS
package My::MultiExporter;
use Import::Into;
use Thing1 ();
use Thing2 ();
# simple
sub import {
Thing1->import::into(scalar caller);
}
# multiple
sub import {
my $target = caller;
Thing1->import::into($target);
Thing2->import::into($target, qw(import arguments));
}
# by level
sub import {
Thing1->import::into(1);
}
# with exporter
use base qw(Exporter);
sub import {
shift->export_to_level(1);
Thing1->import::into(1);
}
# no My::MultiExporter == no Thing1
sub unimport {
Thing1->unimport::out_of(scalar caller);
}
People wanting to re-export your module should also be using L<Import::Into>.
Any exporter or pragma will work seamlessly.
Note: You do B<not> need to make any changes to Thing1 to be able to call
C<import::into> on it. This is a global method, and is callable on any
package (and in fact on any object as well, although it's rarer that you'd
want to do that).
=head1 DESCRIPTION
Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
are pragmas.
Exporting on someone else's behalf is harder. The exporters don't provide a
consistent API for this, and pragmas need to have their import method called
directly, since they effect the current unit of compilation.
C<Import::Into> provides global methods to make this painless.
=head1 METHODS
=head2 $package->import::into( $target, @arguments );
A global method, callable on any package. Imports the given package into
C<$target>. C<@arguments> are passed along to the package's import method.
C<$target> can be an package name to export to, an integer for the
caller level to export to, or a hashref with the following options:
=over 4
=item package
The target package to export to.
=item filename
The apparent filename to export to. Some exporting modules, such as
L<autodie> or L<strictures>, care about the filename they are being imported
to.
=item line
The apparent line number to export to. To be combined with the C<filename>
option.
=item level
The caller level to export to. This will automatically populate the
C<package>, C<filename>, and C<line> options, making it the easiest most
constent option.
=item version
A version number to check for the module. The equivalent of specifying the
version number on a C<use> line.
=back
=head2 $package->unimport::out_of( $target, @arguments );
Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport>
method instead of C<import>.
=head1 WHY USE THIS MODULE
The APIs for exporting modules aren't consistent. L<Exporter> subclasses
provide export_to_level, but if they overrode their import method all bets
are off. L<Sub::Exporter> provides an into parameter but figuring out
something used it isn't trivial. Pragmas need to have their C<import> method
called directly since they affect the current unit of compilation.
It's ... annoying.
However, there is an approach that actually works for all of these types.
eval "package $target; use $thing;"
will work for anything checking caller, which is everything except pragmas.
But it doesn't work for pragmas - pragmas need:
$thing->import;
because they're designed to affect the code currently being compiled - so
within an eval, that's the scope of the eval itself, not the module that
just C<use>d you - so
sub import {
eval "use strict;"
}
doesn't do what you wanted, but
sub import {
strict->import;
}
will apply L<strict> to the calling file correctly.
Of course, now you have two new problems - first, that you still need to
know if something's a pragma, and second that you can't use either of
these approaches alone on something like L<Moose> or L<Moo> that's both
an exporter and a pragma.
So, a solution for that is:
my $sub = eval "package $target; sub { shift->import(\@_) }";
$sub->($thing, @import_args);
which means that import is called from the right place for pragmas to take
effect, and from the right package for caller checking to work - and so
behaves correctly for all types of exporter, for pragmas, and for hybrids.
Additionally, some import routines check the filename they are being imported
to. This can be dealt with by generating a L<#line directive|perlsyn/Plain
Old Comments (Not!)> in the eval, which will change what C<caller> reports for
the filename when called in the importer. The filename and line number to use
in the directive then need to be fetched using C<caller>:
my ($target, $file, $line) = caller(1);
my $sub = eval qq{
package $target;
#line $line "$file"
sub { shift->import(\@_) }
};
$sub->($thing, @import_args);
And you need to switch between these implementations depending on if you are
targetting a specific package, or something in your call stack.
Remembering all this, however, is excessively irritating. So I wrote a module
so I didn't have to anymore. Loading L<Import::Into> creates a global method
C<import::into> which you can call on any package to import it into another
package. So now you can simply write:
use Import::Into;
$thing->import::into($target, @import_args);
This works because of how perl resolves method calls - a call to a simple
method name is resolved against the package of the class or object, so
$thing->method_name(@args);
is roughly equivalent to:
my $code_ref = $thing->can('method_name');
$code_ref->($thing, @args);
while if a C<::> is found, the lookup is made relative to the package name
(i.e. everything before the last C<::>) so
$thing->Package::Name::method_name(@args);
is roughly equivalent to:
my $code_ref = Package::Name->can('method_name');
$code_ref->($thing, @args);
So since L<Import::Into> defines a method C<into> in package C<import>
the syntax reliably calls that.
For more craziness of this order, have a look at the article I wrote at
L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
coderef abuse and the C<${\...}> syntax.
Final note: You do still need to ensure that you already loaded C<$thing> - if
you're receiving this from a parameter, I recommend using L<Module::Runtime>:
use Import::Into;
use Module::Runtime qw(use_module);
use_module($thing)->import::into($target, @import_args);
And that's it.
=head1 ACKNOWLEDGEMENTS
Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
turned on for all consumers of my code?" and then "why is this not a
module?!".
=head1 AUTHOR
mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
=head1 CONTRIBUTORS
haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
=head1 COPYRIGHT
Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
as listed above.
=head1 LICENSE
This library is free software and may be distributed under the same terms
as perl itself.
=cut
|