X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FImport-Into.git;a=blobdiff_plain;f=lib%2FImport%2FInto.pm;h=1e4fb75389b09f74a7c7d429f449a437775acc72;hp=a8a3ada25667ef32de9490f2a23c7ad4bdfe1301;hb=f48235dbfef2a091bf976aef3794e64b0b537f41;hpb=2afb5246467e98519cbc8df4025dd6e4a929a85d diff --git a/lib/Import/Into.pm b/lib/Import/Into.pm index a8a3ada..1e4fb75 100644 --- a/lib/Import/Into.pm +++ b/lib/Import/Into.pm @@ -2,50 +2,287 @@ package Import::Into; use strict; use warnings FATAL => 'all'; +use Module::Runtime; -our $VERSION = '1.0'; +our $VERSION = '1.002004'; -my %importers; +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 ? ', $version' : ''; + eval _prelude($target) + . qq{sub { Module::Runtime::use_module( shift$ver_check )->$action(\@_) }} + or die "Failed to build action sub to ${action} for ${target}: $@"; +} sub import::into { my ($class, $target, @args) = @_; - $class->${\( - $importers{$target} ||= eval qq{ - package $target; - sub { shift->import(\@_) }; - } or die "Couldn't build importer for $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 +Import::Into - Import packages into other packages =head1 SYNOPSIS package My::MultiExporter; - use Thing1 (); - use Thing2 (); + use Import::Into; + + # 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. +Any exporter or pragma will work seamlessly. + +Note: You do B need to make any changes to Thing1 to be able to call +C 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, some use L, +some use L, some use L ... 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 provides global methods to make this painless. + +=head1 METHODS + +=head2 $package->import::into( $target, @arguments ); + +A global method, callable on any package. Loads and 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 or L, care about the filename they are being imported +to. + +=item line + +The apparent line number to export to. To be combined with the C +option. + +=item level + +The caller level to export to. This will automatically populate the +C, C, and C 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 line. + +=back + +=head2 $package->unimport::out_of( $target, @arguments ); + +Equivalent to C, but dispatches to C<$package>'s C +method instead of C. + +=head1 WHY USE THIS MODULE + +The APIs for exporting modules aren't consistent. L subclasses +provide export_to_level, but if they overrode their import method all bets +are off. L provides an into parameter but figuring out +something used it isn't trivial. Pragmas need to have their C 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 Cd you - so + + sub import { + eval "use strict;" + } + +doesn't do what you wanted, but + + sub import { + strict->import; + } + +will apply L 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 or L that's both +an exporter and a pragma. + +So, a solution for that is: + + use Module::Runtime; + my $sub = eval "package $target; sub { use_module(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 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: + + my ($target, $file, $line) = caller(1); + my $sub = eval qq{ + package $target; + #line $line "$file" + sub { use_module(shift)->import(\@_) } + }; + $sub->($thing, @import_args); + +And you need to switch between these implementations depending on if you are +targeting 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 creates a global method +C 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 defines a method C in package C +the syntax reliably calls that. + +For more craziness of this order, have a look at the article I wrote at +L which covers +coderef abuse and the C<${\...}> syntax. + +And that's it. + +=head1 SEE ALSO + +I gave a lightning talk on this module (and L and L) at +L. + +=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) +=head1 CONTRIBUTORS + +haarg - Graham Knop (cpan:HAARG) + +Mithaldu - Christian Walde (cpan:MITHALDU) + =head1 COPYRIGHT -Copyright (c) 2010-2011 the Import::Into L and L +Copyright (c) 2012 the Import::Into L and L as listed above. =head1 LICENSE This library is free software and may be distributed under the same terms as perl itself. + +=cut