view release on metacpan or  search on metacpan

lib/Import/Into.pm  view on Meta::CPAN

=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:

  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<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 { 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<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);