Apply environment expansion to options in .stowrc files

Expand environment variables used in stowrc, as requested in

    https://savannah.gnu.org/bugs/?41826

This is achieved by creating a new function expand_environment() that
replaces any substring of the form '$VAR' or '${VAR}' with contents of
environment variable $VAR.  Literal '$' can be given by '\$'.

N.B. The function is only applied to the --target and --dir options,
and only for options specified in .stowrc; cli options are left
untouched.

Undefined variables are expanded to the empty string, as they would be
in normal shell parameter expansion.

Unit tests added accordingly:

  - Test expand_environment():
    * Expand $HOME
    * Expand ${HOME}
    * Expand ${WITH SPACE}
    * Expand '\$HOME'. Expected is '$HOME'
    * Expand ${UNDEFINED}. Expected is ''.

  - Test that it's applied to the correct options.

  - Test that CLI options are not expanded.

t/cli_options.t

@@ -7,7 +7,7 @@
 use strict;
 use warnings;
 
-use Test::More tests => 9;
+use Test::More tests => 10;
 
 use testutil;
 
@@ -82,5 +82,16 @@ local @ARGV = (
 ($options, $pkgs_to_delete, $pkgs_to_stow) = process_options();
 is_deeply($options->{ignore}, [ qr(~\z), qr(\.#.*\z) ] => 'ignore temp files');
 
+#
+# Check that expansion not applied.
+#
+local @ARGV = (
+    "--target=$OUT_DIR/".'$HOME',
+    'dummy'
+);
+make_dir("$OUT_DIR/".'$HOME');
+($options, $pkgs_to_delete, $pkgs_to_stow) = process_options();
+is($options->{target}, "$OUT_DIR/".'$HOME', 'no expansion');
+remove_dir("$OUT_DIR/".'$HOME');
 
 # vim:ft=perl

t/rc_options.t

@@ -7,7 +7,7 @@
 use strict;
 use warnings;
 
-use Test::More tests => 4;
+use Test::More tests => 15;
 
 use testutil;
 
@@ -72,6 +72,64 @@ make_file($RC_FILE, $rc_contents);
 is_deeply($options->{defer}, [qr(\Ainfo), qr(\Aman)],
           'defer man and info');
 
+# ======== Filepath Expansion Tests ========
+# Test proper filepath expansion in rc file.
+# Expansion is only applied to options that
+# take a filepath, namely target and dir.
+# ==========================================
+
+
+#
+# Test environment variable expansion function.
+#
+# Basic expansion
+is(expand_environment('$HOME/stow'), "$OUT_DIR/stow", 'expand $HOME');
+is(expand_environment('${HOME}/stow'), "$OUT_DIR/stow", 'expand ${HOME}');
+
+delete $ENV{UNDEFINED}; # just in case
+foreach my $var ('$UNDEFINED', '${UNDEFINED}') {
+  eval {
+    expand_environment($var, "--foo option");
+  };
+  is(
+    $@,
+    "--foo option references undefined environment variable \$UNDEFINED; " .
+    "aborting!\n",
+    "expand $var"
+  );
+}
+
+# Expansion with an underscore.
+$ENV{'WITH_UNDERSCORE'} = 'test string';
+is(expand_environment('${WITH_UNDERSCORE}'), 'test string',
+    'expand ${WITH_UNDERSCORE}');
+delete $ENV{'WITH_UNDERSCORE'};
+# Expansion with escaped $
+is(expand_environment('\$HOME/stow'), '$HOME/stow', 'expand \$HOME');
+
+#
+# Test that environment variable expansion is applied.
+#
+$rc_contents = <<'HERE';
+--dir=$HOME/stow
+--target=$HOME/stow
+--ignore=\$HOME
+--defer=\$HOME
+--override=\$HOME
+HERE
+make_file($RC_FILE, $rc_contents);
+($options, $pkgs_to_delete, $pkgs_to_stow) = get_config_file_options();
+is($options->{dir}, "$OUT_DIR/stow",
+    "apply environment expansion on stowrc --dir");
+is($options->{target}, "$OUT_DIR/stow",
+    "apply environment expansion on stowrc --target");
+is_deeply($options->{ignore}, [qr(\$HOME\z)],
+    "environment expansion not applied on --ignore");
+is_deeply($options->{defer}, [qr(\A\$HOME)],
+    "environment expansion not applied on --defer");
+is_deeply($options->{override}, [qr(\A\$HOME)],
+    "environment expansion not applied on --override");
+
 # Clean up files used for testing.
 #
 unlink $RC_FILE or die "Unable to clean up $RC_FILE.\n";