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