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