---

3.1 Dollars Expansion

Eshell has different $ expansion syntax from other shells. There are some similarities, but don’t let these lull you into a false sense of familiarity.

$var

Expands to the value bound to var. This is the main way to use variables in command invocations.

$"var"

$'var'

Expands to the value bound to var. This is useful to disambiguate the variable name when concatenating it with another value, such as ‘$"var"-suffix’.

$(lisp)

Expands to the result of evaluating the S-expression (lisp). On its own, this is identical to just (lisp), but with the $, it can be used inside double quotes or within a longer string, such as ‘/some/path/$(lisp).txt’.

${command}

Returns the output of command, which can be any valid Eshell command invocation, and may even contain expansions. Similar to $(lisp), this is identical to {command} when on its own, but the $ allows it to be used inside double quotes or as part of a string.

Normally, the output is split line-by-line, returning a list (or the first element if there’s only one line of output); if eshell-convert-numeric-arguments is non-nil and every line of output looks like a number, convert each line to a number. However, when this expansion is surrounded by double quotes, it returns the output as a single string instead.

$<command>

As with ‘${command}’, evaluates the Eshell command invocation command, but writes the output to a temporary file and returns the file name.

$expr[i...]

Expands to the ith element of the result of expr, an expression in one of the above forms listed here. If multiple indices are supplied, this will return a list containing the elements for each index. The exact behavior depends on the type of expr’s value:

a sequence

Expands to the element at the (zero-based) index i of the sequence (see Sequences Arrays Vectors in The Emacs Lisp Reference Manual).

a string

Split the string at whitespace, and then expand to the ith element of the resulting sequence.

an alist

If i is a non-numeric value, expand to the value associated with the key "i" in the alist. For example, if var is ‘(("dog" . "fido") ("cat" . "felix"))’, then ‘$var[dog]’ expands to "fido". Otherwise, this behaves as with sequences; e.g., ‘$var[0]’ expands to ("dog" . "fido"). See Association Lists in The Emacs Lisp Reference Manual.

anything else

Signals an error.

Multiple sets of indices can also be specified. For example, if var is ‘((1 2) (3 4))’, then ‘$var[0][1]’ will expand to 2, i.e. the second element of the first list member (all indices are zero-based).

$expr[regexp i...]

As above (when expr expands to a string), but use regexp to split the string. regexp can be any form other than a number. For example, ‘$var[: 0]’ will return the first element of a colon-delimited string.

$#expr

Expands to the length of the result of expr, an expression in one of the above forms. For example, ‘$#var’ returns the length of the variable var and ‘$#var[0]’ returns the length of the first element of var. Again, signals an error if the result of expr is not a string or a sequence.