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