Prep for releasing 1.001000.

[p5sagit/local-lib.git] / lib / local / lib.pm

diff --git a/lib/local/lib.pm b/lib/local/lib.pm
index 013fe87..ef47d5d 100644 (file)
--- a/lib/local/lib.pm
+++ b/lib/local/lib.pm
@@ -11,7 +11,7 @@ use File::Path ();
 use Carp ();
 use Config;
 
-our $VERSION = '1.000000'; # 1.0.0
+our $VERSION = '1.001000'; # 1.1.0
 
 sub import {
   my ($class, $path) = @_;
@@ -38,7 +38,9 @@ sub pipeline {
   }
 }
 
-=for test pipeline
+=begin testing
+
+#:: test pipeline
 
 package local::lib;
 
@@ -46,6 +48,8 @@ package local::lib;
 my $foo = bless({}, 'Foo');                                                 
 Test::More::ok($foo->${pipeline qw(foo bar baz)}(10) == -15);
 
+=end testing
+
 =cut
 
 sub resolve_path {
@@ -66,17 +70,23 @@ sub resolve_empty_path {
   }
 }
 
-=for test classmethod setup
+=begin testing
+
+#:: test classmethod setup
 
 my $c = 'local::lib';
 
-=cut
+=end testing
+
+=begin testing
 
-=for test classmethod
+#:: test classmethod
 
 is($c->resolve_empty_path, '~/perl5');
 is($c->resolve_empty_path('foo'), 'foo');
 
+=end testing
+
 =cut
 
 sub resolve_home_path {
@@ -120,11 +130,15 @@ sub resolve_relative_path {
   File::Spec->rel2abs($path);
 }
 
-=for test classmethod
+=begin testing
+
+#:: test classmethod
 
 local *File::Spec::rel2abs = sub { shift; 'FOO'.shift; };
 is($c->resolve_relative_path('bar'),'FOObar');
 
+=end testing
+
 =cut
 
 sub setup_local_lib_for {
@@ -188,6 +202,7 @@ sub print_environment_vars_for {
   my ($class, $path) = @_;
   my @envs = $class->build_environment_vars_for($path, LITERAL_PATH);
   my $out = '';
+
   # rather basic csh detection, goes on the assumption that something won't
   # call itself csh unless it really is. also, default to bourne in the
   # pathological situation where a user doesn't have $ENV{SHELL} defined.
@@ -198,20 +213,38 @@ sub print_environment_vars_for {
       my @shell_bin_path_parts = File::Spec->splitpath($ENV{'SHELL'});
       $shellbin = $shell_bin_path_parts[-1];
   }
+  my $shelltype = do {
+      local $_ = $shellbin;
+      if(/csh/) {
+          'csh'
+      } else {
+          'bourne'
+      }
+  };
+
   while (@envs) {
     my ($name, $value) = (shift(@envs), shift(@envs));
     $value =~ s/(\\")/\\$1/g;
-
-    if($shellbin =~ /csh/) {
-      $out .= qq{setenv ${name} "${value}"\n};
-    }
-    else {
-      $out .= qq{export ${name}="${value}"\n};
-    }
+    $out .= $class->${\"build_${shelltype}_env_declaration"}($name, $value);
   }
   print $out;
 }
 
+# simple routines that take two arguments: an %ENV key and a value. return
+# strings that are suitable for passing directly to the relevant shell to set
+# said key to said value.
+sub build_bourne_env_declaration {
+  my $class = shift;
+  my($name, $value) = @_;
+  return qq{export ${name}="${value}"\n};
+}
+
+sub build_csh_env_declaration {
+  my $class = shift;
+  my($name, $value) = @_;
+  return qq{setenv ${name} "${value}"\n};
+}
+
 sub setup_env_hash_for {
   my ($class, $path) = @_;
   my %envs = $class->build_environment_vars_for($path, INTERPOLATE_PATH);
@@ -236,7 +269,9 @@ sub build_environment_vars_for {
   )
 }
 
-=for test classmethod
+=begin testing
+
+#:: test classmethod
 
 File::Path::rmtree('t/var/splat');
 
@@ -246,6 +281,8 @@ ok(-d 't/var/splat');
 
 ok(-f 't/var/splat/.modulebuildrc');
 
+=end testing
+
 =head1 NAME
 
 local::lib - create and use a local lib/ for perl modules with PERL5LIB
@@ -258,6 +295,10 @@ In code -
 
   use local::lib '~/foo'; # same, but ~/foo
 
+  # Or...
+  use FindBin;
+  use local::lib "$FindBin::Bin/../support";  # app-local support library
+
 From the shell -
 
   $ perl -Mlocal::lib
@@ -292,11 +333,37 @@ appropriate for the user's current shell (as specified by the C<SHELL>
 environment variable), suitable for directly adding to one's shell configuration
 file.
 
+More generally, local::lib allows for the bootstrapping and usage of a directory
+containing Perl modules outside of Perl's C<@INC>. This makes it easier to ship
+an application with an app-specific copy of a Perl module, or collection of
+modules. Useful in cases like when an upstream maintainer hasn't applied a patch
+to a module of theirs that you need for your application.
+
+On import, local::lib sets the following environment variables to appropriate
+values:
+
+=over 4
+
+=item MODULEBUILDRC
+
+=item PERL_MM_OPT
+
+=item PERL5LIB
+
+=item PATH
+
+PATH is appended to, rather than clobbered.
+
+=back
+
+These values are then available for reference by any code after import.
+
 =head1 LIMITATIONS
 
 Rather basic shell detection. Right now anything with csh in its name is
 assumed to be a C shell or something compatible, and everything else is assumed
-to be Bourne.
+to be Bourne. If the C<SHELL> environment variable is not set, a
+Bourne-compatible shell is assumed.
 
 Bootstrap is a hack and will use CPAN.pm for ExtUtils::MakeMaker even if you
 have CPANPLUS installed.
@@ -322,6 +389,8 @@ commands to add to the shell configuration file.
 
 Matt S Trout <mst@shadowcat.co.uk> http://www.shadowcat.co.uk/
 
+auto_install fixes kindly sponsored by http://www.takkle.com/
+
 =head1 LICENSE
 
 This library is free software under the same license as perl itself