NAME

Import::Into - import packages into other packages

SYNOPSIS

  package My::MultiExporter;

  use Import::Into;

  use Thing1 ();
  use Thing2 ();

  sub import {
    my $target = caller;
    Thing1->import::into($target);
    Thing2->import::into($target, qw(import arguments));
  }

Note: you don't need to do anything more clever than this provided you document that people wanting to re-export your module should also be using Import::Into. In fact, for a single module you can simply do:

  sub import {
    ...
    Thing1->import::into(scalar caller);
  }

Notably, this works:

  use base qw(Exporter);

  sub import {
    shift->export_to_level(1);
    Thing1->import::into(scalar caller);
  }

Note 2: You do not need to do anything 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).

Finally, we also provide an unimport::out_of to allow the exporting of the effect of no:

  # unimport::out_of was added in 1.1.0 (1.001000)
  sub unimport {
    Moose->unimport::out_of(scalar caller); # no MyThing == no Moose
  }

If how and why this all works is of interest to you, please read on to the description immediately below.

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.

If you want to re-export other things, you have to know which is which. 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 used 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, the complete solution 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.

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 http://shadow.cat/blog/matt-s-trout/madness-with-methods which covers coderef abuse and the ${\...} syntax.

Final note: You do still need to ensure that you already loaded $thing - if you're receiving this from a parameter, I recommend using Module::Runtime:

  use Import::Into;
  use Module::Runtime qw(use_module);

  use_module($thing)->import::into($target, @import_args);

And that's it.

AUTHOR

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

CONTRIBUTORS

None yet - maybe this software is perfect! (ahahahahahahahahaha)

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.

cpanm Import::Into

perl -MCPAN -e shell
install Import::Into