4.1 Dollars Expansion

Like in many other shells, you can use $ expansions to insert various values into your Eshell invocations. While Eshell’s $ expansion syntax has some similarities to the syntax from other shells, there are also many differences. Don’t let these similarities lull you into a false sense of familiarity.

When using command form (see Invocation), Eshell will ignore any leading nil values, so if foo is nil, ‘$foo echo hello’ is equivalent to ‘echo hello’.

$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). If i is negative, i counts from the end, so -1 refers to the last element of the sequence.

If i is a range like start..end, this expands to a subsequence from the indices start to end, where end is excluded⁸. start and/or end can also be omitted, which is equivalent to the start and/or end of the entire list. For example, ‘$expr[-2..]’ expands to the last two values of expr.

a string

Split the string at whitespace, and then expand to the ith element of the resulting sequence. As above, i can be a range like start..end.

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

This is the length operator. It 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.

$@expr

This is the splice operator. It “splices” the elements of expr (an expression of one of the above forms) into the resulting list of arguments, much like the ‘,@’ marker in Emacs Lisp (see Backquote in The Emacs Lisp Reference Manual). The elements of expr become arguments at the same level as the other arguments around it. For example, if numbers is the list (1 2 3), then:

~ $ echo 0 $numbers
(0
 (1 2 3))

~ $ echo 0 $@numbers
(0 1 2 3)