lib/Import/Into.pm

   1 package Import::Into;
   2
   3 use strict;
   4 use warnings FATAL => 'all';
   5 use Module::Runtime;
   6
   7 our $VERSION = '1.002005';
   8
   9 sub _prelude {
  10   my $target = shift;
  11   my ($package, $file, $line, $level)
  12     = ref $target         ? @{$target}{qw(package filename line level)}
  13     : $target =~ /[^0-9]/ ? ($target)
  14                           : (undef, undef, undef, $target);
  15   if (defined $level) {
  16     my ($p, $fn, $ln) = caller($level + 2);
  17     $package ||= $p;
  18     $file    ||= $fn;
  19     $line    ||= $ln;
  20   }
  21   qq{package $package;\n}
  22     . ($file ? "#line $line \"$file\"\n" : '')
  23 }
  24
  25 sub _make_action {
  26   my ($action, $target) = @_;
  27   my $version = ref $target && $target->{version};
  28   eval _prelude($target)
  29     . q[sub {]
  30     . q[  my $module = shift;]
  31     . q[  Module::Runtime::require_module($module);]
  32     . (ref $target && exists $target->{version} ? q[  $module->VERSION($version);] : q[])
  33     . q[  $module->].$action.q[(@_);]
  34     . q[}]
  35     or die "Failed to build action sub to ${action} for ${target}: $@";
  36 }
  37
  38 sub import::into {
  39   my ($class, $target, @args) = @_;
  40   _make_action(import => $target)->($class, @args);
  41 }
  42
  43 sub unimport::out_of {
  44   my ($class, $target, @args) = @_;
  45   _make_action(unimport => $target)->($class, @args);
  46 }
  47
  48 1;
  49
  50 __END__
  51
  52 =head1 NAME
  53
  54 Import::Into - Import packages into other packages
  55
  56 =head1 SYNOPSIS
  57
  58   package My::MultiExporter;
  59
  60   use Import::Into;
  61
  62   # simple
  63   sub import {
  64     Thing1->import::into(scalar caller);
  65   }
  66
  67   # multiple
  68   sub import {
  69     my $target = caller;
  70     Thing1->import::into($target);
  71     Thing2->import::into($target, qw(import arguments));
  72   }
  73
  74   # by level
  75   sub import {
  76     Thing1->import::into(1);
  77   }
  78
  79   # with exporter
  80   use base qw(Exporter);
  81   sub import {
  82     shift->export_to_level(1);
  83     Thing1->import::into(1);
  84   }
  85
  86   # no My::MultiExporter == no Thing1
  87   sub unimport {
  88     Thing1->unimport::out_of(scalar caller);
  89   }
  90
  91 People wanting to re-export your module should also be using L<Import::Into>.
  92 Any exporter or pragma will work seamlessly.
  93
  94 Note: You do B<not> need to make any changes to Thing1 to be able to call
  95 C<import::into> on it. This is a global method, and is callable on any
  96 package (and in fact on any object as well, although it's rarer that you'd
  97 want to do that).
  98
  99 =head1 DESCRIPTION
 100
 101 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
 102 some use L<Moose::Exporter>, some use L<Exporter::Declare> ... and some things
 103 are pragmas.
 104
 105 Exporting on someone else's behalf is harder.  The exporters don't provide a
 106 consistent API for this, and pragmas need to have their import method called
 107 directly, since they effect the current unit of compilation.
 108
 109 C<Import::Into> provides global methods to make this painless.
 110
 111 =head1 METHODS
 112
 113 =head2 $package->import::into( $target, @arguments );
 114
 115 A global method, callable on any package.  Loads and imports the given package
 116 into C<$target>.  C<@arguments> are passed along to the package's import method.
 117
 118 C<$target> can be an package name to export to, an integer for the
 119 caller level to export to, or a hashref with the following options:
 120
 121 =over 4
 122
 123 =item package
 124
 125 The target package to export to.
 126
 127 =item filename
 128
 129 The apparent filename to export to.  Some exporting modules, such as
 130 L<autodie> or L<strictures>, care about the filename they are being imported
 131 to.
 132
 133 =item line
 134
 135 The apparent line number to export to.  To be combined with the C<filename>
 136 option.
 137
 138 =item level
 139
 140 The caller level to export to.  This will automatically populate the
 141 C<package>, C<filename>, and C<line> options, making it the easiest most
 142 constent option.
 143
 144 =item version
 145
 146 A version number to check for the module.  The equivalent of specifying the
 147 version number on a C<use> line.
 148
 149 =back
 150
 151 =head2 $package->unimport::out_of( $target, @arguments );
 152
 153 Equivalent to C<import::into>, but dispatches to C<$package>'s C<unimport>
 154 method instead of C<import>.
 155
 156 =head1 WHY USE THIS MODULE
 157
 158 The APIs for exporting modules aren't consistent.  L<Exporter> subclasses
 159 provide export_to_level, but if they overrode their import method all bets
 160 are off.  L<Sub::Exporter> provides an into parameter but figuring out
 161 something used it isn't trivial. Pragmas need to have their C<import> method
 162 called directly since they affect the current unit of compilation.
 163
 164 It's ... annoying.
 165
 166 However, there is an approach that actually works for all of these types.
 167
 168   eval "package $target; use $thing;"
 169
 170 will work for anything checking caller, which is everything except pragmas.
 171 But it doesn't work for pragmas - pragmas need:
 172
 173   $thing->import;
 174
 175 because they're designed to affect the code currently being compiled - so
 176 within an eval, that's the scope of the eval itself, not the module that
 177 just C<use>d you - so
 178
 179   sub import {
 180     eval "use strict;"
 181   }
 182
 183 doesn't do what you wanted, but
 184
 185   sub import {
 186     strict->import;
 187   }
 188
 189 will apply L<strict> to the calling file correctly.
 190
 191 Of course, now you have two new problems - first, that you still need to
 192 know if something's a pragma, and second that you can't use either of
 193 these approaches alone on something like L<Moose> or L<Moo> that's both
 194 an exporter and a pragma.
 195
 196 So, a solution for that is:
 197
 198   use Module::Runtime;
 199   my $sub = eval "package $target; sub { use_module(shift)->import(\@_) }";
 200   $sub->($thing, @import_args);
 201
 202 which means that import is called from the right place for pragmas to take
 203 effect, and from the right package for caller checking to work - and so
 204 behaves correctly for all types of exporter, for pragmas, and for hybrids.
 205
 206 Additionally, some import routines check the filename they are being imported
 207 to.  This can be dealt with by generating a L<#line directive|perlsyn/Plain
 208 Old Comments (Not!)> in the eval, which will change what C<caller> reports for
 209 the filename when called in the importer. The filename and line number to use
 210 in the directive then need to be fetched using C<caller>:
 211
 212   my ($target, $file, $line) = caller(1);
 213   my $sub = eval qq{
 214     package $target;
 215   #line $line "$file"
 216     sub { use_module(shift)->import(\@_) }
 217   };
 218   $sub->($thing, @import_args);
 219
 220 And you need to switch between these implementations depending on if you are
 221 targeting a specific package, or something in your call stack.
 222
 223 Remembering all this, however, is excessively irritating. So I wrote a module
 224 so I didn't have to anymore. Loading L<Import::Into> creates a global method
 225 C<import::into> which you can call on any package to import it into another
 226 package. So now you can simply write:
 227
 228   use Import::Into;
 229
 230   $thing->import::into($target, @import_args);
 231
 232 This works because of how perl resolves method calls - a call to a simple
 233 method name is resolved against the package of the class or object, so
 234
 235   $thing->method_name(@args);
 236
 237 is roughly equivalent to:
 238
 239   my $code_ref = $thing->can('method_name');
 240   $code_ref->($thing, @args);
 241
 242 while if a C<::> is found, the lookup is made relative to the package name
 243 (i.e. everything before the last C<::>) so
 244
 245   $thing->Package::Name::method_name(@args);
 246
 247 is roughly equivalent to:
 248
 249   my $code_ref = Package::Name->can('method_name');
 250   $code_ref->($thing, @args);
 251
 252 So since L<Import::Into> defines a method C<into> in package C<import>
 253 the syntax reliably calls that.
 254
 255 For more craziness of this order, have a look at the article I wrote at
 256 L<http://shadow.cat/blog/matt-s-trout/madness-with-methods> which covers
 257 coderef abuse and the C<${\...}> syntax.
 258
 259 And that's it.
 260
 261 =head1 SEE ALSO
 262
 263 I gave a lightning talk on this module (and L<curry> and L<Safe::Isa>) at
 264 L<YAPC::NA 2013|https://www.youtube.com/watch?v=wFXWV2yY7gE&t=46m05s>.
 265
 266 =head1 ACKNOWLEDGEMENTS
 267
 268 Thanks to Getty for asking "how can I get C<< use strict; use warnings; >>
 269 turned on for all consumers of my code?" and then "why is this not a
 270 module?!".
 271
 272 =head1 AUTHOR
 273
 274 mst - Matt S. Trout (cpan:MSTROUT) <mst@shadowcat.co.uk>
 275
 276 =head1 CONTRIBUTORS
 277
 278 haarg - Graham Knop (cpan:HAARG) <haarg@haarg.org>
 279
 280 Mithaldu - Christian Walde (cpan:MITHALDU) <walde.christian@gmail.com>
 281
 282 =head1 COPYRIGHT
 283
 284 Copyright (c) 2012 the Import::Into L</AUTHOR> and L</CONTRIBUTORS>
 285 as listed above.
 286
 287 =head1 LICENSE
 288
 289 This library is free software and may be distributed under the same terms
 290 as perl itself.
 291
 292 =cut