From: Jim Porter <jporterbugs@gmail.com>
To: 54190@debbugs.gnu.org
Subject: bug#54190: 29.0.50; [PATCH] Incorrect/missing documentation for some Eshell "$" syntaxes
Date: Sun, 27 Feb 2022 13:34:26 -0800 [thread overview]
Message-ID: <0c3898ff-23ac-51bc-2211-770302d7d00e@gmail.com> (raw)
[-- 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
next reply other threads:[~2022-02-27 21:34 UTC|newest]
Thread overview: 15+ messages / expand[flat|nested] mbox.gz Atom feed top
2022-02-27 21:34 Jim Porter [this message]
2022-02-28 6:11 ` bug#54190: 29.0.50; [PATCH] Incorrect/missing documentation for some Eshell "$" syntaxes 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: https://www.gnu.org/software/emacs/
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=0c3898ff-23ac-51bc-2211-770302d7d00e@gmail.com \
--to=jporterbugs@gmail.com \
--cc=54190@debbugs.gnu.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).