unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#54190: 29.0.50; [PATCH] Incorrect/missing documentation for some Eshell "$" syntaxes
@ 2022-02-27 21:34 Jim Porter
  2022-02-28  6:11 ` Jim Porter
  0 siblings, 1 reply; 15+ messages in thread
From: Jim Porter @ 2022-02-27 21:34 UTC (permalink / raw)
  To: 54190

[-- Attachment #1: Type: text/plain, Size: 1040 bytes --]

In the documentation for lisp/eshell/esh-var.el (and 
`eshell-parse-variable-ref' in that file), it says that "$<FOO>" is a 
way of accessing the value of the variable FOO to disambiguate the 
length of the variable name, sort of like "${FOO}" in ordinary shells. 
However, that's not actually true. The correct syntax for that is:

   $"FOO"
   ;; or...
   $'FOO'

In fact, what "$<FOO>" does is to run FOO as a subcommand, writing its 
stdout to a temp file, and returning that file's name. This is (very!) 
subtly implied in the Eshell manual in the "Bugs and ideas" section, 
where it says:

   `grep python $<rpm -qa>' doesn't work, but using `*grep' does

   This happens because the `grep' Lisp function returns immediately,
   and then the asynchronous `grep' process expects to examine the
   temporary file, which has since been deleted.

Attached is a patch which updates the documentation to correctly 
describe the current behavior. Note: since this is just a documentation 
change, it might be worth pushing to the 28 branch.

[-- Attachment #2: 0001-Improve-correct-documentation-about-Eshell-variable-.patch --]
[-- Type: text/plain, Size: 3050 bytes --]

From ec52b44f694f2515bb3673f998e6ea80d2d31e08 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Sun, 27 Feb 2022 13:20:51 -0800
Subject: [PATCH] Improve/correct documentation about Eshell variable expansion

* lisp/eshell/esh-var.el: Correct documentation comment.
(eshell-parse-variable-ref): Correct docstring.

* doc/misc/eshell.texi (Dollars Expansion): Add documentation for
$"var"/$'var' and $<command> syntaxes.
---
 doc/misc/eshell.texi   | 11 +++++++++++
 lisp/eshell/esh-var.el | 15 ++++++++++++---
 2 files changed, 23 insertions(+), 3 deletions(-)

diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index 261e88d00c..88a7d7b130 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -1016,6 +1016,12 @@ Dollars Expansion
 Expands to the value bound to @code{var}.  This is the main way to use
 variables in command invocations.
 
+@item $"var"
+@item $'var'
+Expands to the value bound to @code{var}.  This is useful to
+disambiguate the variable name when concatenating it with another
+value, such as @samp{$"var"-suffix}.
+
 @item $#var
 Expands to the length of the value bound to @code{var}.  Raises an error
 if the value is not a sequence
@@ -1030,6 +1036,11 @@ Dollars Expansion
 Returns the output of @command{command}, which can be any valid Eshell
 command invocation, and may even contain expansions.
 
+@item $<command>
+As with @samp{$@{command@}}, evaluates the Eshell command invocation
+@command{command}, but writes the output to a temporary file and
+returns the file name.
+
 @item $var[i]
 Expands to the @code{i}th element of the value bound to @code{var}.  If
 the value is a string, it will be split at whitespace to make it a list.
diff --git a/lisp/eshell/esh-var.el b/lisp/eshell/esh-var.el
index 5c8dacd980..cfefe15c9c 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 @@ eshell-parse-variable-ref
 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 ?\{ ?\})))
-- 
2.25.1


^ permalink raw reply related	[flat|nested] 15+ messages in thread
end of thread, other threads:[~2022-09-07  3:59 UTC | newest]

Thread overview: 15+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2022-02-27 21:34 bug#54190: 29.0.50; [PATCH] Incorrect/missing documentation for some Eshell "$" syntaxes Jim Porter
2022-02-28  6:11 ` Jim Porter
2022-02-28  8:16   ` Jim Porter
2022-02-28  9:38     ` Lars Ingebrigtsen
2022-02-28 13:18       ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-02-28 13:28         ` Eli Zaretskii
2022-02-28 17:47         ` Jim Porter
2022-03-01 13:10           ` Eli Zaretskii
2022-03-04  5:55             ` Jim Porter
2022-03-04  7:16               ` Eli Zaretskii
2022-03-04 13:35               ` Stefan Monnier via Bug reports for GNU Emacs, the Swiss army knife of text editors
2022-03-04 18:04                 ` Jim Porter
2022-09-06 11:28               ` Lars Ingebrigtsen
2022-09-07  3:50                 ` Jim Porter
2022-09-07  3:59                   ` Jim Porter

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).