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