lib/Import/Into.pm

   1 package Import::Into;
   2
   3 use strict;
   4 use warnings FATAL => 'all';
   5
   6 our $VERSION = '1.001001'; # 1.1.1
   7
   8 my %importers;
   9
  10 sub _importer {
  11   my $target = shift;
  12   \($importers{$target} ||= eval qq{
  13     package $target;
  14     sub { my \$m = splice \@_, 1, 1; shift->\$m(\@_) };
  15   } or die "Couldn't build importer for $target: $@")
  16 }
  17
  18
  19 sub import::into {
  20   my ($class, $target, @args) = @_;
  21   $class->${_importer($target)}(import => @args);
  22 }
  23
  24 sub unimport::out_of {
  25   my ($class, $target, @args) = @_;
  26   $class->${_importer($target)}(unimport => @args);
  27 }
  28
  29 1;
  30
  31 =head1 NAME
  32
  33 Import::Into - import packages into other packages
  34
  35 =head1 SYNOPSIS
  36
  37   package My::MultiExporter;
  38
  39   use Import::Into;
  40
  41   use Thing1 ();
  42   use Thing2 ();
  43
  44   sub import {
  45     my $target = caller;
  46     Thing1->import::into($target);
  47     Thing2->import::into($target, qw(import arguments));
  48   }
  49
  50 Note: you don't need to do anything more clever than this provided you
  51 document that people wanting to re-export your module should also be using
  52 L<Import::Into>. In fact, for a single module you can simply do:
  53
  54   sub import {
  55     ...
  56     Thing1->import::into(scalar caller);
  57   }
  58
  59 Notably, this works:
  60
  61   use base qw(Exporter);
  62
  63   sub import {
  64     shift->export_to_level(1);
  65     Thing1->import::into(scalar caller);
  66   }
  67
  68 Note 2: You do B<not> need to do anything to Thing1 to be able to call
  69 C<import::into> on it. This is a global method, and is callable on any
  70 package (and in fact on any object as well, although it's rarer that you'd
  71 want to do that).
  72
  73 Finally, we also provide an C<unimport::out_of> to allow the exporting of the
  74 effect of C<no>:
  75
  76   # unimport::out_of was added in 1.1.0 (1.001000)
  77   sub unimport {
  78     Moose->unimport::out_of(scalar caller); # no MyThing == no Moose
  79   }
  80
  81 If how and why this all works is of interest to you, please read on to the
  82 description immediately below.
  83
  84 =head1 DESCRIPTION
  85
  86 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
  87 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
  88 are pragmas.
  89
  90 If you want to re-export other things, you have to know which is which.
  91 L<Exporter> subclasses provide export_to_level, but if they overrode their
  92 import method all bets are off. L<Sub::Exporter> provides an into parameter
  93 but figuring out something used it isn't trivial. Pragmas need to have
  94 their C<import> method called directly since they affect the current unit of
  95 compilation.
  96
  97 It's ... annoying.
  98
  99 However, there is an approach that actually works for all of these types.
 100
 101   eval "package $target; use $thing;"
 102
 103 will work for anything checking caller, which is everything except pragmas.
 104 But it doesn't work for pragmas - pragmas need:
 105
 106   $thing->import;
 107
 108 because they're designed to affect the code currently being compiled - so
 109 within an eval, that's the scope of the eval itself, not the module that
 110 just C<use>d you - so
 111
 112   sub import {
 113     eval "use strict;"
 114   }
 115
 116 doesn't do what you wanted, but
 117
 118   sub import {
 119     strict->import;
 120   }
 121
 122 will apply L<strict> to the calling file correctly.
 123
 124 Of course, now you have two new problems - first, that you still need to
 125 know if something's a pragma, and second that you can't use either of
 126 these approaches alone on something like L<Moose> or L<Moo> that's both
 127 an exporter and a pragma.
 128
 129 So, the complete solution is:
 130
 131   my $sub = eval "package $target; sub { shift->import(\@_) }";
 132   $sub->($thing, @import_args);
 133
 134 which means that import is called from the right place for pragmas to take
 135 effect, and from the right package for caller checking to work - and so
 136 behaves correctly for all types of exporter, for pragmas, and for hybrids.
 137
 138 Remembering all this, however, is excessively irritating. So I wrote a module
 139 so I didn't have to anymore. Loading L<Import::Into> creates a global method
 140 C<import::into> which you can call on any package to import it into another
 141 package. So now you can simply write:
 142
 143   use Import::Into;
 144
 145   $thing->import::into($target, @import_args);
 146
 147 This works because of how perl resolves method calls - a call to a simple
 148 method name is resolved against the package of the class or object, so
 149
 150   $thing->method_name(@args);
 151
 152 is roughly equivalent to:
 153
 154   my $code_ref = $thing->can('method_name');
 155   $code_ref->($thing, @args);
 156
 157 while if a C<::> is found, the lookup is made relative to the package name
 158 (i.e. everything before the last C<::>) so
 159
 160   $thing->Package::Name::method_name(@args);
 161
 162 is roughly equivalent to:
 163
 164   my $code_ref = Package::Name->can('method_name');
 165   $code_ref->($thing, @args);
 166
 167 So since L<Import::Into> defines a method C<into> in package C<import>
 168 the syntax reliably calls that.
 169
 170 For more craziness of this order, have a look at the article I wrote at
 171 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
 172 coderef abuse and the C<${\...}> syntax.
 173
 174 Final note: You do still need to ensure that you already loaded C<$thing> - if
 175 you're receiving this from a parameter, I recommend using L<Module::Runtime>:
 176
 177   use Import::Into;
 178   use Module::Runtime qw(use_module);
 179
 180   use_module($thing)->import::into($target, @import_args);
 181
 182 And that's it.
 183
 184 =head1 ACKNOWLEDGEMENTS
 185
 186 Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
 187 turned on for all consumers of my code?" and then "why is this not a
 188 module?!".
 189
 190 =head1 AUTHOR
 191
 192 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 193
 194 =head1 CONTRIBUTORS
 195
 196 None yet - maybe this software is perfect! (ahahahahahahahahaha)
 197
 198 =head1 COPYRIGHT
 199
 200 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
 201 as listed above.
 202
 203 =head1 LICENSE
 204
 205 This library is free software and may be distributed under the same terms
 206 as perl itself.