From: Matt S Trout <mst@shadowcat.co.uk>
Date: Sat, 5 May 2012 19:28:40 +0000 (+0000)
Subject: expand docs and example
X-Git-Tag: v1.000002~2
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=8c17b6f8371a0afcdf3b7e7eccebf2f62e983f79;p=p5sagit%2FImport-Into.git

expand docs and example
---

diff --git a/Changes b/Changes
index 228dade..4beccf8 100644
--- a/Changes
+++ b/Changes
@@ -1,3 +1,5 @@
+  - improve explanation and add more examples to the SYNOPSIS
+
 1.000001 - 2012-05-03
   - correct NAME in Makefile.PL
 
diff --git a/lib/Import/Into.pm b/lib/Import/Into.pm
index 4ef0ab7..09488bb 100644
--- a/lib/Import/Into.pm
+++ b/lib/Import/Into.pm
@@ -38,6 +38,24 @@ Import::Into - import packages into other packages
     Thing2->import::into($target, qw(import arguments));
   }
 
+Note: you don't need to do anything more clever than this provided you
+document that people wanting to re-export your module should also be using
+L<Import::Into>. In fact, for a single module you can simply do:
+
+  sub import {
+    ...
+    Thing1->import::into(scalar caller);
+  }
+
+Notably, this works:
+
+  use base qw(Exporter);
+
+  sub import {
+    shift->export_to_level(1);
+    Thing1->import::into(scalar caller);
+  }
+
 =head1 DESCRIPTION
 
 Writing exporters is a pain. Some use L<Exporter>, some use L<Sub::Exporter>,
@@ -62,13 +80,35 @@ But it doesn't work for pragmas - pragmas need:
 
   $thing->import;
 
-So, the solution is:
+because they're designed to affect the code currently being compiled - so
+within an eval, that's the scope of the eval itself, not the module that
+just C<use>d you - so
+
+  sub import {
+    eval "use strict;"
+  }
+
+doesn't do what you wanted, but
+
+  sub import {
+    strict->import;
+  }
+
+will apply L<strict> to the calling file correctly.
+
+Of course, now you have two new problems - first, that you still need to
+know if something's a pragma, and second that you can't use either of
+these approaches alone on something like L<Moose> or L<Moo> that's both
+an exporter and a pragma.
+
+So, the complete solution is:
 
   my $sub = eval "package $target; sub { shift->import(\@_) }";
   $sub->($thing, @import_args);
 
 which means that import is called from the right place for pragmas to take
-effect, and from the right package for caller checking to work.
+effect, and from the right package for caller checking to work - and so
+behaves correctly for all types of exporter, for pragmas, and for hybrids.
 
 Remembering all this, however, is excessively irritating. So I wrote a module
 so I didn't have to anymore. Loading L<Import::Into> will create a method