lib/Import/Into.pm

   1 package Import::Into;
   2
   3 use strict;
   4 use warnings FATAL => 'all';
   5
   6 our $VERSION = '1.000001'; # 1.0.1
   7
   8 my %importers;
   9
  10 sub import::into {
  11   my ($class, $target, @args) = @_;
  12   $class->${\(
  13     $importers{$target} ||= eval qq{
  14       package $target;
  15       sub { shift->import(\@_) };
  16     } or die "Couldn't build importer for $target: $@"
  17   )}(@args);
  18 }
  19
  20 1;
  21
  22 =head1 NAME
  23
  24 Import::Into - import packages into other packages
  25
  26 =head1 SYNOPSIS
  27
  28   package My::MultiExporter;
  29
  30   use Import::Into;
  31
  32   use Thing1 ();
  33   use Thing2 ();
  34
  35   sub import {
  36     my $target = caller;
  37     Thing1->import::into($target);
  38     Thing2->import::into($target, qw(import arguments));
  39   }
  40
  41 Note: you don't need to do anything more clever than this provided you
  42 document that people wanting to re-export your module should also be using
  43 L<Import::Into>. In fact, for a single module you can simply do:
  44
  45   sub import {
  46     ...
  47     Thing1->import::into(scalar caller);
  48   }
  49
  50 Notably, this works:
  51
  52   use base qw(Exporter);
  53
  54   sub import {
  55     shift->export_to_level(1);
  56     Thing1->import::into(scalar caller);
  57   }
  58
  59 =head1 DESCRIPTION
  60
  61 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
  62 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
  63 are pragmas.
  64
  65 If you want to re-export other things, you have to know which is which.
  66 L<Exporter> subclasses provide export_to_level, but if they overrode their
  67 import method all bets are off. L<Sub::Exporter> provides an into parameter
  68 but figuring out something used it isn't trivial. Pragmas need to have
  69 their C<import> method called directly since they affect the current unit of
  70 compilation.
  71
  72 It's ... annoying.
  73
  74 However, there is an approach that actually works for all of these types.
  75
  76   eval "package $target; use $thing;"
  77
  78 will work for anything checking caller, which is everything except pragmas.
  79 But it doesn't work for pragmas - pragmas need:
  80
  81   $thing->import;
  82
  83 because they're designed to affect the code currently being compiled - so
  84 within an eval, that's the scope of the eval itself, not the module that
  85 just C<use>d you - so
  86
  87   sub import {
  88     eval "use strict;"
  89   }
  90
  91 doesn't do what you wanted, but
  92
  93   sub import {
  94     strict->import;
  95   }
  96
  97 will apply L<strict> to the calling file correctly.
  98
  99 Of course, now you have two new problems - first, that you still need to
 100 know if something's a pragma, and second that you can't use either of
 101 these approaches alone on something like L<Moose> or L<Moo> that's both
 102 an exporter and a pragma.
 103
 104 So, the complete solution is:
 105
 106   my $sub = eval "package $target; sub { shift->import(\@_) }";
 107   $sub->($thing, @import_args);
 108
 109 which means that import is called from the right place for pragmas to take
 110 effect, and from the right package for caller checking to work - and so
 111 behaves correctly for all types of exporter, for pragmas, and for hybrids.
 112
 113 Remembering all this, however, is excessively irritating. So I wrote a module
 114 so I didn't have to anymore. Loading L<Import::Into> will create a method
 115 C<import::into> which you can call on a package to import it into another
 116 package. So now you can simply write:
 117
 118   use Import::Into;
 119
 120   $thing->import::into($target, @import_args);
 121
 122 Just make sure you already loaded C<$thing> - if you're receiving this from
 123 a parameter, I recommend using L<Module::Runtime>:
 124
 125   use Import::Into;
 126   use Module::Runtime qw(use_module);
 127
 128   use_module($thing)->import::into($target, @import_args);
 129
 130 And that's it.
 131
 132 =head1 AUTHOR
 133
 134 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 135
 136 =head1 CONTRIBUTORS
 137
 138 None yet - maybe this software is perfect! (ahahahahahahahahaha)
 139
 140 =head1 COPYRIGHT
 141
 142 Copyright (c) 2010-2011 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
 143 as listed above.
 144
 145 =head1 LICENSE
 146
 147 This library is free software and may be distributed under the same terms
 148 as perl itself.