[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
master 6d78321ce8 2/2: Merge from origin/emacs-28
From: |
Stefan Kangas |
Subject: |
master 6d78321ce8 2/2: Merge from origin/emacs-28 |
Date: |
Wed, 2 Mar 2022 01:03:45 -0500 (EST) |
branch: master
commit 6d78321ce824ede11ab04d976d46487bcd191cab
Merge: 2b130bd944 9dadcbe429
Author: Stefan Kangas <stefan@marxist.se>
Commit: Stefan Kangas <stefan@marxist.se>
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
---
doc/misc/eshell.texi | 54 ++++++++++++++++++++++++----------------
lisp/eshell/esh-var.el | 23 +++++++++++++----
test/lisp/eshell/eshell-tests.el | 4 +++
3 files changed, 55 insertions(+), 26 deletions(-)
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 261e88d00c..bbf8ca6b8b 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 5c8dacd980..ee3ffbc647 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 d6ee1bdb17..eff4edd62c 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)))