File: esh-cmd.el.html

;_* Invoking external commands

External commands cause processes to be created, by loading external executables into memory. This is what most normal shells do, most of the time. For more information, see [External commands].

;_* Invoking Lisp functions

A Lisp function can be invoked using Lisp syntax, or command shell syntax. For example, to run dired to edit the current directory:

  /tmp $ (dired ".")

Or:

  /tmp $ dired .

The latter form is preferable, but the former is more precise, since it involves no translations. See [Argument parsing], to learn more about how arguments are transformed before passing them to commands.

Ordinarily, if 'dired' were also available as an external command, the external version would be called in preference to any Lisp function of the same name. To change this behavior so that Lisp functions always take precedence, set eshell-prefer-lisp-functions to t.

;_* Alias functions

Whenever a command is specified using a simple name, such as 'ls', Eshell will first look for a Lisp function of the name eshell/ls. If it exists, it will be called in preference to any other command which might have matched the name 'ls' (such as command aliases, external commands, Lisp functions of that name, etc).

This is the most flexible mechanism for creating new commands, since it does not pollute the global namespace, yet allows you to use all of Lisp's facilities to define that piece of functionality. Most of Eshell's "builtin" commands are defined as alias functions.

;_* Lisp arguments

It is possible to invoke a Lisp form as an argument. This can be done either by specifying the form as you might in Lisp, or by using the '$' character to introduce a value-interpolation:

  echo (+ 1 2)

Or

  echo $(+ 1 2)

The two forms are equivalent. The second is required only if the form being interpolated is within a string, or is a subexpression of a larger argument:

  echo x$(+ 1 2) "String $(+ 1 2)"

To pass a Lisp symbol as an argument, use the alternate quoting syntax, since the single quote character is far too overused in shell syntax:

  echo #'lisp-symbol

Backquote can also be used:

  echo (list ,lisp-symbol)


Lisp arguments are identified using the following regexp:


;_* Command hooks


There are several hooks involved with command execution, which can be used either to change or augment Eshells behavior.

Defined variables (24)

eshell--local-varsList of locally bound vars that should take precedence over env-vars.
eshell-allow-commandsIf non-nil, allow evaluating command forms (including Lisp forms).
eshell-background-commandsA list of currently-running deferred commands.
eshell-cmd-load-hookA hook that gets run when ‘eshell-cmd’ is loaded.
eshell-complex-commandsA list of commands names or functions, that determine complexity.
eshell-current-commandThe currently-running foreground command, if any.
eshell-deferrable-commandsA list of functions which might return a deferrable process.
eshell-foreground-commandThe currently-running foreground command, if any.
eshell-in-pipeline-pInternal Eshell variable, non-nil inside a pipeline.
eshell-last-async-procsThe currently-running foreground command, if any.
eshell-last-command-resultThe result of the last command. Not related to success.
eshell-last-command-statusThe exit code from the last command. 0 if successful.
eshell-lisp-form-nil-is-failureIf non-nil, Lisp forms like (COMMAND ARGS) treat a nil result as failure.
eshell-lisp-regexpA regexp which, if matched at beginning of an argument, means Lisp.
eshell-named-command-hookA set of functions called before a named command is invoked.
eshell-post-command-hookA hook run after each interactive command is invoked.
eshell-post-rewrite-command-functionFunction run after command rewriting is finished.
eshell-post-rewrite-command-hookA hook run after command rewriting is finished.
eshell-pre-command-hookA hook run before each interactive command is invoked.
eshell-pre-rewrite-command-hookA hook run before command rewriting begins.
eshell-prefer-lisp-functionsIf non-nil, prefer Lisp functions to external commands.
eshell-prepare-command-hookA set of functions called to prepare a named command.
eshell-rewrite-command-hookA set of functions used to rewrite the command argument.
eshell-subcommand-bindingsA list of ‘let’ bindings for subcommand environments.

Defined functions (78)

