Merge branch 'shadowcat-mst:master' into plenv

Author: djerius

Changes

@@ -1,4 +1,14 @@
+0.902003 - 2021-11-25
+  - Restore 'plx t/foo.t' feature
+
+0.902002 - 2021-11-09
+  - Fix pod typo
+
+0.902001 - 2021-11-09
+  - Add support for prepending environment variables to --cmd/--perl/--exec
   - Make plx-packed handle being invoked via | perl -
+  - Set PERL_PLX_BASE env var inside invocations
+  - Handle falsish config values
 
 0.901001 - 2020-05-30
   - Add extra commands and user bootstrap code

README.md

@@ -30,7 +30,7 @@ environments, using them can still be a little on the lumpy side. With
     perl -Ilocal/lib/perl -Ilib bin/myapp
     carton exec perl -Ilib bin/myapp
 
-With [App::perlbrew](https://metacpan.org/pod/App::perlbrew),
+With [App::perlbrew](https://metacpan.org/pod/App%3A%3Aperlbrew),
 
     perlbrew switch perl-5.28.0@libname
     perl -Ilib bin/myapp
@@ -40,7 +40,7 @@ With [https://github.com/tokuhirom/plenv](https://github.com/tokuhirom/plenv),
     plenv exec perl -Ilib bin/myapp
 
 and if you have more than one distinct layer of dependencies, while
-[local::lib](https://metacpan.org/pod/local::lib) will happily handle that, integrating it with everything else
+[local::lib](https://metacpan.org/pod/local%3A%3Alib) will happily handle that, integrating it with everything else
 becomes a pain in the buttocks.
 
 As a result of this, your not-so-humble author found himself regularly having
@@ -62,7 +62,7 @@ However, much like back in 2007 frustration with explaining to other
 developers how to set up [CPAN](https://metacpan.org/pod/CPAN) to install into `~/perl5` and how to
 set up one's environment variables to then find the modules so installed
 led to the exercise in rage driven development that first created
-[local::lib](https://metacpan.org/pod/local::lib), walking newbies through the creation and subsequent use of
+[local::lib](https://metacpan.org/pod/local%3A%3Alib), walking newbies through the creation and subsequent use of
 such a script was not the most enjoyable experience for anybody involved.
 
 Thus, the creation of this module to reduce the setup process to:
@@ -77,7 +77,7 @@ Follwed by being able to immediately (and even more concisely) run:
     plx myapp
 
 which will execute `perl -Ilib bin/myapp` with the correct `perl` and the
-relevant [local::lib](https://metacpan.org/pod/local::lib) already in scope.
+relevant [local::lib](https://metacpan.org/pod/local%3A%3Alib) already in scope.
 
 If this seems of use to you, the ["QUICKSTART"](#quickstart) is next and the ["ACTIONS"](#actions)
 section of this document lists the full capabilities of plx. Onwards!
@@ -114,7 +114,7 @@ library, then we'd also want to run:
 
     plx --config libspec add 40otherlib.dir ../Other-Lib/lib
 
-If we want our ~/perl [local::lib](https://metacpan.org/pod/local::lib) available within the plx environment, we
+If we want our ~/perl [local::lib](https://metacpan.org/pod/local%3A%3Alib) available within the plx environment, we
 can add that as the least significant libspec with:
 
     plx --config libspec add 00tilde.ll $HOME/perl5
@@ -145,9 +145,36 @@ installer available, you can run:
 
 to get the current latest packed version.
 
-The packed version bundled [local::lib](https://metacpan.org/pod/local::lib) and [File::Which](https://metacpan.org/pod/File::Which), and also includes
+The packed version bundles [local::lib](https://metacpan.org/pod/local%3A%3Alib) and [File::Which](https://metacpan.org/pod/File%3A%3AWhich), and also includes
 a modified `--cpanm` action that uses an inline `App::cpanminus`.
 
+# ENVIRONMENT
+
+`plx` actions that execute external commands all clear any existing
+environment variables that start with `PERL` to keep an encapsulated setup
+for commands being run within the layouts - and also set `PERL5OPT` to
+exclude `site_perl` (but not `vendor_perl`) to avoid locally installed
+modules causing unexpected effects.
+
+Having done so, `plx` then loads each env config entry and sets those
+variables - then prepends the `plx` specific entries to both `PATH` and
+`PERL5LIB`. You can add env config entries with ["--config"](#config):
+
+    plx --config env add NAME VALUE
+
+The changes that will be made to your environment can be output by calling
+the ["--env"](#env) command.
+
+Additionally, environment variable overrides may be provided to the
+["--cmd"](#cmd), ["--exec"](#exec) and ["--perl"](#perl) commands by providing them in
+ `NAME=VALUE` format:
+
+    # do not do this, it will be deleted
+    PERL_RL=Perl5 plx <something>
+
+    # do this instead, it will provide the environment variable to the command
+    plx PERL_RL=Perl5 <something>
+
 # ACTIONS
 
     plx --help                             # Print synopsis
@@ -280,11 +307,11 @@ syntax that is (hopefully) correct for your current shell.
 Finds the `cpanm` binary in the `PATH` that `plx` was executed _from_,
 and executes it using the layout's perl binary and environment variables.
 
-Requires the user to specify a [local::lib](https://metacpan.org/pod/local::lib) to install into via `-l` or
+Requires the user to specify a [local::lib](https://metacpan.org/pod/local%3A%3Alib) to install into via `-l` or
 `-L` in order to avoid installing modules into unexpected places.
 
 Note that this action exists primarily for bootstrapping, and if you want
-to use a different installer such as [App::cpm](https://metacpan.org/pod/App::cpm), you'd install it with:
+to use a different installer such as [App::cpm](https://metacpan.org/pod/App%3A%3Acpm), you'd install it with:
 
     plx --cpanm -ldevel App::cpm
 
@@ -324,7 +351,7 @@ layout's perl with the given options and arguments.
         exists bin/<name>      -> --perl bin/<name> <args>
         else                   -> --exec <name> <args>
 
-**Note**: Much like the `devel` [local::lib](https://metacpan.org/pod/local::lib) is created to allow for the
+**Note**: Much like the `devel` [local::lib](https://metacpan.org/pod/local%3A%3Alib) is created to allow for the
 installation of out-of-band dependencies that aren't going to be needed in
 production, the `dev` directory is supported to allow for the easy addition
 of development time only sugar commands. Note that since `perl` will re-exec
@@ -390,7 +417,7 @@ The part of the name before the last `.` is not semantically significant to
 plx, but is used for asciibetical sorting of the libspec entries to determine
 in which order to apply them.
 
-The part after must be either `ll` for a [local::lib](https://metacpan.org/pod/local::lib), or `dir` for a bare
+The part after must be either `ll` for a [local::lib](https://metacpan.org/pod/local%3A%3Alib), or `dir` for a bare
 [lib](https://metacpan.org/pod/lib) directory.
 
 When loaded, the spec is (if relative) resolved to an absolute path relative
@@ -438,8 +465,8 @@ libspec pointing at `$HOME/perl5`.
 
 ## --installself
 
-Installs [App::plx](https://metacpan.org/pod/App::plx) and [App::cpanminus](https://metacpan.org/pod/App::cpanminus) into the highest-numbered
-[local::lib](https://metacpan.org/pod/local::lib) within the layout.
+Installs [App::plx](https://metacpan.org/pod/App%3A%3Aplx) and [App::cpanminus](https://metacpan.org/pod/App%3A%3Acpanminus) into the highest-numbered
+[local::lib](https://metacpan.org/pod/local%3A%3Alib) within the layout.
 
 ## --installenv
 

bin/plx

@@ -2,7 +2,7 @@
 
 package App::plx;
 
-our $VERSION = '0.901001'; # 0.901.1
+our $VERSION = '0.902003'; # 0.902.3
 
 $VERSION = eval $VERSION;
 
@@ -345,20 +345,27 @@ sub run_action_init {
 }
 
 sub _which {
-  my ($self, $cmd, @args) = @_;
+  my ($self, @args) = @_;
   $self->ensure_layout_config_dir;
+
+  my @env;
+
+  push @env, shift @args while $args[0] =~ /^\w+=/;
+
+  my $cmd = shift @args;
+
   barf "--cmd <cmd> <args>" unless $cmd;
 
   if ($fs->file_name_is_absolute($cmd)) {
-    return (exec => $cmd => @args);
+    return (exec => @env => $cmd => @args);
   }
 
   if ($cmd eq 'perl') {
-    return (perl => @args);
+    return (perl => @env => @args);
   }
 
   if ($cmd =~ m{/}) {
-    return (perl => $cmd, @args);
+    return (perl => @env => $cmd, @args);
   }
 
   if ($cmd =~ /^-/) {
@@ -373,16 +380,16 @@ sub _which {
       }
       last;
     }
-    return (perl => @optargs);
+    return (perl => @env => @optargs);
   }
 
   foreach my $dirname ($self->cmd_search_path) {
     if (-f (my $file = $self->layout_file($dirname => $cmd))) {
-      return (perl => $file, @args);
+      return (perl => @env => $file, @args);
     }
   }
 
-  return (exec => $cmd, @args);
+  return (exec => @env => $cmd, @args);
 }
 
 sub run_action_which {
@@ -391,7 +398,7 @@ sub run_action_which {
   say join(' ', 'plx', "--${action}", @call);
 }
 
-sub run_action_run {
+sub run_action_cmd {
   my ($self, @args) = @_;
   my ($action, @call) = $self->_which(@args);
   $self->${\"run_action_${action}"}(@call);
@@ -401,13 +408,18 @@ sub run_action_perl {
   my ($self, @call) = @_;
   $self->ensure_layout_config_dir;
   return $self->show_config_perl unless @call;
-  $self->run_action_exec($self->layout_perl, @call);
+  my @env;
+  push @env, shift @call while $call[0] =~ /^\w+=/;
+  $self->run_action_exec(@env, $self->layout_perl, @call);
 }
 
 sub run_action_exec {
   my ($self, @exec) = @_;
   $self->ensure_layout_config_dir;
   $self->setup_env;
+
+  shift @exec and $ENV{$1} = $2 while $exec[0] =~ /^(\w+)=(.*)$/;
+
   exec(@exec) or barf "exec of (".join(' ', @exec).") failed: $!";
 }
 
@@ -605,12 +617,11 @@ sub _parse_multi {
   my ($self, @args) = @_;
   my @multi;
   MULTI: while (@args) {
-    barf "Expected multi arg {, got: $args[0]" unless $args[0] eq '{';
+    barf "Expected multi arg [, got: $args[0]" unless $args[0] eq '[';
     shift @args;
     my @action;
-    /^--/ or s/^/--/ for @args ? $args[0] : ();
     while (my $el = shift @args) {
-      push @multi, \@action and next MULTI if $el eq '}';
+      push @multi, \@action and next MULTI if $el eq ']';
       push @action, $el;
     }
     barf "Missing closing ] for multi";
@@ -643,7 +654,7 @@ sub run_action_showmulti {
 sub run {
   my ($self, $cmd, @args) = @_;
   $cmd ||= '--help';
-  if ($cmd eq '{') {
+  if ($cmd eq '[') {
     return $self->run_action_multi($cmd, @args);
   }
   if ($cmd =~ s/^--//) {
@@ -657,7 +668,7 @@ sub run {
     $cmd = shift @args;
   }
   $self->ensure_layout_config_dir;
-  return $self->run_action_run($cmd, @args);
+  return $self->run_action_cmd($cmd, @args);
 }
 
 caller() ? 1 : __PACKAGE__->new->run(@ARGV);
@@ -809,9 +820,36 @@ installer available, you can run:
 
 to get the current latest packed version.
 
-The packed version bundled L<local::lib> and L<File::Which>, and also includes
+The packed version bundles L<local::lib> and L<File::Which>, and also includes
 a modified C<--cpanm> action that uses an inline C<App::cpanminus>.
 
+=head1 ENVIRONMENT
+
+C<plx> actions that execute external commands all clear any existing
+environment variables that start with C<PERL> to keep an encapsulated setup
+for commands being run within the layouts - and also set C<PERL5OPT> to
+exclude C<site_perl> (but not C<vendor_perl>) to avoid locally installed
+modules causing unexpected effects.
+
+Having done so, C<plx> then loads each env config entry and sets those
+variables - then prepends the C<plx> specific entries to both C<PATH> and
+C<PERL5LIB>. You can add env config entries with L</--config>:
+
+  plx --config env add NAME VALUE
+
+The changes that will be made to your environment can be output by calling
+the L</--env> command.
+
+Additionally, environment variable overrides may be provided to the
+L</--cmd>, L</--exec> and L</--perl> commands by providing them in
+ C<NAME=VALUE> format:
+
+  # do not do this, it will be deleted
+  PERL_RL=Perl5 plx <something>
+
+  # do this instead, it will provide the environment variable to the command
+  plx PERL_RL=Perl5 <something>
+
 =head1 ACTIONS
 
   plx --help                             # Print synopsis
@@ -843,7 +881,7 @@ a modified C<--cpanm> action that uses an inline C<App::cpanminus>.
   plx --exec <cmd> <args>                # exec()s with env vars set
   plx --perl <args>                      # Run perl with args
 
-  plx --run <cmd> <args>                 # DWIM command:
+  plx --cmd <cmd> <args>                 # DWIM command:
   
     cmd = perl           -> --perl <args>
     cmd = -<flag>        -> --perl -<flag> <args>
@@ -855,15 +893,15 @@ a modified C<--cpanm> action that uses an inline C<App::cpanminus>.
       exists bin/<name>      -> --perl bin/<name> <args>
       else                   -> --exec <name> <args>
 
-  plx --which <cmd>                      # Expands --run <cmd> without running
+  plx --which <cmd>                      # Expands --cmd <cmd> without running
   
-  plx <something> <args>                 # Shorthand for plx --run
+  plx <something> <args>                 # Shorthand for plx --cmd
   
   plx --commands <filter>?               # List available commands
   
-  plx --multi { <cmd1> <args1> } { ... } # Run multiple actions
-  plx --showmulti { ... } { ... }        # Show multiple action running
-  plx { ... } { ... }                    # Shorthand for plx --multi
+  plx --multi [ <cmd1> <args1> ] [ ... ] # Run multiple actions
+  plx --showmulti [ ... ] [ ... ]        # Show multiple action running
+  plx [ ... ] [ ... ]                    # Shorthand for plx --multi
   
   plx --userinit <perl>                  # Init ~/.plx with ~/perl5 ll
   plx --installself                      # Installs plx and cpanm into layout
@@ -974,9 +1012,9 @@ Without arguments, sugar for C<--config perl>.
 Otherwise, sets up the layout's environment variables and C<exec>s the
 layout's perl with the given options and arguments.
 
-=head2 --run
+=head2 --cmd
 
-  plx --run <cmd> <args>
+  plx --cmd <cmd> <args>
   
     cmd = perl           -> --perl <args>
     cmd = -<flag>        -> --perl -<flag> <args>
@@ -1002,7 +1040,7 @@ anything with a non-perl shebang, one can add wrappers here ala:
 
   plx --which <cmd>
 
-Outputs the expanded form of a C<--run> invocation without running it.
+Outputs the expanded form of a C<--cmd> invocation without running it.
 
 =head2 --config
 
@@ -1085,15 +1123,13 @@ stripped and the filter is treated as a regexp.
 
 =head2 --multi
 
-  plx --multi { --init } { --config perl set 5.28.0 }
-  plx --multi { init } { config perl set 5.28.0 }
+  plx --multi [ --init ] [ --config perl set 5.28.0 ]
 
 Runs multiple plx commands from a single invocation delimited by C<[ ... ]>.
 
 =head2 --showmulti
 
-  plx --showmulti { --init } { --config perl set 5.28.0 }
-  plx --showmulti { init } { config perl set 5.28.0 }
+  plx --showmulti [ --init ] [ --config perl set 5.28.0 ]
 
 Outputs approximate plx invocations that would be run by C<--multi>.