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