Import-Into-1.002005/000700 000765 000024 00000000000 12567725604 014407 5ustar00gknopstaff000000 000000 Import-Into-1.002005/Changes000644 000765 000024 00000002014 12567725574 015717 0ustar00gknopstaff000000 000000 Revision history for Import-Into 1.002005 - 2015-08-28 - fix level as a hashref parameter 1.002004 - 2014-07-09 - fix prerequisite declarations for older toolchain 1.002003 - 2014-07-09 - module loading is now done while importing, making it unnecessary to load them beforehand (RT#96995, Christian Walde) 1.002002 - 2014-05-06 - minor metadata updates 1.002001 - 2014-03-04 - fix tests and Makefile.PL to support perl 5.6 1.002000 - 2013-12-10 - allow specifying by caller level, as well as specifying file, line, and version 1.001001 - 2013-03-25 - fix NAME in Makefile.PL (RT#84207) 1.001000 - 2012-05-12 - add unimport::out_of 1.000003 - 2012-05-06 - clarify how the method name trick works since apparently now people understand the eval/import trick they've noticed that that isn't the only bit of crazy 1.000002 - 2012-05-05 - improve explanation and add more examples to the SYNOPSIS 1.000001 - 2012-05-03 - correct NAME in Makefile.PL 1.000000 - 2012-05-03 - initial release Import-Into-1.002005/lib/000700 000765 000024 00000000000 12567725604 015155 5ustar00gknopstaff000000 000000 Import-Into-1.002005/maint/000700 000765 000024 00000000000 12567725604 015517 5ustar00gknopstaff000000 000000 Import-Into-1.002005/Makefile.PL000644 000765 000024 00000005114 12375412200 016352 0ustar00gknopstaff000000 000000 use strict; use warnings FATAL => 'all'; my %META = ( name => 'Import-Into', license => 'perl_5', dynamic_config => 0, resources => { # r/w: p5sagit@git.shadowcat.co.uk:Import-Into.git repository => { url => 'git://git.shadowcat.co.uk/p5sagit/Import-Into.git', web => 'http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Import-Into.git', type => 'git', }, bugtracker => { mailto => 'bug-Import-Into@rt.cpan.org', web => 'https://rt.cpan.org/Public/Dist/Display.html?Name=Import-Into', }, }, prereqs => { configure => { requires => { 'ExtUtils::MakeMaker' => 0, }, }, runtime => { requires => { 'strict' => '0', 'warnings' => '0', 'Module::Runtime' => '0', 'perl' => '5.006', }, }, test => { requires => { 'Exporter' => '0', 'base' => '0', 'Test::More' => '0', }, }, }, ); my %MM_ARGS = ( ); ## BOILERPLATE ############################################################### require ExtUtils::MakeMaker; (do 'maint/Makefile.PL.include' or die $@) unless -f 'META.yml'; # have to do this since old EUMM dev releases miss the eval $VERSION line my $eumm_version = eval $ExtUtils::MakeMaker::VERSION; my $mymeta = $eumm_version >= 6.57_02; my $mymeta_broken = $mymeta && $eumm_version < 6.57_07; ($MM_ARGS{NAME} = $META{name}) =~ s/-/::/g; ($MM_ARGS{VERSION_FROM} = "lib/$MM_ARGS{NAME}.pm") =~ s{::}{/}g; $META{license} = [ $META{license} ] if $META{license} && !ref $META{license}; $MM_ARGS{LICENSE} = $META{license}[0] if $META{license} && $eumm_version >= 6.30; $MM_ARGS{NO_MYMETA} = 1 if $mymeta_broken; $MM_ARGS{META_ADD} = { 'meta-spec' => { version => 2 }, %META } unless -f 'META.yml'; for (qw(configure build test runtime)) { my $key = $_ eq 'runtime' ? 'PREREQ_PM' : uc $_.'_REQUIRES'; my $r = $MM_ARGS{$key} = { %{$META{prereqs}{$_}{requires} || {}}, %{delete $MM_ARGS{$key} || {}}, }; defined $r->{$_} or delete $r->{$_} for keys %$r; } $MM_ARGS{MIN_PERL_VERSION} = delete $MM_ARGS{PREREQ_PM}{perl} || 0; delete $MM_ARGS{MIN_PERL_VERSION} if $eumm_version < 6.47_01; $MM_ARGS{BUILD_REQUIRES} = {%{$MM_ARGS{BUILD_REQUIRES}}, %{delete $MM_ARGS{TEST_REQUIRES}}} if $eumm_version < 6.63_03; $MM_ARGS{PREREQ_PM} = {%{$MM_ARGS{PREREQ_PM}}, %{delete $MM_ARGS{BUILD_REQUIRES}}} if $eumm_version < 6.55_01; delete $MM_ARGS{CONFIGURE_REQUIRES} if $eumm_version < 6.51_03; ExtUtils::MakeMaker::WriteMakefile(%MM_ARGS); ## END BOILERPLATE ########################################################### Import-Into-1.002005/MANIFEST000644 000765 000024 00000000536 12567725605 015557 0ustar00gknopstaff000000 000000 Changes lib/Import/Into.pm maint/Makefile.PL.include Makefile.PL MANIFEST This list of files t/import_into.t META.yml Module YAML meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) README README file (added by Distar) Import-Into-1.002005/META.json000600 000765 000024 00000002704 12567725604 016035 0ustar00gknopstaff000000 000000 { "abstract" : "Import packages into other packages", "author" : [ "mst - Matt S. Trout (cpan:MSTROUT) " ], "dynamic_config" : 0, "generated_by" : "ExtUtils::MakeMaker version 7.0401, CPAN::Meta::Converter version 2.150001", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "Import-Into", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : {}, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0" } }, "runtime" : { "requires" : { "Module::Runtime" : "0", "perl" : "5.006", "strict" : "0", "warnings" : "0" } }, "test" : { "requires" : { "Exporter" : "0", "Test::More" : "0", "base" : "0" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "mailto" : "bug-Import-Into@rt.cpan.org", "web" : "https://rt.cpan.org/Public/Dist/Display.html?Name=Import-Into" }, "repository" : { "type" : "git", "url" : "git://git.shadowcat.co.uk/p5sagit/Import-Into.git", "web" : "http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit/Import-Into.git" } }, "version" : "1.002005" } Import-Into-1.002005/META.yml000600 000765 000024 00000001363 12567725604 015665 0ustar00gknopstaff000000 000000 --- abstract: 'Import packages into other packages' author: - 'mst - Matt S. Trout (cpan:MSTROUT) ' build_requires: Exporter: '0' Test::More: '0' base: '0' configure_requires: ExtUtils::MakeMaker: '0' dynamic_config: 0 generated_by: 'ExtUtils::MakeMaker version 7.0401, CPAN::Meta::Converter version 2.150001' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: Import-Into no_index: directory: - t - inc requires: Module::Runtime: '0' perl: '5.006' strict: '0' warnings: '0' resources: bugtracker: https://rt.cpan.org/Public/Dist/Display.html?Name=Import-Into repository: git://git.shadowcat.co.uk/p5sagit/Import-Into.git version: '1.002005' Import-Into-1.002005/README000600 000765 000024 00000016206 12567725605 015277 0ustar00gknopstaff000000 000000 NAME Import::Into - Import packages into other packages SYNOPSIS package My::MultiExporter; 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 Import::Into. Any exporter or pragma will work seamlessly. Note: You do not need to make any changes to Thing1 to be able to call "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). DESCRIPTION Writing exporters is a pain. Some use Exporter, some use Sub::Exporter, some use Moose::Exporter, some use 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. "Import::Into" provides global methods to make this painless. METHODS $package->import::into( $target, @arguments ); A global method, callable on any package. Loads and imports the given package into $target. @arguments are passed along to the package's import method. $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: package The target package to export to. filename The apparent filename to export to. Some exporting modules, such as autodie or strictures, care about the filename they are being imported to. line The apparent line number to export to. To be combined with the "filename" option. level The caller level to export to. This will automatically populate the "package", "filename", and "line" options, making it the easiest most constent option. version A version number to check for the module. The equivalent of specifying the version number on a "use" line. $package->unimport::out_of( $target, @arguments ); Equivalent to "import::into", but dispatches to $package's "unimport" method instead of "import". WHY USE THIS MODULE The APIs for exporting modules aren't consistent. Exporter subclasses provide export_to_level, but if they overrode their import method all bets are off. Sub::Exporter provides an into parameter but figuring out something used it isn't trivial. Pragmas need to have their "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 "use"d you - so sub import { eval "use strict;" } doesn't do what you wanted, but sub import { strict->import; } will apply 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 Moose or Moo 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 #line directive in the eval, which will change what "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 "caller": 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 Import::Into creates a global method "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 "::" is found, the lookup is made relative to the package name (i.e. everything before the last "::") 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 Import::Into defines a method "into" in package "import" the syntax reliably calls that. For more craziness of this order, have a look at the article I wrote at which covers coderef abuse and the "${\...}" syntax. And that's it. SEE ALSO I gave a lightning talk on this module (and curry and Safe::Isa) at YAPC::NA 2013 . ACKNOWLEDGEMENTS Thanks to Getty for asking "how can I get "use strict; use warnings;" turned on for all consumers of my code?" and then "why is this not a module?!". AUTHOR mst - Matt S. Trout (cpan:MSTROUT) CONTRIBUTORS haarg - Graham Knop (cpan:HAARG) Mithaldu - Christian Walde (cpan:MITHALDU) COPYRIGHT Copyright (c) 2012 the Import::Into "AUTHOR" and "CONTRIBUTORS" as listed above. LICENSE This library is free software and may be distributed under the same terms as perl itself. Import-Into-1.002005/t/000700 000765 000024 00000000000 12567725604 014652 5ustar00gknopstaff000000 000000 Import-Into-1.002005/t/import_into.t000644 000765 000024 00000006204 12567725442 017416 0ustar00gknopstaff000000 000000 use strict; use warnings FATAL => 'all'; use Test::More qw(no_plan); BEGIN { package MyExporter; $INC{"MyExporter.pm"} = __FILE__; use base qw(Exporter); our @EXPORT_OK = qw(thing); sub thing { 'thing' } } my @importcaller; my @versioncaller; my $version; BEGIN { package CheckFile; $INC{"CheckFile.pm"} = __FILE__; sub import { @importcaller = caller; } sub VERSION { $version = $_[1]; @versioncaller = caller; } } BEGIN { package MultiExporter; $INC{"MultiExporter.pm"} = __FILE__; use Import::Into; sub import { my $target = caller; warnings->import::into($target); MyExporter->import::into($target, 'thing'); CheckFile->import::into(1); } } eval q{ package TestPackage; no warnings FATAL => 'all'; #line 1 "import_into_inline.pl" use MultiExporter; sub test { thing . undef } 1; } or die $@; my @w; is(do { local $SIG{__WARN__} = sub { push @w, @_; }; TestPackage::test(); }, 'thing', 'returned thing ok'); is(scalar @w, 1, 'Only one entry in @w'); like($w[0], qr/uninitialized/, 'Correct warning'); is $importcaller[0], 'TestPackage', 'import by level has correct package'; is $importcaller[1], 'import_into_inline.pl', 'import by level has correct file'; is $importcaller[2], 1, 'import by level has correct line'; is scalar @versioncaller, 0, 'VERSION not called when not specified'; @importcaller = (); @versioncaller = (); $version = undef; CheckFile->import::into({ package => 'ExplicitPackage', filename => 'explicit-file.pl', line => 42, version => 219, }); is $importcaller[0], 'ExplicitPackage', 'import with hash has correct package'; is $importcaller[1], 'explicit-file.pl', 'import with hash has correct file'; is $importcaller[2], 42, 'import with hash has correct line'; is $versioncaller[0], 'ExplicitPackage', 'VERSION with hash has correct package'; is $versioncaller[1], 'explicit-file.pl', 'VERSION with hash has correct file'; is $versioncaller[2], 42, 'VERSION with hash has correct line'; is $version, 219, 'import with hash has correct version'; BEGIN { package LevelExporter; $INC{'LevelExporter.pm'} = __FILE__; sub import { CheckFile->import::into({ level => 1, version => 219, }); } } @importcaller = (); @versioncaller = (); $version = undef; eval q{ package ExplicitLevel; #line 42 "explicit-level.pl" use LevelExporter; 1; } or die $@; is $importcaller[0], 'ExplicitLevel', 'import with level in hash has correct package'; is $importcaller[1], 'explicit-level.pl', 'import with level in hash has correct file'; is $importcaller[2], 42, 'import with level in hash has correct line'; is $versioncaller[0], 'ExplicitLevel', 'VERSION with level in hash has correct package'; is $versioncaller[1], 'explicit-level.pl', 'VERSION with level in hash has correct file'; is $versioncaller[2], 42, 'VERSION with level in hash has correct line'; is $version, 219, 'import with level in hash has correct version'; ok( !IPC::Open3->can("open3"), "IPC::Open3 is unloaded" ); IPC::Open3->import::into("TestPackage"); ok( TestPackage->can("open3"), "IPC::Open3 was use'd and import::into'd" ); Import-Into-1.002005/maint/Makefile.PL.include000644 000765 000024 00000000300 12216242035 021075 0ustar00gknopstaff000000 000000 BEGIN { -e 'Distar' or system("git clone git://git.shadowcat.co.uk/p5sagit/Distar.git") } use lib 'Distar/lib'; use Distar; author 'mst - Matt S. Trout (cpan:MSTROUT) '; Import-Into-1.002005/lib/Import/000700 000765 000024 00000000000 12567725604 016427 5ustar00gknopstaff000000 000000 Import-Into-1.002005/lib/Import/Into.pm000644 000765 000024 00000020010 12567725567 017711 0ustar00gknopstaff000000 000000 package Import::Into; use strict; use warnings FATAL => 'all'; use Module::Runtime; our $VERSION = '1.002005'; sub _prelude { my $target = shift; my ($package, $file, $line, $level) = ref $target ? @{$target}{qw(package filename line level)} : $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}; eval _prelude($target) . q[sub {] . q[ my $module = shift;] . q[ Module::Runtime::require_module($module);] . (ref $target && exists $target->{version} ? q[ $module->VERSION($version);] : q[]) . q[ $module->].$action.q[(@_);] . q[}] 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; # 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) 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