Quoted¶

In single-quoted strings, all characters represent themselves, except single quotes, which need to be doubled. For instance, '*\' evaluates to *\, and 'it''s' evaluates to it's.

In double-quoted strings, the backslash \ introduces a escape sequence. For instance, "\n" evaluates to a newline; "\\" evaluates to a backslash; invalid escape sequences like "\*" result in a syntax error.

TODO: Document the full list of supported escape sequences.

Unlike most other shells, double-quoted strings do not support interpolation. For instance, "$USER" simply evaluates to the string $USER. To get a similar effect, simply concatenate strings: instead of "my name is $name", write "my name is "$name. Under the hood this is a compound expression.

Barewords¶

•

ASCII letters (a-z and A-Z) and numbers (0-9);

•

The symbols -_:%+,./@!;

•

Non-ASCII codepoints that are printable, as defined by unicode.IsPrint (https://godoc.org/unicode#IsPrint) in Go's standard library.

The following are bareword characters depending on their position:

•

The tilde ~, unless it appears at the beginning of a compound expression, in which case it is subject to tilde expansion;

•

The equal sign =, unless it is used for terminating map keys or option keys, or denoting assignments or temporary assignments.

Unlike traditional shells, an unquoted backslash \ does not escape metacharacters; use quoted strings instead. For instance, to echo a star, write echo "*" or echo '*', not echo \*. Unquote backslashes are now only used in line continuations; their use elsewhere is reserved will cause a syntax error.

Notes¶

Elvish does not have a separate number type. For instance, in the command + 1 2, both 1 and 2 are strings, and it is the command + that knows to treat its arguments as numbers. This design is driven by syntax -- because barewords are always treated as strings, and digits are barewords, we cannot treat words like 1 as number literals. At some point the language may get a dedicated number type (or several number types), but they will likely need to be constructed explicitly, e.g. (number 1).

List¶

~> put [lorem ipsum]
▶ [lorem ipsum]
~> put [lorem
        ipsum
        foo
        bar]
▶ [lorem ipsum foo bar]

    

Note that commas have no special meanings and are valid bareword characters, so don't use them to separate elements:

~> li = [a, b]
~> put $li
▶ [a, b]
~> put $li[0]
▶ a,

    

Map¶

~> put [&foo=bar &lorem=ipsum]
▶ [&foo=bar &lorem=ipsum]
~> put [&a=   10
        &b=   23
        &sum= (+ 10 23)]
▶ [&a=10 &b=23 &sum=33]

    

An empty map is written as [&].

Assignment¶

~> foo = bar

    

You can assign multiple values to multiple variables simultaneously, simply by writing several variable names (separated by inline whitespaces) on the left-hand side, and several values on the right-hand side:

~> x y = 3 4

    

Referencing¶

~> foo = bar
~> x y = 3 4
~> put $foo
▶ bar
~> put $x
▶ 3

    

Variables must be assigned before use. Attempting to use an unassigned variable causes a compilation error:

~> echo $x
Compilation error: variable $x not found
[tty], line 1: echo $x
~> { echo $x }
Compilation error: variable $x not found
[tty], line 1: { echo $x }

    

Explosion and Rest Variable¶

~> li = [lorem ipsum foo bar]
~> put $li
▶ [lorem ipsum foo bar]
~> put $@li
▶ lorem
▶ ipsum
▶ foo
▶ bar

    

(This notation is restricted to exploding variables. To explode arbitrary values, use the builtin explode (/ref/builtin.html#explode) command.)

When assigning variables, if you prefix the name of the last variable with @, it gets assigned a list containing all remaining values. That variable is called a rest variable. Example:

~> a b @rest = 1 2 3 4 5 6 7
~> put $a $b $rest
▶ 1
▶ 2
▶ [3 4 5 6 7]

    

Schematically this is a reverse operation to variable explosion, which is why they share the @ sign.

Temporary Assignment¶

In the following example, $x and $y are temporarily assigned 100 and 200:

~> x y = 1 2
~> x=100 y=200 + $x $y
▶ 300
~> echo $x $y
1 2

    

In contrary to normal assignments, there should be no whitespaces around the equal sign =. To have multiple variables in the left-hand side, use braces:

~> x y = 1 2
~> fn f { put 100 200 }
~> {x,y}=(f) + $x $y
▶ 300

    

If you use a previously undefined variable in a temporary assignment, its value will become the empty string after the command finishes. This behavior will likely change; don't rely on it.

Since ordinary assignments are also a kind of command, they can also be prepended with temporary assignments:

~> x=1
~> x=100 y = (+ 133 $x)
~> put $x $y
▶ 1
▶ 233

    

Temporary assignments must all appear before the command. As soon as something that is not a temporary assignments is parsed, Elvish no longer parses temporary assignments. For instance, in x=1 echo x=1, the second x=1 is not a temporary assignment, but a bareword.

Note: Elvish's behavior differs from bash (or zsh) in one important place. In bash, temporary assignments to variables do not affect their direct appearance in the command:

bash-4.4$ x=1
bash-4.4$ x=100 echo $x
1

    

Scoping rule¶

When you use a variable, Elvish looks for it in the current lexical scope, then its parent lexical scope and so forth, until the outermost scope:

~> x = 12
~> { echo $x } # $x is in the global scope
12
~> { y = bar; { echo $y } } # $y is in the outer scope
bar

    

If a variable is not in any of the lexical scopes, Elvish tries to resolve it in the builtin: namespace, and if that also fails, cause an error:

~> echo $pid # builtin
36613
~> echo $nonexistent
Compilation error: variable $nonexistent not found
  [interactive], line 1:
    echo $nonexistent

    

Note that Elvish resolves all variables in a code chunk before starting to execute any of it; that is why the error message above says compilation error. This can be more clearly observed in the following example:

~> echo pre-error; echo $nonexistent
Compilation error: variable $nonexistent not found
[tty], line 1: echo pre-error; echo $nonexistent

    

When you assign a variable, Elvish does a similar searching. If the variable cannot be found, it will be created in the current scope:

~> x = 12
~> { x = 13 } # assigns to x in the global scope
~> echo $x
13
~> { z = foo } # creates z in the inner scope
~> echo $z
Compilation error: variable $z not found
[tty], line 1: echo $z

    

One implication of this behavior is that Elvish will not shadow your variable in outer scopes.

There is a local: namespace that always refers to the current scope, and by using it it is possible to force Elvish to shadow variables:

~> x = 12
~> { local:x = 13; echo $x } # force shadowing
13
~> echo $x
12

    

After force shadowing, you can still access the variable in the outer scope using the up: namespace, which always skips the innermost scope:

~> x = 12
~> { local:x = 14; echo $x $up:x }
14 12

    

The local: and up: namespaces can also be used on unshadowed variables, although they are not useful in those cases:

~> foo = a
~> { echo $up:foo } # $up:foo is the same as $foo
a
~> { bar = b; echo $local:bar } # $local:bar is the same as $bar
b

    

It is not possible to refer to a specific outer scope.

You cannot create new variables in the builtin: namespace, although existing variables in it can be assigned new values.

Signature¶

~> f = [a b]{ put $b $a }
~> $f lorem ipsum
▶ ipsum
▶ lorem

    

There should be no space between ] and {; otherwise Elvish will parse the signature as a list, followed by a lambda without signature:

~> put [a]{ nop }
▶ <closure 0xc420153d80>
~> put [a] { nop }
▶ [a]
▶ <closure 0xc42004a480>

    

Like in the left hand of assignments, if you prefix the last argument with @, it becomes a rest argument, and its value is a list containing all the remaining arguments:

~> f = [a @rest]{ put $a $rest }
~> $f lorem
▶ lorem
▶ []
~> $f lorem ipsum dolar sit
▶ lorem
▶ [ipsum dolar sit]

    

You can also declare options in the signature. The syntax is &name=default (like a map pair), where default is the default value for the option:

~> f = [&opt=default]{ echo "Value of $opt is "$opt }
~> $f
Value of $opt is default
~> $f &opt=foobar
Value of $opt is foobar

    

Options must have default values: Options should be optional.

If you call a function with too few arguments, too many arguments or unknown options, an exception is thrown:

~> [a]{ echo $a } foo bar
Exception: need 1 arguments, got 2
[tty], line 1: [a]{ echo $a } foo bar
~> [a b]{ echo $a $b } foo
Exception: need 2 arguments, got 1
[tty], line 1: [a b]{ echo $a $b } foo
~> [a b @rest]{ echo $a $b $rest } foo
Exception: need 2 or more arguments, got 1
[tty], line 1: [a b @rest]{ echo $a $b $rest } foo
~> [&k=v]{ echo $k } &k2=v2
Exception: unknown option k2
[tty], line 1: [&k=v]{ echo $k } &k2=v2

    

Closure Semantics¶

In the following example, the make-adder function outputs two functions, both referring to a local variable $n. Closure semantics means that:

1.

Both functions can continue to refer to the $n variable after make-adder has returned.

2.

Multiple calls to the make-adder function generates distinct instances of the $n variables.

~> fn make-adder {
     n = 0
     put { put $n } { n = (+ $n 1) }
   }
~> getter adder = (make-adder)
~> $getter # $getter outputs $n
▶ 0
~> $adder # $adder increments $n
~> $getter # $getter and $setter refer to the same $n
▶ 1
~> getter2 adder2 = (make-adder)
~> $getter2 # $getter2 and $getter refer to different $n
▶ 0
~> $getter
▶ 1

    

Variables that get "captured" in closures are called upvalues; this is why the pseudo-namespace for variables in outer scopes is called up:. When capturing upvalues, Elvish only captures the variables that are used. In the following example, $m is not an upvalue of $g because it is not used:

~> fn f { m = 2; n = 3; put { put $n } }
~> g = (f)

    

This effect is not currently observable, but will become so when namespaces become introspectable (https://github.com/elves/elvish/issues/492).

List Indexing¶

•

A non-negative integer, an offset counting from the beginning of the list. For example, $li[0] is the first element of $li.

•

A negative integer, an offset counting from the back of the list. For instance, $li[-1] is the last element $li.

•

A slice $a:$b, where both $a and $b are integers. The result is sublist of $li[$a] up to, but not including, $li[$b]. For instance, $li[4:7] equals [$li[4] $li[5] $li[6]], while $li[1:-1] contains all elements from $li except the first and last one.

•

Not yet implemented: The string @. The result is all the values in the list. Note that this is not the same as :: if $li has 10 elements, $li[@] evaluates to 10 values (all the elements in the list), while $li[:] evaluates to just one value (a copy of the list).

Examples:

~> li = [lorem ipsum foo bar]
~> put $li[0]
▶ lorem
~> put $li[-1]
▶ bar
~> put $li[0:2]
▶ [lorem ipsum]

    

(Negative indicies and slicing are borrowed from Python.)

String indexing¶

Strings should always be UTF-8, and they can indexed by byte indicies at which codepoints start, and indexing results in the codepoint that starts there. This is best explained with examples:

•

In the string elv, every codepoint is encoded with only one byte, so 0, 1, 2 are all valid indices:

•

In the string 世界, each codepoint is encoded with three bytes. The first codepoint occupies byte 0 through 2, and the second occupies byte 3 through 5. Hence valid indicies are 0 and 3:

Strings can also be indexed by slices.

(This idea of indexing codepoints by their byte positions is borrowed from Julia.)

Map indexing¶

~> map = [&a=lorem &b=ipsum &a:b=haha]
~> echo $map[a]
lorem
~> echo $map[a:b]
haha

    

Multiple Indices¶

~> put elv[0 2 0:2]
▶ e
▶ v
▶ el
~> put [lorem ipsum foo bar][0 2 0:2]
▶ lorem
▶ foo
▶ [lorem ipsum]
~> put [&a=lorem &b=ipsum &a:b=haha][a a:b]
▶ lorem
▶ haha

    

Modifiers¶

Global modifiers apply to the whole pattern and can be placed after any wildcard:

•

nomatch-ok tells Elvish not to throw an error when there is no match for the pattern. For instance, in the example directory put bad* will be an error, but put bad*[nomatch-ok] does exactly nothing.

•

but:xxx (where xxx is any filename) excludes the filename from the final result.

Although global modifiers affect the entire wildcard pattern, you can add it after any wildcard, and the effect is the same. For example, put */*[nomatch-ok].cpp and put *[nomatch-ok]/*.cpp do the same thing.

On the other hand, you must add it after a wildcard, instead of after the entire pattern: put */*.cpp[nomatch-ok] unfortunately does not do the correct thing. (This will probably be fixed.)

Local modifiers only apply to the wildcard it immediately follows:

•

match-hidden tells the wildcard to match . at the beginning of filenames, e.g. *[match-hidden].conf matches .x.conf and ax.conf.

•

Character matchers restrict the characters to match:

Braced Lists¶

~> put {a,b}-{1,2}
▶ a-1
▶ a-2
▶ b-1
▶ b-2

    

Elements in braced lists can also be separated with whitespaces, or a combination of comma and whitespaces (the latter not recommended):

~> put {a b , c,d}
▶ a
▶ b
▶ c
▶ d

    

(In future, the syntax might be made more strict.)

Braced list is merely a syntax for grouping multiple values. It is not a data structure.

Head¶

~> ls -l # the string ls is the head
(output omitted)
~> (put [@a]{ ls $@a }) -l
(same output)

    

The head must evaluate to one value. For instance, the following does not work:

~> (put [@a]{ ls $@a } -l)
Exception: head of command must be a single value; got 2 values
[tty], line 1: (put [@a]{ ls $@a } -l)

    

The definition of barewords is relaxed for the head to include <, >, * and ^. These are all names of numeric builtins:

~> < 3 5 # less-than
▶ $true
~> > 3 5 # greater-than
▶ $false
~> * 3 5 # multiplication
▶ 15
~> ^ 3 5 # power
▶ 243

    

Arguments and Options¶

~> echo &sep=, a b c # seq=, is an option; a b c are arguments
a,b,c

    

Redirections¶

The most common form of redirections opens a file and associates it with an FD. The form consists of an optional destination FD (like 2), a redirection operator (like >) and a filename (like error.log):

•

The destination fd determines which FD to modify. If absent, it is determined from the redirection operator. If present, there must be no space between the fd and the redirection operator. (Otherwise Elvish parses it as an argument.)

•

The redirection operator determines the mode to open the file, and the destination fd if it is not explicitly specified.

•

The filename names the file to open.

Possible redirection operators and their default FDs are:

•

< for reading. The default FD is 0 (stdin).

•

> for writing. The default FD is 1 (stdout).

•

>> for appending. The default FD is 1 (stdout).

•

<> for reading and writing. The default FD is 1 (stdout).

Examples:

~> echo haha > log
~> cat log
haha
~> cat < log
haha
~> ls --bad-arg 2> error
Exception: ls exited with 2
Traceback:
  [interactive], line 1:
    ls --bad-arg 2> error
~> cat error
/bin/ls: unrecognized option '--bad-arg'
Try '/bin/ls --help' for more information.

    

Redirections can also be used for closing or duplicating FDs. Instead of writing a filename, use &n (where n is a number) for duplicating, or &- for closing. In this case, the redirection operator only determines the default destination FD (and is totally irrevelant if a destination FD is specified). Examples:

~> ls >&- # close stdout
/bin/ls: write error: Bad file descriptor
Exception: ls exited with 2
Traceback:
  [interactive], line 1:
    ls >&-

    

If you have multiple related redirections, they are applied in the order they appear. For instance:

~> fn f { echo out; echo err >&2 } # echoes "out" on stdout, "err" on stderr
~> f >log 2>&1 # use file "log" for stdout, then use (changed) stdout for stderr
~> cat log
out
err

    

Ordering¶

echo something > file
> file echo something # mistaken for the comparison builtin ">" in Elvish

    

Deleting variable or element: del¶

Example of deleting variable:

~> x = 2
~> echo $x
2
~> del x
~> echo $x
Compilation error: variable $x not found
[tty], line 1: echo $x

    

Example of deleting element:

~> m = [&k=v &k2=v2]
~> del m[k2]
~> put $m
▶ [&k=v]
~> l = [[&k=v &k2=v2]]
~> del l[0][k2]
~> put $l
▶ [[&k=v]]

    

Logics: and and or¶

The or special command is the same except that it stops when a booleanly true value is obtained. When given no arguments, it outpus $false.

Condition: if¶

Syntax:

if <condition> {
    <body>
} elif <condition> {
    <body>
} else {
    <else-body>
}

    

The if special command goes through the conditions one by one: as soon as one evaluates to a booleanly true value, its corresponding body is executed. If none of conditions are booleanly true and an else body is supplied, it is executed.

The condition part is an expression, not a command like in other shells.

Tip: a combination of if and ?() gives you a semantics close to other shells:

if ?(test -d .git) {
    # do something
}

    

However, for Elvish's builtin predicates that output values instead of throw exceptions, the output capture construct () should be used.

TODO: add more examples.

Conditional Loop: while¶

while <condition> {
    <body>
} else {
    <else-body>
}

    

Execute the body as long as the condition evaluates to a booleanly true value.

The else body, if present, is executed if the body has never been executed (i.e. the condition evaluates to a booleanly false value in the very beginning).

Iterative Loop: for¶

for <var> <container> {
    <body>
} else {
    <body>
}

    

Iterate the container (e.g. a list). In each iteration, assign the variable to an element of the container and execute the body.

The else body, if present, is executed if the body has never been executed (i.e. the iteration value has no elements).

Exception Control: try¶

Syntax:

try {
    <try-block>
} except except-varname {
    <except-block>
} else {
    <else-block>
} finally {
    <finally-block>
}

    

Only try and try-block are required. This control structure behaves as follows:

1.

The try-block is always executed first.

2.

If except is present and an exception occurs in try-block, it is caught and stored in except-varname, and except-block is then executed. Example:

3.

If no exception occurs and else is present, else-block is executed. Example:

4.

If finally-block is present, it is executed. Examples:

5.

If the exception was not caught (i.e. except is not present), it is rethrown.

Exceptions thrown in blocks other than try-block are not caught. If an exception was thrown and either except-block or finally-block throws another exception, the original exception is lost. Examples:

~> try { fail bad } except e { fail worse }
Exception: worse
Traceback:
  [tty], line 1:
    try { fail bad } except e { fail worse }
~> try { fail bad } except e { fail worse } finally { fail worst }
Exception: worst
Traceback:
  [tty], line 1:
    try { fail bad } except e { fail worse } finally { fail worst }

    

Function Definition: fn¶

fn <name> <lambda>

    

Define a function with a given name. The function behaves in the same way to the lambda used to define it, except that it "captures" return. In other words, return will fall through lambdas not defined with fn, and continues until it exits a function defined with fn:

~> fn f {
     { echo a; return }
     echo b # will not execute
   }
~> f
a
~> {
     f
     echo c # executed, because f "captures" the return
   }
a
c

    

TODO: Find a better way to describe this. Hopefully the example is illustrative enough, though.

IO Semantics¶

Command redirections are applied before the connection happens. For instance, the following writes foo to a.txt instead of the output:

~> echo foo > a.txt | cat
~> cat a.txt
foo

    

Execution Flow¶

If one or more command in a pipeline throws an exception, the other commands will continue to execute as normal. After all commands finish execution, an exception is thrown, the value of which depends on the number of commands that have thrown an exception:

•

If only one command has thrown an exception, that exception is rethrown.

•

If more than one commands have thrown exceptions, a "composite exception", containing information all exceptions involved, is thrown.

Background Pipeline¶

When a background pipeline finishes, a message is printed to the terminal if the shell is interactive.

Syntax¶

e:echo $E:PATH

    

uses the echo command from the e namespace and the PATH variable from the E namespace.

Names of namespaces can contain colons themselves. For instance, in $x:y:z the namespace is x:y. More precisely, when parsing command names and variable names, everything up to the last colon is considered to be the namespace.

A convention used in articles is when referring to a namespace is to add a trailing colon: for instance, edit: means "the namespace edit". This is remniscent to the syntax but is not syntactically valid.

Special Namespaces¶

•

local: and up: refer to lexical scopes, and have been documented above.

•

e: refers to externals. For instance, e:ls refers to the external command ls.

•

E: refers to environment variables. For instance, $E:USER is the environment variable USER.

•

builtin: refers to builtin functions and variables.

Pre-Imported Modules¶

•

edit: for accessing the Elvish editor. This module is available in interactive mode.

•

re: for regular expression facilities. This module is always available. See reference (/ref/re.html).

•

daemon: for manipulating the daemon. This module is always available.

User-Defined Modules¶

~> cat ~/.elvish/lib/a.elv
echo "mod a loading"
fn f {
  echo "f from mod a"
}

    

To import the module, use use:

~> use a
mod a loading
~> a:f
f from mod a

    

The argument to use is called the usespec and will be explained in more details below. In the simplest case, it is simply the module name.

Modules are evaluated in a seprate scope. That means that functions and variables defined in the module does not pollute the default namespace, and vice versa. For instance, if you define ls as a wrapper function in rc.elv:

fn ls [@a]{
    e:ls --color=auto $@a
}

    

That definition is not visible in module files: ls will still refer to the external command ls, unless you shadow it in the very same module.

Modules in Nested Directories¶

For instance, if you have the following content in x/y/z.elv (relative to ~/.elvish/lib, of course):

fn f {
    echo 'In a deeply nested module'
}

    

It is possible to import the module as z, y:z, or x:y:z:

~> use x/y/z # imports as "z"
~> z:f
In a deeply nested module
~> use x/y:z # imports as "y:z"
~> y:z:f
In a deeply nested module
~> use x:y:z # imports as "x:y:z"
~> x:y:z:f
In a deeply nested module

    

To be precise:

•

The path of the module to import is derived by replacing all : with / and adding .elv. In the above example, all of x/y/z, x/y:z and x:y:z have the same path x/y/z.elv and refer to the same module

•

The part after the last / becomes the module name.

Lexical Scoping of Imports¶

{
    use some-mod
    some-mod:some-func
}
some-mod:some-func # not valid

    

Re-Importing¶

echo importing

    

The following code only prints one importing:

{ use a:b }
use a:b # only brings mod into the lexical scope

    

As does the following:

use a/b
use a:b