From: Jim Porter <jporterbugs@gmail.com>
To: 60846@debbugs.gnu.org
Subject: bug#60846: 29.0.60; [PATCH] Add more documentation about Eshell command invocation
Date: Sun, 15 Jan 2023 20:01:01 -0800 [thread overview]
Message-ID: <efd01f85-5d70-8112-71c9-133b14711b70@gmail.com> (raw)
In-Reply-To: <e5d0f9e6-357d-0d96-7047-15c7b4bfbb90@gmail.com>
[-- Attachment #1: Type: text/plain, Size: 87 bytes --]
Oops. Forgot to save the file, so I missed part of my update in the
patch. Fixed here.
[-- Attachment #2: 0001-Add-more-detail-about-how-to-invoke-Eshell-commands.patch --]
[-- Type: text/plain, Size: 5810 bytes --]
From e2e9e3257cdd5fde1256d8a0937ca7b2c6800588 Mon Sep 17 00:00:00 2001
From: Jim Porter <jporterbugs@gmail.com>
Date: Sun, 15 Jan 2023 18:35:31 -0800
Subject: [PATCH] Add more detail about how to invoke Eshell commands
* doc/misc/eshell.texi (Commands): Move explanation about kernel
functions to here.
(Invocation): Describe command form and Lisp form. Fix documentation
about priority of commands in command form.
---
doc/misc/eshell.texi | 103 +++++++++++++++++++++++++++++++++----------
1 file changed, 80 insertions(+), 23 deletions(-)
diff --git a/doc/misc/eshell.texi b/doc/misc/eshell.texi
index fc7d52eb711..2e8703059f1 100644
--- a/doc/misc/eshell.texi
+++ b/doc/misc/eshell.texi
@@ -193,6 +193,12 @@ Commands
chapter covers command invocations in Eshell, including the command
history and invoking commands in a script file.
+Unlike regular system shells, Eshell never invokes kernel functions
+directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
+available in the Emacs Lisp library. It does this by transforming the
+input line into a callable Lisp form.@footnote{To see the Lisp form
+that will be invoked, type: @samp{eshell-parse-command 'echo hello'}}
+
@menu
* Invocation::
* Arguments::
@@ -207,23 +213,16 @@ Commands
@node Invocation
@section Invocation
-Unlike regular system shells, Eshell never invokes kernel functions
-directly, such as @code{exec(3)}. Instead, it uses the Lisp functions
-available in the Emacs Lisp library. It does this by transforming the
-input line into a callable Lisp form.@footnote{To see the Lisp form that will be invoked, type: @samp{eshell-parse-command "echo hello"}}
+Eshell is both a command shell and an Emacs Lisp @acronym{REPL}. As a
+result, you can invoke commands in two different ways: in @dfn{command
+form} or in @dfn{lisp form}.
-The command can be either an Elisp function or an external command.
-Eshell looks first for an alias (@pxref{Aliases}) with the same name as the
-command, then a built-in (@pxref{Built-ins}) or a function with the
-same name; if there is no match, it then tries to execute it as an
-external command.
-
-The semicolon (@code{;}) can be used to separate multiple command
-invocations on a single line. You can also separate commands with
-@code{&&} or @code{||}. When using @code{&&}, Eshell will execute the
-second command only if the first succeeds (i.e.@: has an exit
-status of 0); with @code{||}, Eshell will execute the second command
-only if the first fails.
+You can use the semicolon (@code{;}) to separate multiple command
+invocations on a single line, executing each in turn. You can also
+separate commands with @code{&&} or @code{||}. When using @code{&&},
+Eshell will execute the second command only if the first succeeds
+(i.e.@: has an exit status of 0); with @code{||}, Eshell will execute
+the second command only if the first fails.
A command invocation followed by an ampersand (@code{&}) will be run
in the background. Eshell has no job control, so you can not suspend
@@ -232,12 +231,74 @@ Invocation
can be controlled the same way as any other background process in
Emacs.
+@subsection Command form
+Command form looks much the same as in other shells. A command
+consists of arguments separated by spaces; the first argument is the
+command to run, with any subsequent arguments being passed to that
+command.
+
+@example
+~ $ echo hello
+hello
+@end example
+
+The command can be either an Elisp function or an external command.
+Eshell looks for the command in the following order:
+
+@enumerate
+@item
+As a command alias (@pxref{Aliases})
+
+@item
+As a built-in command (@pxref{Built-ins})
+
+@item
+As an external program
+
+@item
+As an ordinary Lisp function
+@end enumerate
+
+@vindex eshell-prefer-lisp-functions
+If you would prefer to use ordinary Lisp functions over external
+programs, set the option @code{eshell-prefer-lisp-functions} to
+@code{t}.
+
+You can also group command forms together into a subcommand with curly
+braces (@code{@{@}}). This lets you use the output of a subcommand as
+an argument to another command, or within control flow statements
+(@pxref{Control Flow}).
+
+@example
+~ $ echo @{echo hello; echo there@}
+hellothere
+@end example
+
+@subsection Lisp form
+Lisp form looks like ordinary Emacs Lisp code, because that's what it
+is. As a result, you can use any syntax normally available to an
+Emacs Lisp program (@pxref{Top, , , elisp, The Emacs Lisp Reference
+Manual}).
+
+@example
+~ $ (format "hello, %s" user-login-name)
+hello, user
+@end example
+
+In addition, you can @emph{combine} command forms and Lisp forms
+together into single statements, letting you use whatever form is the
+most convenient for expressing your intentions.
+
+@example
+~ $ ls *.patch > (format-time-string "%F.log")
+@end example
+
@node Arguments
@section Arguments
-Ordinarily, command arguments are parsed by Eshell as either strings
+Ordinarily, Eshell parses arguments in command form as either strings
or numbers, depending on what the parser thinks they look like. To
-specify an argument of some other data type, you can use an
-@ref{Dollars Expansion, Elisp expression}:
+specify an argument of some other data type, you can use a
+@ref{Invocation, Lisp form}:
@example
~ $ echo (list 1 2 3)
@@ -354,10 +415,6 @@ Built-ins
sudo is an alias, defined as "*sudo $@@*"
@end example
-@vindex eshell-prefer-lisp-functions
-If you would prefer to use the built-in commands instead of the external
-commands, set @code{eshell-prefer-lisp-functions} to @code{t}.
-
Some of the built-in commands have different behavior from their
external counterparts, and some have no external counterpart. Most of
these will print a usage message when given the @code{--help} option.
--
2.25.1
next prev parent reply other threads:[~2023-01-16 4:01 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-01-16 2:51 bug#60846: 29.0.60; [PATCH] Add more documentation about Eshell command invocation Jim Porter
2023-01-16 4:01 ` Jim Porter [this message]
2023-01-16 13:38 ` Eli Zaretskii
2023-01-16 20:18 ` Jim Porter
2023-01-17 13:05 ` Eli Zaretskii
2023-01-17 22:01 ` 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=efd01f85-5d70-8112-71c9-133b14711b70@gmail.com \
--to=jporterbugs@gmail.com \
--cc=60846@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).