Merge from origin/emacs-28

9dadcbe429 ; * doc/misc/eshell.texi (Dollars Expansion): Fix markup.
2c3d1b6bf4 Improve/correct documentation about Eshell variable expansion
9e257aecc9 Partially revert b03f74e0f2a578b1580e8b1c368665850ee7f808

3 files changed, 55 insertions, 26 deletions

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 261e88d00c6..bbf8ca6b8bd 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -1012,51 +1012,63 @@ of familiarity.
 
 @table @code
 
-@item $var
-Expands to the value bound to @code{var}.  This is the main way to use
+@item $@var{var}
+Expands to the value bound to @var{var}.  This is the main way to use
 variables in command invocations.
 
-@item $#var
-Expands to the length of the value bound to @code{var}.  Raises an error
+@item $"@var{var}"
+@item $'@var{var}'
+Expands to the value bound to @var{var}.  This is useful to
+disambiguate the variable name when concatenating it with another
+value, such as @samp{$"@var{var}"-suffix}.
+
+@item $#@var{var}
+Expands to the length of the value bound to @var{var}.  Raises an error
 if the value is not a sequence
 (@pxref{Sequences Arrays Vectors, Sequences, , elisp, The Emacs Lisp Reference Manual}).
 
-@item $(lisp)
-Expands to the result of evaluating the S-expression @code{(lisp)}.  On
-its own, this is identical to just @code{(lisp)}, but with the @code{$},
-it can be used in a string, such as @samp{/some/path/$(lisp).txt}.
+@item $(@var{lisp})
+Expands to the result of evaluating the S-expression @code{(@var{lisp})}.  On
+its own, this is identical to just @code{(@var{lisp})}, but with the @code{$},
+it can be used in a string, such as @samp{/some/path/$(@var{lisp}).txt}.
 
-@item $@{command@}
-Returns the output of @command{command}, which can be any valid Eshell
+@item $@{@var{command}@}
+Returns the output of @command{@var{command}}, which can be any valid Eshell
 command invocation, and may even contain expansions.
 
-@item $var[i]
-Expands to the @code{i}th element of the value bound to @code{var}.  If
+@item $<@var{command}>
+As with @samp{$@{@var{command}@}}, evaluates the Eshell command invocation
+@command{@var{command}}, but writes the output to a temporary file and
+returns the file name.
+
+@item $@var{var}[i]
+Expands to the @code{i}th element of the value bound to @var{var}.  If
 the value is a string, it will be split at whitespace to make it a list.
 Again, raises an error if the value is not a sequence.
 
-@item $var[: i]
+@item $@var{var}[: i]
 As above, but now splitting occurs at the colon character.
 
-@item $var[: i j]
+@item $@var{var}[: i j]
 As above, but instead of returning just a string, it now returns a list
 of two strings.  If the result is being interpolated into a larger
 string, this list will be flattened into one big string, with each
 element separated by a space.
 
-@item $var["\\\\" i]
+@item $@var{var}["\\\\" i]
 Separate on backslash characters.  Actually, the first argument -- if it
 doesn't have the form of a number, or a plain variable name -- can be
-any regular expression.  So to split on numbers, use @samp{$var["[0-9]+" 10 20]}.
+any regular expression.  So to split on numbers, use
+@samp{$@var{var}["[0-9]+" 10 20]}.
 
-@item $var[hello]
-Calls @code{assoc} on @code{var} with @code{"hello"}, expecting it to be
+@item $@var{var}[hello]
+Calls @code{assoc} on @var{var} with @code{"hello"}, expecting it to be
 an alist (@pxref{Association List Type, Association Lists, , elisp,
 The Emacs Lisp Reference Manual}).
 
-@item $#var[hello]
-Returns the length of the cdr of the element of @code{var} who car is equal
-to @code{"hello"}.
+@item $#@var{var}[hello]
+Returns the length of the @code{cdr} of the element of @var{var} whose
+car is equal to @code{"hello"}.
 
 @end table
 
diff --git a/lisp/eshell/esh-var.el b/lisp/eshell/esh-var.el
index 5c8dacd980e..ee3ffbc6475 100644
--- a/lisp/eshell/esh-var.el
+++ b/lisp/eshell/esh-var.el
@@ -34,7 +34,8 @@
 ;;
 ;; "-" is a valid part of a variable name.
 ;;
-;;   $<MYVAR>-TOO
+;;   $\"MYVAR\"-TOO
+;;   $'MYVAR'-TOO
 ;;
 ;; Only "MYVAR" is part of the variable name in this case.
 ;;
@@ -55,6 +56,11 @@
 ;; Returns the value of an eshell subcommand.  See the note above
 ;; regarding Lisp evaluations.
 ;;
+;;   $<command>
+;;
+;; Evaluates an eshell subcommand, redirecting the output to a
+;; temporary file, and returning the file name.
+;;
 ;;   $ANYVAR[10]
 ;;
 ;; Return the 10th element of ANYVAR.  If ANYVAR's value is a string,
@@ -423,9 +429,12 @@ variable.
 Possible options are:
 
   NAME          an environment or Lisp variable value
-  <LONG-NAME>   disambiguates the length of the name
+  \"LONG-NAME\"   disambiguates the length of the name
+  'LONG-NAME'   as above
   {COMMAND}     result of command is variable's value
-  (LISP-FORM)   result of Lisp form is variable's value"
+  (LISP-FORM)   result of Lisp form is variable's value
+  <COMMAND>     write the output of command to a temporary file;
+                result is the file name"
   (cond
    ((eq (char-after) ?{)
     (let ((end (eshell-find-delimiter ?\{ ?\})))
@@ -457,8 +466,12 @@ Possible options are:
                    (eshell-as-subcommand ,(eshell-parse-command cmd))
                    (ignore
                     (nconc eshell-this-command-hook
-                           (list (lambda ()
-                                   (delete-file ,temp)))))
+                           ;; Quote this lambda; it will be evaluated
+                           ;; by `eshell-do-eval', which requires very
+                           ;; particular forms in order to work
+                           ;; properly.  See bug#54190.
+                           (list (function (lambda ()
+                                   (delete-file ,temp))))))
                    (quote ,temp)))
             (goto-char (1+ end)))))))
    ((eq (char-after) ?\()
diff --git a/test/lisp/eshell/eshell-tests.el b/test/lisp/eshell/eshell-tests.el
index d6ee1bdb175..eff4edd62c7 100644
--- a/test/lisp/eshell/eshell-tests.el
+++ b/test/lisp/eshell/eshell-tests.el
@@ -93,6 +93,10 @@ e.g. \"{(+ 1 2)} 3\" => 3"
   "Interpolate Lisp form evaluation"
   (should (equal (eshell-test-command-result "+ $(+ 1 2) 3") 6)))
 
+(ert-deftest eshell-test/interp-temp-cmd ()
+  "Interpolate command result redirected to temp file"
+  (should (equal (eshell-test-command-result "cat $<echo hi>") "hi")))
+
 (ert-deftest eshell-test/interp-concat ()
   "Interpolate and concat command"
   (should (equal (eshell-test-command-result "+ ${+ 1 2}3 3") 36)))