eshell--find-plain-lisp-command(COMMAND)
eshell--find-subcommands(HAYSTACK)
eshell--invoke-command-directly-p(COMMAND)
eshell-add-command(FORM &optional BACKGROUND)
eshell-apply(FUNC ARGS)
eshell-apply*(PRINTER ERRPRINT FUNC ARGS)
eshell-applyn(FUNC ARGS)
eshell-as-subcommand(COMMAND)
eshell-cmd-initialize()
eshell-command-success(COMMAND)
eshell-command-to-value(COMMAND)
eshell-commands(OBJECT &optional SILENT)
eshell-commands-for-process(PROCESS)
eshell-complete-lisp-symbols()
eshell-copy-handles(&rest BODY)
eshell-debug-show-parsed-args(TERMS)
eshell-deferrable(ARG1)
eshell-do-command(OBJECT)
eshell-do-command-to-value(OBJECT)
eshell-do-eval(FORM &optional SYNCHRONOUS-P)
eshell-do-pipelines(PIPELINE &optional NOTFIRST)
eshell-do-pipelines-synchronously(PIPELINE)
eshell-do-subjob(OBJECT)
eshell-eval(FORM)
eshell-eval*(PRINTER ERRPRINT FORM)
eshell-eval-argument(ARGUMENT)
eshell-eval-command(COMMAND &optional INPUT)
eshell-evaln(FORM)
eshell-exec-lisp(PRINTER ERRPRINT FUNC-OR-FORM ARGS FORM-P)
eshell-execute-pipeline(PIPELINE)
eshell-exit-success-p()
eshell-find-alias-function(NAME)
eshell-for-iterate(&rest ARGS)
eshell-funcall(FUNC &rest ARGS)
eshell-funcall*(PRINTER ERRPRINT FUNC &rest ARGS)
eshell-funcalln(FUNC &rest ARGS)
eshell-head-process()
eshell-interactive-process()
eshell-interactive-process-p()
eshell-invoke-directly(COMMAND)
eshell-invoke-directly-p(COMMAND)
eshell-invokify-arg(ARG &optional SHARE-OUTPUT SILENT)
eshell-lisp-command(OBJECT &optional ARGS)
eshell-lisp-command*(OBJECT &optional ARGS)
eshell-manipulate(FORM TAG &rest BODY)
eshell-named-command(COMMAND &optional ARGS)
eshell-named-command*(COMMAND &optional ARGS)
eshell-no-command-conversion(TERMS)
eshell-parse-command(COMMAND &optional ARGS TOPLEVEL)
eshell-parse-lisp-argument()
eshell-parse-pipeline(TERMS)
eshell-parse-subcommand-argument()
eshell-plain-command(COMMAND ARGS)
eshell-plain-command--which(COMMAND)
eshell-process-identity(ARGUMENT)
eshell-protect(OBJECT)
eshell-remove-command(COMMAND)
eshell-resume-command(PROC STATUS)
eshell-resume-eval(COMMAND)
eshell-rewrite-for-command(TERMS)
eshell-rewrite-if-command(TERMS)
eshell-rewrite-initial-subcommand(TERMS)
eshell-rewrite-named-command(TERMS)
eshell-rewrite-sexp-command(TERMS)
eshell-rewrite-while-command(TERMS)
eshell-separate-commands(TERMS SEPARATOR &optional REVERSED LAST-TERMS-SYM)
eshell-set-exit-info(STATUS &optional RESULT)
eshell-silence-test-command(TERMS)
eshell-split-commands(TERMS SEPARATOR &optional REVERSED RETURN-SEPS)
eshell-structure-basic-command(FUNC NAMES KEYWORD TEST &rest BODY)
eshell-subcommand-arg-values(TERMS)
eshell-tail-process()
eshell-term-as-value(TERM)
eshell-trap-errors(OBJECT)
eshell-with-copied-handles(&rest BODY)
eshell-with-handles(HANDLE-ARGS &rest BODY)
eshell/funcall(FUNC &rest ARGS)
eshell/which(COMMAND &rest NAMES)

Defined faces (0)