.\"t
.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "elvish-language" "7" "Dec 07, 2021" "Elvish 0.17.0~rc4" "Miscellaneous Information Manual"
.hy
.SH Introduction
.PP
This document describes the Elvish programming language.
It is both a specification and an advanced tutorial.
The parts of this document marked with either \f[B]notes\f[R] or called
out as \f[B]examples\f[R] are non-normative, and only serve to help you
understand the more formal descriptions.
.PP
Examples in this document might use constructs that have not yet been
introduced, so some familiarity with the language is assumed.
If you are new to Elvish, start with the learning materials.
.SH Source code encoding
.PP
Elvish source code must be Unicode text encoded in UTF-8.
.PP
In this document, \f[B]character\f[R] is a synonym of Unicode
codepoint (https://en.wikipedia.org/wiki/Code_point) or its UTF-8
encoding.
.SH Lexical elements
.SS Whitespace
.PP
In this document, an \f[B]inline whitespace\f[R] is any of the
following:
.IP \[bu] 2
A space (U+0020);
.IP \[bu] 2
A tab (U+0009);
.IP \[bu] 2
A comment: starting with \f[C]#\f[R] and ending before (but not
including) the next carriage return, newline or end of file;
.IP \[bu] 2
A line continuation: a \f[C]\[ha]\f[R] followed by a newline
(\f[C]\[dq]\[rs]n\[dq]\f[R]), or a carriage return and newline
(\f[C]\[dq]\[rs]r\[rs]n\[dq]\f[R]).
.PP
A \f[B]whitespace\f[R] is any of the following:
.IP \[bu] 2
An inline whitespace;
.IP \[bu] 2
A carriage return (U+000D);
.IP \[bu] 2
A newline (U+000A).
.SS Metacharacters
.PP
The following \f[B]metacharacters\f[R] serve to introduce or delimit
syntax constructs:
.PP
.TS
tab(@);
l l.
T{
Metacharacter
T}@T{
Use
T}
_
T{
\f[C]$\f[R]
T}@T{
Referencing variables
T}
T{
\f[C]*\f[R] and \f[C]?\f[R]
T}@T{
Forming wildcard
T}
T{
\f[C]|\f[R]
T}@T{
Separating forms in a pipeline
T}
T{
\f[C]&\f[R]
T}@T{
Marking background pipelines; introducing key-value pairs
T}
T{
\f[C];\f[R]
T}@T{
Separating pipelines
T}
T{
\f[C]<\f[R] and \f[C]>\f[R]
T}@T{
Introducing IO redirections
T}
T{
\f[C](\f[R] and \f[C])\f[R]
T}@T{
Enclosing output captures
T}
T{
\f[C][\f[R] and \f[C]]\f[R]
T}@T{
Enclosing list literals, map literals or function signature
T}
T{
\f[C]{\f[R] and \f[C]}\f[R]
T}@T{
Enclosing lambda literals or brace expressions
T}
.TE
.PP
The following characters are parsed as metacharacters under certain
conditions:
.IP \[bu] 2
\f[C]\[ti]\f[R] is a metacharacter if it appears at the beginning of a
compound expression, in which case it is subject to tilde expansion;
.IP \[bu] 2
\f[C]=\f[R] is a metacharacter when used for terminating map keys or
option keys, or denoting legacy assignment form or temporary
assignments.
.SS Single-quoted string
.PP
A single-quoted string consists of zero or more characters enclosed in
single quotes (\f[C]\[aq]\f[R]).
All enclosed characters represent themselves, except the single quote.
.PP
Two consecutive single quotes are handled as a special case: they
represent one single quote, instead of terminating a single-quoted
string and starting another.
.PP
\f[B]Examples\f[R]: \f[C]\[aq]*\[rs]\[aq]\f[R] evaluates to
\f[C]*\[rs]\f[R], and \f[C]\[aq]it\[aq]\[aq]s\[aq]\f[R] evaluates to
\f[C]it\[aq]s\f[R].
.SS Double-quoted string
.PP
A double-quoted string consists of zero or more characters enclosed in
double quotes (\f[C]\[dq]\f[R]).
All enclosed characters represent themselves, except backslashes
(\f[C]\[rs]\f[R]), which introduces \f[B]escape sequences\f[R].
Double quotes are not allowed inside double-quoted strings, except after
backslashes.
.PP
The following escape sequences are supported:
.IP \[bu] 2
\f[C]\[rs]cX\f[R], where \f[I]X\f[R] is a character with codepoint
between 0x40 and 0x5F, represents the codepoint that is 0x40 lower than
\f[I]X\f[R].
For example, \f[C]\[rs]cI\f[R] is the tab character: 0x49 (\f[C]I\f[R])
- 0x40 = 0x09 (tab).
There is one special case: A question-mark is converted to del; i.e.,
\f[C]\[rs]c?\f[R] or \f[C]\[rs]\[ha]?\f[R] is equivalent to
\f[C]\[rs]x7F\f[R].
.IP \[bu] 2
\f[C]\[rs]\[ha]X\f[R] is the same as \f[C]\[rs]cX\f[R].
.IP \[bu] 2
\f[C]\[rs][0..7][0..7][0..7]\f[R] is a byte written as an octal value.
There must be three octal digits following the backslash.
For example, \f[C]\[rs]000\f[R] is the nul character, and
\f[C]\[rs]101\f[R] is the same as \f[C]A\f[R], but \f[C]\[rs]0\f[R] is
an invalid escape sequence (too few digits).
.IP \[bu] 2
\f[C]\[rs]x..\f[R] is a Unicode code point represented by two
hexadecimal digits.
.IP \[bu] 2
\f[C]\[rs]u....\f[R] is a Unicode code point represented by four
hexadecimal digits.
.IP \[bu] 2
\f[C]\[rs]U......\f[R] is a Unicode code point represented by eight
hexadecimal digits.
.IP \[bu] 2
The following single character escape sequences:
.RS 2
.IP \[bu] 2
\f[C]\[rs]a\f[R] is the \[lq]bell\[rq] character, equivalent to
\f[C]\[rs]007\f[R] or \f[C]\[rs]x07\f[R].
.IP \[bu] 2
\f[C]\[rs]b\f[R] is the \[lq]backspace\[rq] character, equivalent to
\f[C]\[rs]010\f[R] or \f[C]\[rs]x08\f[R].
.IP \[bu] 2
\f[C]\[rs]f\f[R] is the \[lq]form feed\[rq] character, equivalent to
\f[C]\[rs]014\f[R] or \f[C]\[rs]x0c\f[R].
.IP \[bu] 2
\f[C]\[rs]n\f[R] is the \[lq]new line\[rq] character, equivalent to
\f[C]\[rs]012\f[R] or \f[C]\[rs]x0a\f[R].
.IP \[bu] 2
\f[C]\[rs]r\f[R] is the \[lq]carriage return\[rq] character, equivalent
to \f[C]\[rs]015\f[R] or \f[C]\[rs]x0d\f[R].
.IP \[bu] 2
\f[C]\[rs]t\f[R] is the \[lq]tab\[rq] character, equivalent to
\f[C]\[rs]011\f[R] or \f[C]\[rs]x09\f[R].
.IP \[bu] 2
\f[C]\[rs]v\f[R] is the \[lq]vertical tab\[rq] character, equivalent to
\f[C]\[rs]013\f[R] or \f[C]\[rs]x0b\f[R].
.IP \[bu] 2
\f[C]\[rs]\[rs]\f[R] is the \[lq]backslash\[rq] character, equivalent to
\f[C]\[rs]134\f[R] or \f[C]\[rs]x5c\f[R].
.IP \[bu] 2
\f[C]\[rs]\[dq]\f[R] is the \[lq]double-quote\[rq] character, equivalent
to \f[C]\[rs]042\f[R] or \f[C]\[rs]x22\f[R].
.RE
.PP
An unsupported escape sequence results in a parse error.
.PP
\f[B]Note\f[R]: Unlike most other shells, double-quoted strings in
Elvish do not support interpolation.
For instance, \f[C]\[dq]$name\[dq]\f[R] simply evaluates to a string
containing \f[C]$name\f[R].
To get a similar effect, simply concatenate strings: instead of
\f[C]\[dq]my name is $name\[dq]\f[R], write
\f[C]\[dq]my name is \[dq]$name\f[R].
Under the hood this is a compounding operation.
.SS Bareword
.PP
A string can be written without quoting \[en] a \f[B]bareword\f[R], if
it only includes the characters from the following set:
.IP \[bu] 2
ASCII letters (a-z and A-Z) and numbers (0-9);
.IP \[bu] 2
The symbols \f[C]!%+,-./:\[at]\[rs]_\f[R];
.IP \[bu] 2
Non-ASCII codepoints that are printable, as defined by
unicode.IsPrint (https://godoc.org/unicode#IsPrint) in Go\[cq]s standard
library.
.PP
\f[B]Examples\f[R]: \f[C]a.txt\f[R], \f[C]long-bareword\f[R],
\f[C]elf\[at]elv.sh\f[R], \f[C]/usr/local/bin\f[R],
\f[C]\[u4F60]\[u597D]\[u4E16]\[u754C]\f[R].
.PP
Moreover, \f[C]\[ti]\f[R] and \f[C]=\f[R] are allowed to appear without
quoting when they are not parsed as metacharacters.
.PP
\f[B]Note\f[R]: since the backslash (\f[C]\[rs]\f[R]) is a valid
bareword character in Elvish, it cannot be used to escape metacharacter.
Use quotes instead: for example, to echo a star, write
\f[C]echo \[dq]*\[dq]\f[R] or \f[C]echo \[aq]*\[aq]\f[R], not
\f[C]echo \[rs]*\f[R].
The last command just writes out \f[C]\[rs]*\f[R].
.SH Value types
.SS String
.PP
A string is a (possibly empty) sequence of bytes.
.PP
Single-quoted string literals, double-quoted string literals and
barewords all evaluate to string values.
Unless otherwise noted, different syntaxes of string literals are
equivalent in the code.
For instance, \f[C]xyz\f[R], \f[C]\[aq]xyz\[aq]\f[R] and
\f[C]\[dq]xyz\[dq]\f[R] are different syntaxes for the same string with
content \f[C]xyz\f[R].
.PP
Strings that contain UTF-8 encoded text can be indexed with a \f[B]byte
index\f[R] where a codepoint starts, which results in the codepoint that
starts there.
The index can be given as either a typed number, or a string that parses
to a number.
Examples:
.IP \[bu] 2
In the string \f[C]elv\f[R], every codepoint is encoded with only one
byte, so 0, 1, 2 are all valid indices:
.RS 2
.IP
.nf
\f[C]
\[ti]> put elv[0]
\[u25B6] e
\[ti]> put elv[1]
\[u25B6] l
\[ti]> put elv[2]
\[u25B6] v
\f[R]
.fi
.RE
.IP \[bu] 2
In the string \f[C]\[u4E16]\[u754C]\f[R], 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 indices are 0 and 3:
.RS 2
.IP
.nf
\f[C]
\[ti]> put \[u4E16]\[u754C][0]
\[u25B6] \[u4E16]
\[ti]> put \[u4E16]\[u754C][3]
\[u25B6] \[u754C]
\f[R]
.fi
.RE
.PP
Such strings may also be indexed with a slice (see documentation of list
for slice syntax).
The range determined by the slice is also interpreted as byte indices,
and the range must begin and end at codepoint boundaries.
.PP
The behavior of indexing a string that does not contain valid
UTF-8-encoded Unicode text is unspecified.
.PP
\f[B]Note\f[R]: String indexing will likely change.
.SS Number
.PP
Elvish supports several types of numbers.
There is no literal syntax, but they can be constructed by passing their
\f[B]string representation\f[R] to the \f[C]num\f[R] builtin command:
.IP \[bu] 2
\f[B]Integers\f[R] are written in decimal (e.g.
\f[C]10\f[R]), hexadecimal (e.g.
\f[C]0xA\f[R]), octal (e.g.
\f[C]0o12\f[R]) or binary (e.g.
\f[C]0b1010\f[R]).
.RS 2
.PP
\f[B]NOTE\f[R]: Integers with leading zeros are now parsed as octal
(e.g.
\f[C]010\f[R] is the same as \f[C]0o10\f[R], or \f[C]8\f[R]), but this
is subject to change (#1372 (https://b.elv.sh/1371)).
.RE
.IP \[bu] 2
\f[B]Rationals\f[R] are written as two exact integers joined by
\f[C]/\f[R], e.g.
\f[C]1/2\f[R] or \f[C]0x10/100\f[R] (16/100).
.IP \[bu] 2
\f[B]Floating-point numbers\f[R] are written with a decimal point (e.g.
\f[C]10.0\f[R]) or using scientific notation (e.g.
\f[C]1e1\f[R] or \f[C]1.0e1\f[R]).
There are also three additional special floating-point values:
\f[C]+Inf\f[R], \f[C]-Inf\f[R] and \f[C]NaN\f[R].
.PP
Digits may be separated by underscores, which are ignored; this permits
separating the digits into groups to improve readability.
For example, \f[C]1000000\f[R] and \f[C]1_000_000\f[R] are equivalent,
so are \f[C]1.234_56e3\f[R] and \f[C]1.23456e3\f[R], or \f[C]1_2_3\f[R]
and \f[C]123\f[R].
.PP
The string representation is case-insensitive.
.SS Strings and numbers
.PP
Strings and numbers are distinct types; for example, \f[C]2\f[R] and
\f[C](num 2)\f[R] are distinct values.
.PP
However, by convention, all language constructs that expect numbers
(e.g.
list indices) also accept strings that can be converted to numbers.
This means that most of the time, you can just use the string
representation of numbers, instead of explicitly constructing number
values.
Builtin numeric commands follow the same convention.
.PP
When the word \f[B]number\f[R] appears unqualified in other sections of
this document, it means either an explicitly number-typed value
(\f[B]typed number\f[R]), or its string representation.
.PP
When a typed number is converted to a string (e.g.
with \f[C]to-string\f[R]), the result is guaranteed to convert back to
the original number.
In other words, \f[C]eq $x (num (to-string $x))\f[R] always outputs
\f[C]$true\f[R] if \f[C]$x\f[R] is a typed number.
.SS Exactness
.PP
Integers and rationals are \f[B]exact\f[R] numbers; their precision is
only limited by the available memory, and many (but not all) operations
on them are guaranteed to produce mathematically correct results.
.PP
Floating-point numbers are IEEE
754 (https://en.wikipedia.org/wiki/IEEE_754) double-precision.
Since operations on floating-point numbers in general are not guaranteed
to be precise, they are always considered \f[B]inexact\f[R].
.PP
This distinction is important for some builtin commands; see
exactness-preserving commands.
.SS List
.PP
A list is a value containing a sequence of values.
Values in a list are called its \f[B]elements\f[R].
Each element has an index, starting from zero.
.PP
List literals are surrounded by square brackets \f[C][ ]\f[R], with
elements separated by whitespace.
Examples:
.IP
.nf
\f[C]
\[ti]> put [lorem ipsum]
\[u25B6] [lorem ipsum]
\[ti]> put [lorem
        ipsum
        foo
        bar]
\[u25B6] [lorem ipsum foo bar]
\f[R]
.fi
.PP
\f[B]Note\f[R]: In Elvish, commas have no special meanings and are valid
bareword characters, so don\[cq]t use them to separate elements:
.IP
.nf
\f[C]
\[ti]> li = [a, b]
\[ti]> put $li
\[u25B6] [a, b]
\[ti]> put $li[0]
\[u25B6] a,
\f[R]
.fi
.PP
A list can be indexed with the index of an element to obtain the
element, which can take one of two forms:
.IP \[bu] 2
A non-negative integer, an offset counting from the beginning of the
list.
For example, \f[C]$li[0]\f[R] is the first element of \f[C]$li\f[R].
.IP \[bu] 2
A negative integer, an offset counting from the back of the list.
For instance, \f[C]$li[-1]\f[R] is the last element \f[C]$li\f[R].
.PP
In both cases, the index can be given either as a typed number or a
number-like string.
.PP
A list can also be indexed with a \f[B]slice\f[R] to obtain a sublist,
which can take one of two forms:
.IP \[bu] 2
A slice \f[C]$a..$b\f[R], where both \f[C]$a\f[R] and \f[C]$b\f[R] are
integers.
The result is sublist of \f[C]$li[$a]\f[R] up to, but not including,
\f[C]$li[$b]\f[R].
For instance, \f[C]$li[4..7]\f[R] equals
\f[C][$li[4] $li[5] $li[6]]\f[R], while \f[C]$li[1..-1]\f[R] contains
all elements from \f[C]$li\f[R] except the first and last one.
.RS 2
.PP
Both integers may be omitted; \f[C]$a\f[R] defaults to 0 while
\f[C]$b\f[R] defaults to the length of the list.
For instance, \f[C]$li[..2]\f[R] is equivalent to \f[C]$li[0..2]\f[R],
\f[C]$li[2..]\f[R] is equivalent to \f[C]$li[2..(count $li)]\f[R], and
\f[C]$li[..]\f[R] makes a copy of \f[C]$li\f[R].
The last form is rarely useful, as lists are immutable.
.PP
Note that the slice needs to be a \f[B]single\f[R] string, so there
cannot be any spaces within the slice.
For instance, \f[C]$li[2..10]\f[R] cannot be written as
\f[C]$li[2.. 10]\f[R]; the latter contains two indices and is equivalent
to \f[C]$li[2..] $li[10]\f[R] (see Indexing).
.RE
.IP \[bu] 2
A slice \f[C]$a..=$b\f[R], which is similar to \f[C]$a..$b\f[R], but
includes \f[C]$li[$b]\f[R].
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> li = [lorem ipsum foo bar]
\[ti]> put $li[0]
\[u25B6] lorem
\[ti]> put $li[-1]
\[u25B6] bar
\[ti]> put $li[0..2]
\[u25B6] [lorem ipsum]
\f[R]
.fi
.SS Map
.PP
A map is a value containing unordered key-value pairs.
.PP
Map literals are surrounded by square brackets; a key/value pair is
written \f[C]&key=value\f[R] (reminiscent to HTTP query parameters), and
pairs are separated by whitespaces.
Whitespaces are allowed after \f[C]=\f[R], but not before \f[C]=\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> put [&foo=bar &lorem=ipsum]
\[u25B6] [&foo=bar &lorem=ipsum]
\[ti]> put [&a=   10
        &b=   23
        &sum= (+ 10 23)]
\[u25B6] [&a=10 &b=23 &sum=33]
\f[R]
.fi
.PP
The literal of an empty map is \f[C][&]\f[R].
.PP
Specifying a key without \f[C]=\f[R] or a value following it is
equivalent to specifying \f[C]$true\f[R] as the value.
Specifying a key with \f[C]=\f[R] but no value following it is
equivalent to specifying the empty string as the value.
Example:
.IP
.nf
\f[C]
\[ti]> echo [&a &b=]
[&a=$true &b=\[aq]\[aq]]
\f[R]
.fi
.PP
A map can be indexed by any of its keys.
Unlike strings and lists, there is no support for slices, and
\f[C]..\f[R] and \f[C]..=\f[R] have no special meanings.
Examples:
.IP
.nf
\f[C]
\[ti]> map = [&a=lorem &b=ipsum &a..b=haha]
\[ti]> echo $map[a]
lorem
\[ti]> echo $map[a..b]
haha
\f[R]
.fi
.PP
You can test if a key is present using \f[C]has-key\f[R] and enumerate
the keys using the \f[C]keys\f[R] builtins.
.PP
\f[B]Note\f[R]: Since \f[C]&\f[R] is a metacharacter, key-value pairs do
not have to follow whitespaces; \f[C][&a=lorem&b=ipsum]\f[R] is
equivalent to \f[C][&a=lorem &b=ipsum]\f[R], just less readable.
This might change in future.
.SS Pseudo-map
.PP
A pseudo-map is not a single concrete data type.
It refers to concrete types that behave like maps with some
restrictions.
.PP
A pseudo-map has a fixed set of keys whose values can be accessed by
indexing like you would for a regular map.
Similarly, you can use commands like \f[C]keys\f[R] and
\f[C]has-key\f[R] on such objects.
.PP
Unlike a normal map, it is currently not possible to create a modified
version of an existing pseudo-map: it is not possible to create a
pseudo-map with new keys, without existing keys, or with a different
value for a given key.
.PP
The pseudo-map mechanism is often used for introspection.
For example, exceptions, user-defined functions, and
\f[C]$buildinfo\f[R] are pseudo-maps.
.SS Nil
.PP
The value \f[C]$nil\f[R] serves as the initial value of variables that
are declared but not assigned.
.SS Boolean
.PP
There are two boolean values, \f[C]$true\f[R] and \f[C]$false\f[R].
.PP
When converting non-boolean values to the boolean type, \f[C]$nil\f[R]
and exceptions convert to \f[C]$false\f[R]; such values and
\f[C]$false\f[R] itself are \f[B]booleanly false\f[R].
All the other non-boolean values convert to \f[C]$true\f[R]; such values
and \f[C]$true\f[R] itself are \f[B]booleanly true\f[R].
.SS Exception
.PP
An exception carries information about errors during the execution of
code.
.PP
There is no literal syntax for exceptions.
See the discussion of exception and flow commands for more information
about this data type.
.PP
An exception is a pseudo-map with a \f[C]reason\f[R] field, which is in
turn a pseudo-map.
The reason pseudo-map has has a \f[C]type\f[R] field identifying how the
exception was raised, and further fields depending on the type:
.IP \[bu] 2
If the \f[C]type\f[R] field is \f[C]fail\f[R], the exception was raised
by the fail command.
.RS 2
.PP
In this case, the \f[C]content\f[R] field contains the argument to
\f[C]fail\f[R].
.RE
.IP \[bu] 2
If the \f[C]type\f[R] field is \f[C]flow\f[R], the exception was raised
by one of the flow commands.
.RS 2
.PP
In this case, the \f[C]name\f[R] field contains the name of the flow
command.
.RE
.IP \[bu] 2
If the \f[C]type\f[R] field is \f[C]pipeline\f[R], the exception was a
result of multiple commands in the same pipeline raising exceptions.
.RS 2
.PP
In this case, the \f[C]exceptions\f[R] field contains the exceptions
from the individual commands.
.RE
.IP \[bu] 2
If the \f[C]type\f[R] field starts with \f[C]external-cmd/\f[R], the
exception was caused by one of several conditions of an external
command.
In this case, the following fields are available:
.RS 2
.IP \[bu] 2
The \f[C]cmd-name\f[R] field contains the name of the command.
.IP \[bu] 2
The \f[C]pid\f[R] field contains the PID of the command.
.RE
.IP \[bu] 2
If the \f[C]type\f[R] field is \f[C]external-cmd/exited\f[R], the
external command exited with a non-zero status code.
In this case, the \f[C]exit-status\f[R] field contains the exit status.
.IP \[bu] 2
If the \f[C]type\f[R] field is \f[C]external-cmd/signaled\f[R], the
external command was killed by a signal.
In this case, the following extra fields are available:
.RS 2
.IP \[bu] 2
The \f[C]signal-name\f[R] field contains the name of the signal.
.IP \[bu] 2
The \f[C]signal-number\f[R] field contains the numerical value of the
signal, as a string.
.IP \[bu] 2
The \f[C]core-dumped\f[R] field is a boolean reflecting whether a core
dump was generated.
.RE
.IP \[bu] 2
If the \f[C]type\f[R] field is \f[C]external-cmd/stopped\f[R], the
external command was stopped.
In this case, the following extra fields are available:
.RS 2
.IP \[bu] 2
The \f[C]signal-name\f[R] field contains the name of the signal.
.IP \[bu] 2
The \f[C]signal-number\f[R] field contains the numerical value of the
signal, as a string.
.IP \[bu] 2
The \f[C]trap-cause\f[R] field contains the number indicating the trap
cause.
.RE
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> put ?(fail foo)[reason]
\[u25B6] [&content=foo &type=fail]
\[ti]> put ?(return)[reason]
\[u25B6] [&name=return &type=flow]
\[ti]> put ?(false)[reason]
\[u25B6] [&cmd-name=false &exit-status=1 &pid=953421 &type=external-cmd/exited]
\f[R]
.fi
.SS File
.PP
There is no literal syntax for the file type.
This type is returned by commands such as file:open and path:temp-file.
It can be used as the target of a redirection rather than a filename.
.PP
A file object is a pseudo-map with fields \f[C]fd\f[R] (an int) and
\f[C]name\f[R] (a string).
If the file is closed the fd will be -1.
.SS Function
.PP
A function encapsulates a piece of code that can be executed in an
ordinary command, and takes its arguments and options.
Functions are first-class values; they can be kept in variables, used as
arguments, output on the value channel and embedded in other data
structures.
Elvish comes with a set of \f[B]builtin functions\f[R], and Elvish code
can also create \f[B]user-defined functions\f[R].
.PP
\f[B]Note\f[R]: Unlike most programming languages, functions in Elvish
do not have return values.
Instead, they can output values, which can be captured later.
.PP
A \f[B]function literal\f[R], or alternatively a \f[B]lambda\f[R],
evaluates to a user-defined function.
The literal syntax consists of an optional \f[B]signature list\f[R],
followed by a code chunk that defines the body of the function.
.PP
Here is an example without a signature:
.IP
.nf
\f[C]
\[ti]> f = { echo \[dq]Inside a lambda\[dq] }
\[ti]> put $f
\[u25B6] <closure 0x18a1a340>
\f[R]
.fi
.PP
One or more whitespace characters after \f[C]{\f[R] is required: Elvish
relies on the presence of whitespace to disambiguate function literals
and braced lists.
.PP
\f[B]Note\f[R]: It is good style to put some whitespace before the
closing \f[C]}\f[R] for symmetry, but this is not required by the
syntax.
.PP
Functions defined without a signature list do not accept any arguments
or options.
To do so, write a signature list.
Here is an example:
.IP
.nf
\f[C]
\[ti]> f = [a b]{ put $b $a }
\[ti]> $f lorem ipsum
\[u25B6] ipsum
\[u25B6] lorem
\f[R]
.fi
.PP
There must be no space between \f[C]]\f[R] and \f[C]{\f[R]; otherwise
Elvish will parse the signature as a list, followed by a lambda without
signature:
.IP
.nf
\f[C]
\[ti]> put [a]{ nop }
\[u25B6] <closure 0xc420153d80>
\[ti]> put [a] { nop }
\[u25B6] [a]
\[u25B6] <closure 0xc42004a480>
\f[R]
.fi
.PP
Like in the left hand of assignments, if you prefix one of the arguments
with \f[C]\[at]\f[R], it becomes a \f[B]rest argument\f[R], and its
value is a list containing all the remaining arguments:
.IP
.nf
\f[C]
\[ti]> f = [a \[at]rest]{ put $a $rest }
\[ti]> $f lorem
\[u25B6] lorem
\[u25B6] []
\[ti]> $f lorem ipsum dolar sit
\[u25B6] lorem
\[u25B6] [ipsum dolar sit]
\[ti]> f = [a \[at]rest b]{ put $a $rest $b }
\[ti]> $f lorem ipsum dolar sit
\[u25B6] lorem
\[u25B6] [ipsum dolar]
\[u25B6] sit
\f[R]
.fi
.PP
You can also declare options in the signature.
The syntax is \f[C]&name=default\f[R] (like a map pair), where
\f[C]default\f[R] is the default value for the option; the value of the
option will be kept in a variable called \f[C]name\f[R]:
.IP
.nf
\f[C]
\[ti]> f = [&opt=default]{ echo \[dq]Value of $opt is \[dq]$opt }
\[ti]> $f
Value of $opt is default
\[ti]> $f &opt=foobar
Value of $opt is foobar
\f[R]
.fi
.PP
Options must have default values: Options should be \f[B]option\f[R]al.
.PP
If you call a function with too few arguments, too many arguments or
unknown options, an exception is thrown:
.IP
.nf
\f[C]
\[ti]> [a]{ echo $a } foo bar
Exception: need 1 arguments, got 2
[tty], line 1: [a]{ echo $a } foo bar
\[ti]> [a b]{ echo $a $b } foo
Exception: need 2 arguments, got 1
[tty], line 1: [a b]{ echo $a $b } foo
\[ti]> [a b \[at]rest]{ echo $a $b $rest } foo
Exception: need 2 or more arguments, got 1
[tty], line 1: [a b \[at]rest]{ echo $a $b $rest } foo
\[ti]> [&k=v]{ echo $k } &k2=v2
Exception: unknown option k2
[tty], line 1: [&k=v]{ echo $k } &k2=v2
\f[R]
.fi
.PP
A user-defined function is a pseudo-map.
If \f[C]$f\f[R] is a user-defined function, it has the following fields:
.IP \[bu] 2
\f[C]$f[arg-names]\f[R] is a list containing the names of the arguments.
.IP \[bu] 2
\f[C]$f[rest-arg]\f[R] is the index of the rest argument.
If there is no rest argument, it is \f[C]-1\f[R].
.IP \[bu] 2
\f[C]$f[opt-names]\f[R] is a list containing the names of the options.
.IP \[bu] 2
\f[C]$f[opt-defaults]\f[R] is a list containing the default values of
the options, in the same order as \f[C]$f[opt-names]\f[R].
.IP \[bu] 2
\f[C]$f[def]\f[R] is a string containing the definition of the function,
including the signature and the body.
.IP \[bu] 2
\f[C]$f[body]\f[R] is a string containing the body of the function,
without the enclosing brackets.
.IP \[bu] 2
\f[C]$f[src]\f[R] is a map-like data structure containing information
about the source code that the function is defined in.
It contains the same value that the src function would output if called
from the function.
.SH Variable
.PP
A variable is a named storage location for holding a value.
The following characters can be used in variable names (a subset of
bareword characters) without quoting:
.PP
A variable exist after it is declared (either explicitly using
\f[C]var\f[R] or implicitly using the legacy assignment form), and its
value may be mutated by further assignments.
It can be used as an expression or part of an expression.
.PP
\f[B]Note\f[R]: In most other shells, variables can map directly to
environmental variables: \f[C]$PATH\f[R] is the same as the
\f[C]PATH\f[R] environment variable.
This is not the case in Elvish.
Instead, environment variables are put in a dedicated \f[C]E:\f[R]
namespace; the environment variable \f[C]PATH\f[R] is known as
\f[C]$E:PATH\f[R].
The \f[C]$PATH\f[R] variable, on the other hand, does not exist
initially, and if you have defined it, only lives in a certain lexical
scope within the Elvish interpreter.
.PP
You will notice that variables sometimes have a leading dollar
\f[C]$\f[R], and sometimes not.
The tradition is that they do when they are used for their values, and
do not otherwise (e.g.
in assignment).
This is consistent with most other shells.
.SS Variable suffix
.PP
There are two characters that have special meanings and extra type
constraints when used as the suffix of a variable name:
.IP \[bu] 2
If a variable name ends with \f[C]\[ti]\f[R], it can only take callable
values, which are functions and external commands.
Such variables are consulted when resolving ordinary commands.
The default value is the builtin \f[C]nop\f[R] command.
.IP \[bu] 2
If a variable name ends with \f[C]:\f[R], it can only take namespaces as
values.
They are used for accessing namespaced variables.
.SS Scoping rule
.PP
Elvish has lexical scoping.
A file or an interactive prompt starts with a top-level scope, and a
function literal introduce new lexical scopes.
.PP
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:
.IP
.nf
\f[C]
\[ti]> x = 12
\[ti]> { echo $x } # $x is in the global scope
12
\[ti]> { y = bar; { echo $y } } # $y is in the outer scope
bar
\f[R]
.fi
.PP
If a variable is not in any of the lexical scopes, Elvish tries to
resolve it in the \f[C]builtin:\f[R] namespace, and if that also fails,
fails with an error:
.IP
.nf
\f[C]
\[ti]> echo $pid # builtin
36613
\[ti]> echo $nonexistent
Compilation error: variable $nonexistent not found
  [interactive], line 1:
    echo $nonexistent
\f[R]
.fi
.PP
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
\f[I]compilation error\f[R].
This can be more clearly observed in the following example:
.IP
.nf
\f[C]
\[ti]> echo pre-error; echo $nonexistent
Compilation error: variable $nonexistent not found
[tty], line 1: echo pre-error; echo $nonexistent
\f[R]
.fi
.PP
When you assign a variable, Elvish does a similar searching.
If the variable cannot be found, instead of causing an error, it will be
created in the current scope:
.IP
.nf
\f[C]
\[ti]> x = 12
\[ti]> { x = 13 } # assigns to x in the global scope
\[ti]> echo $x
13
\[ti]> { z = foo } # creates z in the inner scope
\[ti]> echo $z
Compilation error: variable $z not found
[tty], line 1: echo $z
\f[R]
.fi
.PP
One implication of this behavior is that Elvish will not shadow your
variable in outer scopes.
.PP
There is a \f[C]local:\f[R] namespace that always refers to the current
scope, and by using it it is possible to force Elvish to shadow
variables:
.IP
.nf
\f[C]
\[ti]> x = 12
\[ti]> { local:x = 13; echo $x } # force shadowing
13
\[ti]> echo $x
12
\f[R]
.fi
.PP
After force shadowing, you can still access the variable in the outer
scope using the \f[C]up:\f[R] namespace, which always \f[B]skips\f[R]
the innermost scope:
.IP
.nf
\f[C]
\[ti]> x = 12
\[ti]> { local:x = 14; echo $x $up:x }
14 12
\f[R]
.fi
.PP
The \f[C]local:\f[R] and \f[C]up:\f[R] namespaces can also be used on
unshadowed variables, although they are not useful in those cases:
.IP
.nf
\f[C]
\[ti]> foo = a
\[ti]> { echo $up:foo } # $up:foo is the same as $foo
a
\[ti]> { bar = b; echo $local:bar } # $local:bar is the same as $bar
b
\f[R]
.fi
.PP
It is not possible to refer to a specific outer scope.
.PP
You cannot create new variables in the \f[C]builtin:\f[R] namespace,
although existing variables in it can be assigned new values.
.SS Closure semantics
.PP
When a function literal refers to a variable in an outer scope, the
function will keep that variable alive, even if that variable is the
local variable of an outer function that that function has returned.
This is called closure
semantics (https://en.wikipedia.org/wiki/Closure_(computer_programming)),
because the function literal \[lq]closes\[rq] over the environment it is
defined in.
.PP
In the following example, the \f[C]make-adder\f[R] function outputs two
functions, both referring to a local variable \f[C]$n\f[R].
Closure semantics means that:
.IP "1." 3
Both functions can continue to refer to the \f[C]$n\f[R] variable after
\f[C]make-adder\f[R] has returned.
.IP "2." 3
Multiple calls to the \f[C]make-adder\f[R] function generates distinct
instances of the \f[C]$n\f[R] variables.
.IP
.nf
\f[C]
\[ti]> fn make-adder {
     n = 0
     put { put $n } { n = (+ $n 1) }
   }
\[ti]> getter adder = (make-adder)
\[ti]> $getter # $getter outputs $n
\[u25B6] 0
\[ti]> $adder # $adder increments $n
\[ti]> $getter # $getter and $setter refer to the same $n
\[u25B6] 1
\[ti]> getter2 adder2 = (make-adder)
\[ti]> $getter2 # $getter2 and $getter refer to different $n
\[u25B6] 0
\[ti]> $getter
\[u25B6] 1
\f[R]
.fi
.PP
Variables that get \[lq]captured\[rq] in closures are called
\f[B]upvalues\f[R]; this is why the pseudo-namespace for variables in
outer scopes is called \f[C]up:\f[R].
When capturing upvalues, Elvish only captures the variables that are
used.
In the following example, \f[C]$m\f[R] is not an upvalue of \f[C]$g\f[R]
because it is not used:
.IP
.nf
\f[C]
\[ti]> fn f { m = 2; n = 3; put { put $n } }
\[ti]> g = (f)
\f[R]
.fi
.PP
This effect is not currently observable, but will become so when
namespaces become
introspectable (https://github.com/elves/elvish/issues/492).
.SH Expressions
.PP
Elvish has a few types of expressions.
Some of those are new compared to most other languages, but some are
very similar.
.PP
Unlike most other languages, expressions in Elvish may evaluate to any
number of values.
The concept of multiple values is distinct from a list of multiple
elements.
.SS Literal
.PP
Literals of strings, lists, maps and functions all evaluate to one value
of their corresponding types.
They are described in their respective sections.
.SS Variable use
.PP
A \f[B]variable use\f[R] expression is formed by a \f[C]$\f[R] followed
by the name of the variable.
Examples:
.IP
.nf
\f[C]
\[ti]> foo = bar
\[ti]> x y = 3 4
\[ti]> put $foo
\[u25B6] bar
\[ti]> put $x
\[u25B6] 3
\f[R]
.fi
.PP
If the variable name only contains the following characters (a subset of
bareword characters), the name can appear unquoted after \f[C]$\f[R] and
the variable use expression extends to the longest sequence of such
characters:
.IP \[bu] 2
ASCII letters (a-z and A-Z) and numbers (0-9);
.IP \[bu] 2
The symbols \f[C]-_:\[ti]\f[R].
The colon \f[C]:\f[R] is special; it is normally used for separating
namespaces or denoting namespace variables;
.IP \[bu] 2
Non-ASCII codepoints that are printable, as defined by
unicode.IsPrint (https://godoc.org/unicode#IsPrint) in Go\[cq]s standard
library.
.PP
Alternatively, \f[C]$\f[R] may be followed immediately by a
single-quoted
string (https://elv.sh/ref/language.html#single-quoted-string) or a
double-quoted
string (https://elv.sh/ref/language.html#double-quoted-string), in which
cases the value of the string specifies the name of the variable.
Examples:
.IP
.nf
\f[C]
\[ti]> \[dq]\[rs]n\[dq] = foo
\[ti]> put $\[dq]\[rs]n\[dq]
\[u25B6] foo
\[ti]> \[aq]!!!\[aq] = bar
\[ti]> put $\[aq]!!!\[aq]
\[u25B6] bar
\f[R]
.fi
.PP
Unlike other shells and other dynamic languages, local namespaces in
Elvish are statically checked.
This means that referencing a nonexistent variable results in a
compilation error, which is triggered before any code is actually
evaluated:
.IP
.nf
\f[C]
\[ti]> echo $x
Compilation error: variable $x not found
[tty], line 1: echo $x
\[ti]> f = { echo $x }
compilation error: variable $x not found
[tty 1], line 1: f = { echo $x }
\f[R]
.fi
.PP
If a variable contains a list value, you can add \f[C]\[at]\f[R] before
the variable name; this evaluates to all the elements within the list.
This is called \f[B]exploding\f[R] the variable:
.IP
.nf
\f[C]
\[ti]> li = [lorem ipsum foo bar]
\[ti]> put $li
\[u25B6] [lorem ipsum foo bar]
\[ti]> put $\[at]li
\[u25B6] lorem
\[u25B6] ipsum
\[u25B6] foo
\[u25B6] bar
\f[R]
.fi
.PP
\f[B]Note\f[R]: Since variable uses have higher precedence than
indexing, this does not work for exploding a list that is an element of
another list.
For doing that, and exploding the result of other expressions (such as
an output capture), use the builtin all command.)
.SS Output capture
.PP
An \f[B]output capture\f[R] expression is formed by putting parentheses
\f[C]()\f[R] around a code chunk.
It redirects the output of the chunk into an internal pipe, and
evaluates to all the values that have been output.
.IP
.nf
\f[C]
\[ti]> + 1 10 100
\[u25B6] 111
\[ti]> x = (+ 1 10 100)
\[ti]> put $x
\[u25B6] 111
\[ti]> put lorem ipsum
\[u25B6] lorem
\[u25B6] ipsum
\[ti]> x y = (put lorem ipsum)
\[ti]> put $x
\[u25B6] lorem
\[ti]> put $y
\[u25B6] ipsum
\f[R]
.fi
.PP
If the chunk outputs bytes, Elvish strips the last newline (if any), and
split them by newlines, and consider each line to be one string value:
.IP
.nf
\f[C]
\[ti]> put (echo \[dq]a\[rs]nb\[dq])
\[u25B6] a
\[u25B6] b
\f[R]
.fi
.PP
Trailing carriage returns are also stripped from each line, which
effectively makes \f[C]\[rs]r\[rs]n\f[R] also valid line separators:
.IP
.nf
\f[C]
\[ti]> put (echo \[dq]a\[rs]r\[rs]nb\[dq])
\[u25B6] a
\[u25B6] b
\f[R]
.fi
.PP
\f[B]Note 1\f[R].
Only the last newline is ever removed, so empty lines are preserved;
\f[C](echo \[dq]a\[rs]n\[dq])\f[R] evaluates to two values,
\f[C]\[dq]a\[dq]\f[R] and \f[C]\[dq]\[dq]\f[R].
.PP
\f[B]Note 2\f[R].
One consequence of this mechanism is that you can not distinguish
outputs that lack a trailing newline from outputs that have one;
\f[C](echo what)\f[R] evaluates to the same value as
\f[C](print what)\f[R].
If such a distinction is needed, use \f[C]slurp\f[R] to preserve the
original bytes output.
.PP
If the chunk outputs both values and bytes, the values of output capture
will contain both value outputs and lines.
However, the ordering between value output and byte output might not
agree with the order in which they happened:
.IP
.nf
\f[C]
\[ti]> put (put a; echo b) # value order need not be the same as output order
\[u25B6] b
\[u25B6] a
\f[R]
.fi
.PP
\f[B]Note\f[R]: If you want to capture the stdout and stderr byte
streams independent of each other, see the example in the run-parallel
documentation.
.SS Exception capture
.PP
An \f[B]exception capture\f[R] expression is formed by putting
\f[C]?()\f[R] around a code chunk.
It runs the chunk and evaluates to the exception it throws.
.IP
.nf
\f[C]
\[ti]> fail bad
Exception: bad
Traceback:
  [interactive], line 1:
    fail bad
\[ti]> put ?(fail bad)
\[u25B6] ?(fail bad)
\f[R]
.fi
.PP
If there was no error, it evaluates to the special value \f[C]$ok\f[R]:
.IP
.nf
\f[C]
\[ti]> nop
\[ti]> put ?(nop)
\[u25B6] $ok
\f[R]
.fi
.PP
Exceptions are booleanly false and \f[C]$ok\f[R] is booleanly true.
This is useful in \f[C]if\f[R] (introduced later):
.IP
.nf
\f[C]
if ?(test -d ./a) {
  # ./a is a directory
}
\f[R]
.fi
.PP
\f[B]Note\f[R]: Exception captures do not affect the output of the code
chunk.
You can combine output capture and exception capture:
.IP
.nf
\f[C]
output = (error = ?(commands-that-may-fail))
\f[R]
.fi
.SS Braced list
.PP
A \f[B]braced list\f[R] consists of multiple expressions separated by
whitespaces and surrounded by braces (\f[C]{}\f[R]).
There must be no space after the opening brace.
A braced list evaluates to whatever the expressions inside it evaluate
to.
Its most typical use is grouping multiple values in a compound
expression.
Example:
.IP
.nf
\f[C]
\[ti]> put {a b}-{1 2}
\[u25B6] a-1
\[u25B6] a-2
\[u25B6] b-1
\[u25B6] b-2
\f[R]
.fi
.PP
It can also be used to affect the order of evaluation.
Examples:
.IP
.nf
\f[C]
\[ti]> put *
\[u25B6] foo
\[u25B6] bar
\[ti]> put *o
\[u25B6] foo
\[ti]> put {*}o
\[u25B6] fooo
\[u25B6] baro
\f[R]
.fi
.PP
\f[B]Note\f[R]: When used to affect the order of evaluation, braced
lists are very similar to parentheses in C-like languages.
.PP
\f[B]Note\f[R]: A braced list is an expression.
It is a syntactical construct and not a separate data structure.
.PP
Elvish currently also supports using commas to separate items in a
braced list.
This will likely be removed in future, but it also means that literal
commas must be quoted right now.
.SS Indexing
.PP
An \f[B]indexing expression\f[R] is formed by appending one or more
indices inside a pair of brackets (\f[C][]\f[R]) after another
expression (the indexee).
Examples:
.IP
.nf
\f[C]
\[ti]> li = [foo bar]
\[ti]> put $li[0]
\[u25B6] foo
\[ti]> li = [[foo bar] quux]
\[ti]> put $li[0][0]
\[u25B6] foo
\[ti]> put [[foo bar]][0][0]
\[u25B6] foo
\f[R]
.fi
.PP
If the expression being indexed evaluates to multiple values, the
indexing operation is applied on each value.
Example:
.IP
.nf
\f[C]
\[ti]> put (put [foo bar] [lorem ipsum])[0]
\[u25B6] foo
\[u25B6] lorem
\[ti]> put {[foo bar] [lorem ipsum]}[0]
\[u25B6] foo
\[u25B6] lorem
\f[R]
.fi
.PP
If there are multiple index expressions, or the index expression
evaluates to multiple values, the indexee is indexed once for each of
the index value.
Examples:
.IP
.nf
\f[C]
\[ti]> put elv[0 2 0..2]
\[u25B6] e
\[u25B6] v
\[u25B6] el
\[ti]> put [lorem ipsum foo bar][0 2 0..2]
\[u25B6] lorem
\[u25B6] foo
\[u25B6] [lorem ipsum]
\[ti]> put [&a=lorem &b=ipsum &a..b=haha][a a..b]
\[u25B6] lorem
\[u25B6] haha
\f[R]
.fi
.PP
If both the indexee and index evaluate to multiple values, the results
generated from the first indexee appear first.
Example:
.IP
.nf
\f[C]
\[ti]> put {[foo bar] [lorem ipsum]}[0 1]
\[u25B6] foo
\[u25B6] bar
\[u25B6] lorem
\[u25B6] ipsum
\f[R]
.fi
.SS Compounding
.PP
A \f[B]compound expression\f[R] is formed by writing several expressions
together with no space in between.
A compound expression evaluates to a string concatenation of all the
constituent expressions.
Examples:
.IP
.nf
\f[C]
\[ti]> put \[aq]a\[aq]b\[dq]c\[dq] # compounding three string literals
\[u25B6] abc
\[ti]> v = value
\[ti]> put \[aq]$v is \[aq]$v # compounding one string literal with one string variable
\[u25B6] \[aq]$v is value\[aq]
\f[R]
.fi
.PP
When one or more of the constituent expressions evaluate to multiple
values, the result is all possible combinations:
.IP
.nf
\f[C]
\[ti]> li = [foo bar]
\[ti]> put {a b}-$li[0 1]
\[u25B6] a-foo
\[u25B6] a-bar
\[u25B6] b-foo
\[u25B6] b-bar
\f[R]
.fi
.PP
The order of the combinations is determined by first taking the first
value in the leftmost expression that generates multiple values, and
then taking the second value, and so on.
.SS Tilde expansion
.PP
An unquoted tilde at the beginning of a compound expression triggers
\f[B]tilde expansion\f[R].
The remainder of this expression must be a string.
The part from the beginning of the string up to the first \f[C]/\f[R]
(or the end of the word if the string does not contain \f[C]/\f[R]), is
taken as a user name; and they together evaluate to the home directory
of that user.
If the user name is empty, the current user is assumed.
.PP
In the following example, the home directory of the current user is
\f[C]/home/xiaq\f[R], while that of the root user is \f[C]/root\f[R]:
.IP
.nf
\f[C]
\[ti]> put \[ti]
\[u25B6] /home/xiaq
\[ti]> put \[ti]root
\[u25B6] /root
\[ti]> put \[ti]/xxx
\[u25B6] /home/xiaq/xxx
\[ti]> put \[ti]root/xxx
\[u25B6] /root/xxx
\f[R]
.fi
.PP
Note that tildes are not special when they appear elsewhere in a word:
.IP
.nf
\f[C]
\[ti]> put a\[ti]root
\[u25B6] a\[ti]root
\f[R]
.fi
.PP
If you need them to be, use a braced list:
.IP
.nf
\f[C]
\[ti]> put a{\[ti]root}
\[u25B6] a/root
\f[R]
.fi
.SS Wildcard expansion
.PP
\f[B]Wildcard patterns\f[R] are expressions that contain
\f[B]wildcards\f[R].
Wildcard patterns evaluate to all filenames they match.
.PP
In examples in this section, we will assume that the current directory
has the following structure:
.IP
.nf
\f[C]
\&.x.conf
a.cc
ax.conf
foo.cc
d/
|__ .x.conf
|__ ax.conf
|__ y.cc
\&.d2/
|__ .x.conf
|__ ax.conf
\f[R]
.fi
.PP
Elvish supports the following wildcards:
.IP \[bu] 2
\f[C]?\f[R] matches one arbitrary character except \f[C]/\f[R].
For example, \f[C]?.cc\f[R] matches \f[C]a.cc\f[R];
.IP \[bu] 2
\f[C]*\f[R] matches any number of arbitrary characters except
\f[C]/\f[R].
For example, \f[C]*.cc\f[R] matches \f[C]a.cc\f[R] and \f[C]foo.cc\f[R];
.IP \[bu] 2
\f[C]**\f[R] matches any number of arbitrary characters including
\f[C]/\f[R].
For example, \f[C]**.cc\f[R] matches \f[C]a.cc\f[R], \f[C]foo.cc\f[R]
and \f[C]b/y.cc\f[R].
.PP
The following behaviors are default, although they can be altered by
modifiers:
.IP \[bu] 2
When the entire wildcard pattern has no match, an error is thrown.
.IP \[bu] 2
None of the wildcards matches \f[C].\f[R] at the beginning of filenames.
For example:
.RS 2
.IP \[bu] 2
\f[C]?x.conf\f[R] does not match \f[C].x.conf\f[R];
.IP \[bu] 2
\f[C]d/*.conf\f[R] does not match \f[C]d/.x.conf\f[R];
.IP \[bu] 2
\f[C]**.conf\f[R] does not match \f[C]d/.x.conf\f[R].
.RE
.PP
Wildcards can be \f[B]modified\f[R] using the same syntax as indexing.
For instance, in \f[C]*[match-hidden]\f[R] the \f[C]*\f[R] wildcard is
modified with the \f[C]match-hidden\f[R] modifier.
Multiple matchers can be chained like \f[C]*[set:abc][range:0-9]\f[R].
In which case they are OR\[cq]ed together.
.PP
There are two kinds of modifiers:
.PP
\f[B]Global modifiers\f[R] apply to the whole pattern and can be placed
after any wildcard:
.IP \[bu] 2
\f[C]nomatch-ok\f[R] tells Elvish not to throw an error when there is no
match for the pattern.
For instance, in the example directory \f[C]put bad*\f[R] will be an
error, but \f[C]put bad*[nomatch-ok]\f[R] does exactly nothing.
.IP \[bu] 2
\f[C]but:xxx\f[R] (where \f[C]xxx\f[R] is any filename) excludes the
filename from the final result.
.IP \[bu] 2
\f[C]type:xxx\f[R] (where \f[C]xxx\f[R] is a recognized file type from
the list below).
Only one type modifier is allowed.
For example, to find the directories at any level below the current
working directory: \f[C]**[type:dir]\f[R].
.RS 2
.IP \[bu] 2
\f[C]dir\f[R] will match if the path is a directory.
.IP \[bu] 2
\f[C]regular\f[R] will match if the path is a regular file.
.RE
.PP
Although global modifiers affect the entire wildcard pattern, you can
add it after any wildcard, and the effect is the same.
For example, \f[C]put */*[nomatch-ok].cpp\f[R] and
\f[C]put *[nomatch-ok]/*.cpp\f[R] do the same thing.
On the other hand, you must add it after a wildcard, instead of after
the entire pattern: \f[C]put */*.cpp[nomatch-ok]\f[R] unfortunately does
not do the correct thing.
(This will probably be fixed.)
.PP
\f[B]Local modifiers\f[R] only apply to the wildcard it immediately
follows:
.IP \[bu] 2
\f[C]match-hidden\f[R] tells the wildcard to match \f[C].\f[R] at the
beginning of filenames, e.g.
\f[C]*[match-hidden].conf\f[R] matches \f[C].x.conf\f[R] and
\f[C]ax.conf\f[R].
.RS 2
.PP
Being a local modifier, it only applies to the wildcard it immediately
follows.
For instance, \f[C]*[match-hidden]/*.conf\f[R] matches
\f[C]d/ax.conf\f[R] and \f[C].d2/ax.conf\f[R], but not
\f[C]d/.x.conf\f[R] or \f[C].d2/.x.conf\f[R].
.RE
.IP \[bu] 2
Character matchers restrict the characters to match:
.RS 2
.IP \[bu] 2
Character sets, like \f[C]set:aeoiu\f[R];
.IP \[bu] 2
Character ranges like \f[C]range:a-z\f[R] (including \f[C]z\f[R]) or
\f[C]range:a\[ti]z\f[R] (excluding \f[C]z\f[R]);
.IP \[bu] 2
Character classes: \f[C]control\f[R], \f[C]digit\f[R],
\f[C]graphic\f[R], \f[C]letter\f[R], \f[C]lower\f[R], \f[C]mark\f[R],
\f[C]number\f[R], \f[C]print\f[R], \f[C]punct\f[R], \f[C]space\f[R],
\f[C]symbol\f[R], \f[C]title\f[R], and \f[C]upper\f[R].
See the Is* functions here (https://godoc.org/unicode) for their
definitions.
.RE
.PP
Note the following caveats:
.IP \[bu] 2
Local matchers chained together in separate modifiers are OR\[cq]ed.
For instance, \f[C]?[set:aeoiu][digit]\f[R] matches all files with the
chars \f[C]aeoiu\f[R] or containing a digit.
.IP \[bu] 2
Local matchers combined in the same modifier, such as
\f[C]?[set:aeoiu digit]\f[R], behave in a hard to explain manner.
Do not use this form as \f[B]the behavior is likely to change in the
future.\f[R]
.IP \[bu] 2
Dots at the beginning of filenames always require an explicit
\f[C]match-hidden\f[R], even if the matcher includes \f[C].\f[R].
For example, \f[C]?[set:.a]x.conf\f[R] does \f[B]not\f[R] match
\f[C].x.conf\f[R]; you have to \f[C]?[set:.a match-hidden]x.conf\f[R].
.IP \[bu] 2
Likewise, you always need to use \f[C]**\f[R] to match slashes, even if
the matcher includes \f[C]/\f[R].
For example \f[C]*[set:abc/]\f[R] is the same as \f[C]*[set:abc]\f[R].
.SS Order of evaluation
.PP
An expression can use a combination of indexing, tilde expansion,
wildcard and compounding.
The order of evaluation is as follows:
.IP "1." 3
Literals, variable uses, output captures and exception captures and
braced lists have the highest precedence and are evaluated first.
.IP "2." 3
Indexing has the next highest precedence and is then evaluated first.
.IP "3." 3
Expression compounding then happens.
Tildes and wildcards are kept unevaluated.
.IP "4." 3
If the expression starts with a tilde, tilde expansion happens.
If the tilde is followed by a wildcard, an exception is raised.
.IP "5." 3
If the expression contains any wildcard, wildcard expansion happens.
.PP
Here an example: in \f[C]\[ti]/$li[0 1]/*\f[R] (where \f[C]$li\f[R] is a
list \f[C][foo bar]\f[R]), the expression is evaluated as follows:
.IP "1." 3
The variable use \f[C]$li\f[R] evaluates to the list
\f[C][foo bar]\f[R].
.IP "2." 3
The indexing expression \f[C]$li[0]\f[R] evaluates to two strings
\f[C]foo\f[R] and \f[C]bar\f[R].
.IP "3." 3
Compounding the expression, the result is \f[C]\[ti]/foo/*\f[R] and
\f[C]\[ti]/bar/*\f[R].
.IP "4." 3
Tilde expansion happens; assuming that the user\[cq]s home directory is
\f[C]/home/elf\f[R], the values are now \f[C]/home/elf/foo/*\f[R] and
\f[C]/home/elf/bar/*\f[R].
.IP "5." 3
Wildcard expansion happens, evaluating the expression to all the
filenames within \f[C]/home/elf/foo\f[R] and \f[C]/home/elf/bar\f[R].
If any directory is empty or nonexistent, an exception is thrown.
.PP
To force a particular order of evaluation, group expressions using a
braced list.
.SH Command forms
.PP
A \f[B]command form\f[R] is either an ordinary command, a special
command or an legacy assignment form.
All of three different types have access to IO ports, which can be
modified via redirections.
.PP
When Elvish parses a command form, it applies the following process to
decide its type:
.IP \[bu] 2
If the command form contains an unquoted equal sign surrounded by inline
whitespaces, it is an ordinary assignment.
.IP \[bu] 2
If the first expression in the command form contains a single string
literal, and the string value matches one of the special commands, it is
a special command.
.IP \[bu] 2
Otherwise, it is an ordinary command.
.SS Ordinary command
.PP
An \f[B]ordinary command\f[R] form consists of a command head, and any
number of arguments and options.
.PP
The first expression in an ordinary command is the command
\f[B]head\f[R].
If the head is a single string literal, it is subject to \f[B]static
resolution\f[R]:
.IP \[bu] 2
If a variable with name \f[C]head\[ti]\f[R] (where \f[C]head\f[R] is the
value of the head) exists, the head will evaluate as if it is
\f[C]$head\[ti]\f[R]; i.e., a function invocation.
.IP \[bu] 2
If the head contains at least one slash, it is treated as an external
command with the value as its path relative to the current directory.
.IP \[bu] 2
Otherwise, the head is considered \[lq]unknown\[rq], and the behavior is
controlled by the \f[C]unknown-command\f[R] pragma:
.RS 2
.IP \[bu] 2
If the \f[C]unknown-command\f[R] pragma is set to \f[C]external\f[R]
(the default), the head is treated as the name of an external command,
to be searched in the \f[C]$E:PATH\f[R] during runtime.
.IP \[bu] 2
If the \f[C]unknown-command\f[R] pragma is set to \f[C]disallow\f[R],
such command heads trigger a compilation error.
.RE
.PP
If the head is not a single string literal, it is evaluated as a normal
expression.
The expression must evaluate to one value, and the value must be one of
the following:
.IP \[bu] 2
A callable value: a function or external command.
.IP \[bu] 2
A string containing at least one slash, in which case it is treated like
an external command with the string value as its path.
.PP
Examples of commands using static resolution:
.IP
.nf
\f[C]
\[ti]> put x # resolves to builtin function $put\[ti]
\[u25B6] x
\[ti]> f\[ti] = { put \[aq]this is f\[aq] }
\[ti]> f # resolves to user-defined function $f\[ti]
\[u25B6] \[aq]this is f\[aq]
\[ti]> whoami # resolves to external command whoami
elf
\f[R]
.fi
.PP
Examples of commands using a dynamic callable head:
.IP
.nf
\f[C]
\[ti]> $put\[ti] x
\[u25B6] x
\[ti]> (external whoami)
elf
\[ti]> { put \[aq]this is a lambda\[aq] }
\[u25B6] \[aq]this is a lambda\[aq]
\f[R]
.fi
.PP
\f[B]Note\f[R]: The last command resembles a code block in C-like
languages in syntax, but is quite different under the hood: it works by
defining a function on the fly and calling it immediately.
.PP
Examples of commands using a dynamic string head:
.IP
.nf
\f[C]
\[ti]> x = /bin/whoami
\[ti]> $x
elf
\[ti]> x = whoami
\[ti]> $x # dynamic strings can only used when containing slash
Exception: bad value: command must be callable or string containing slash, but is string
[tty 10], line 1: $x
\f[R]
.fi
.PP
The definition of barewords is relaxed when parsing the head, and
includes \f[C]<\f[R], \f[C]>\f[R], and \f[C]*\f[R].
These are all names of numeric builtins:
.IP
.nf
\f[C]
\[ti]> < 3 5 # less-than
\[u25B6] $true
\[ti]> > 3 5 # greater-than
\[u25B6] $false
\[ti]> * 3 5 # multiplication
\[u25B6] 15
\f[R]
.fi
.PP
\f[B]Arguments\f[R] and \f[B]options\f[R] can be supplied to commands.
Arguments are arbitrary words, while options have exactly the same
syntax as key-value pairs in map literals.
They are separated by inline whitespaces and may be intermixed:
.IP
.nf
\f[C]
\[ti]> echo &sep=, a b c # &seq=, is an option; a b c are arguments
a,b,c
\[ti]> echo a b &sep=, c # same, with the option mixed within arguments
a,b,c
\f[R]
.fi
.PP
\f[B]Note\f[R]: Since options have the same syntax as key-value pairs in
maps, \f[C]&key\f[R] is equivalent to \f[C]&key=$true\f[R]:
.IP
.nf
\f[C]
\[ti]> fn f [&opt=$false]{ put $opt }
\[ti]> f &opt
\[u25B6] $true
\f[R]
.fi
.PP
\f[B]Note\f[R]: Since \f[C]&\f[R] is a metacharacter, it can be used to
start an option immediately after the command name;
\f[C]echo&sep=, a b\f[R] is equivalent to \f[C]echo &sep=, a b\f[R],
just less readable.
This might change in future.
.SS Special command
.PP
A \f[B]special command\f[R] form has the same syntax with an ordinary
command, but how it is executed depends on the command head.
See special commands.
.SS Legacy assignment form
.PP
If any argument in a command form is an unquoted equal sign
(\f[C]=\f[R]), the command form is treated as an assignment form: the
arguments to the left of \f[C]=\f[R], including the head, are treated as
lvalues, and the arguments to the right of \f[C]=\f[R] are treated as
values to assign to those lvalues.
.PP
If any lvalue refers to a variable that doesn\[cq]t yet exist, it is
created first.
.PP
This is a legacy syntax that will be deprecated in future.
Use the \f[C]var\f[R] special command to declare variables, and the
\f[C]set\f[R] special command set the values of variables.
.SS Temporary assignment
.PP
You can prepend any command form with \f[B]temporary assignments\f[R],
which gives variables temporarily values during the execution of that
command.
.PP
In the following example, \f[C]$x\f[R] and \f[C]$y\f[R] are temporarily
assigned 100 and 200:
.IP
.nf
\f[C]
\[ti]> x y = 1 2
\[ti]> x=100 y=200 + $x $y
\[u25B6] 300
\[ti]> echo $x $y
1 2
\f[R]
.fi
.PP
In contrary to normal assignments, there should be no whitespaces around
the equal sign \f[C]=\f[R].
To have multiple variables in the left-hand side, use braces:
.IP
.nf
\f[C]
\[ti]> x y = 1 2
\[ti]> fn f { put 100 200 }
\[ti]> {x,y}=(f) + $x $y
\[u25B6] 300
\f[R]
.fi
.PP
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\[cq]t rely on it.
.PP
Since ordinary assignments are also command forms, they can also be
prepended with temporary assignments:
.IP
.nf
\f[C]
\[ti]> x=1
\[ti]> x=100 y = (+ 133 $x)
\[ti]> put $x $y
\[u25B6] 1
\[u25B6] 233
\f[R]
.fi
.PP
Temporary assignments must all appear at the beginning of the command
form.
As soon as something that is not a temporary assignments is parsed,
Elvish no longer parses temporary assignments.
For instance, in \f[C]x=1 echo x=1\f[R], the second \f[C]x=1\f[R] is not
a temporary assignment, but a bareword.
.PP
\f[B]Note\f[R]: Elvish\[cq]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:
.IP
.nf
\f[C]
bash-4.4$ x=1
bash-4.4$ x=100 echo $x
1
\f[R]
.fi
.PP
\f[B]Note\f[R]: Elvish currently supports using the syntax of temporary
assignments for ordinary assignments, when they are not followed by a
command form; for example, \f[C]a=x\f[R] behaves like an ordinary
assignment \f[C]a = x\f[R].
This will likely go away; don\[cq]t rely on it.
.SS IO ports
.PP
A command have access to a number of \f[B]IO ports\f[R].
Each IO port is identified by a number starting from 0, and combines a
traditional file object, which conveys bytes, and a \f[B]value
channel\f[R], which conveys values.
.PP
Elvish starts with 3 IO ports at the top level with special significance
for commands:
.IP \[bu] 2
Port 0, known as standard input or stdin, and is used as the default
input port by builtin commands.
.IP \[bu] 2
Port 1, known as standard output or stdout, and is used as the default
output port by builtin commands.
.IP \[bu] 2
Port 2, known as standard error or stderr, is currently not special for
builtin commands, but usually has special significance for external
commands.
.PP
Value channels are typically created by a pipeline, and used to pass
values between commands in the same pipeline.
At the top level, they are initialized with special values:
.IP \[bu] 2
The value channel for port 0 never produces any values when read.
.IP \[bu] 2
The value channels for port 1 and 2 are special channels that forward
the values written to them to their file counterparts.
Each value is put on a separate line, with a prefix controlled by
\f[C]$value-out-indicator\f[R].
The default prefix is \f[C]\[u25B6]\f[R] followed by a space.
.PP
When running an external command, the file object from each port is used
to create its file descriptor table.
Value channels only work inside the Elvish process, and are not
accessible to external commands.
.PP
IO ports can be modified with redirections or by pipelines.
.SS Redirection
.PP
A \f[B]redirection\f[R] modifies the IO ports a command operate with.
There are several variants.
.PP
A \f[B]file redirection\f[R] opens a file and associates it with an IO
port.
The syntax consists of an optional destination IO port (like
\f[C]2\f[R]), a redirection operator (like \f[C]>\f[R]) and a filename
(like \f[C]error.log\f[R]):
.IP \[bu] 2
The \f[B]destination IO port\f[R] determines which IO port to modify.
It can be given either as the number of the IO port, or one of
\f[C]stdin\f[R], \f[C]stdout\f[R] and \f[C]stderr\f[R], which are
equivalent to 0, 1 and 2 respectively.
.RS 2
.PP
The destination IO port can be omitted, in which case it is inferred
from the redirection operator.
.PP
When the destination IO port is given, it must precede the redirection
operator directly, without whitespaces in between; if there are
whitespaces, otherwise Elvish will parse it as an argument instead.
.RE
.IP \[bu] 2
The \f[B]redirection operator\f[R] determines the mode to open the file,
and the destination IO port if it is not explicitly specified.
.IP \[bu] 2
The \f[B]filename\f[R] names the file to open.
.PP
Possible redirection operators and their default FDs are:
.IP \[bu] 2
\f[C]<\f[R] for reading.
The default IO port is 0 (stdin).
.IP \[bu] 2
\f[C]>\f[R] for writing.
The default IO port is 1 (stdout).
.IP \[bu] 2
\f[C]>>\f[R] for appending.
The default IO port is 1 (stdout).
.IP \[bu] 2
\f[C]<>\f[R] for reading and writing.
The default IO port is 1 (stdout).
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> echo haha > log
\[ti]> cat log
haha
\[ti]> cat < log
haha
\[ti]> ls --bad-arg 2> error
Exception: ls exited with 2
Traceback:
  [interactive], line 1:
    ls --bad-arg 2> error
\[ti]> cat error
/bin/ls: unrecognized option \[aq]--bad-arg\[aq]
Try \[aq]/bin/ls --help\[aq] for more information.
\f[R]
.fi
.PP
IO ports modified by file redirections do not support value channels.
To be more exact:
.IP \[bu] 2
A file redirection using \f[C]<\f[R] sets the value channel to one that
never produces any values.
.IP \[bu] 2
A file redirection using \f[C]>\f[R], \f[C]>>\f[R] or \f[C]<>\f[R] sets
the value channel to one that throws an exception when written to.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> put foo > file # will truncate file if it exists
Exception: port has no value output
[tty 2], line 1: put foo > file
\[ti]> echo content > file
\[ti]> only-values < file
\[ti]> # previous command produced nothing
\f[R]
.fi
.PP
Redirections can also be used for closing or duplicating IO ports.
Instead of writing a filename, use \f[C]&fd\f[R] (where \f[C]fd\f[R] is
a number, or any of \f[C]stdin\f[R], \f[C]stdout\f[R] and
\f[C]stderr\f[R]) for duplicating, or \f[C]&-\f[R] for closing.
In this case, the redirection operator only determines the default
destination FD (and is totally irrevelant if a destination IO port is
specified).
Examples:
.IP
.nf
\f[C]
\[ti]> date >&-
date: stdout: Bad file descriptor
Exception: date exited with 1
[tty 3], line 1: date >&-
\[ti]> put foo >&-
Exception: port has no value output
[tty 37], line 1: put foo >&-
\f[R]
.fi
.PP
If you have multiple related redirections, they are applied in the order
they appear.
For instance:
.IP
.nf
\f[C]
\[ti]> fn f { echo out; echo err >&2 } # echoes \[dq]out\[dq] on stdout, \[dq]err\[dq] on stderr
\[ti]> f >log 2>&1 # use file \[dq]log\[dq] for stdout, then use (changed) stdout for stderr
\[ti]> cat log
out
err
\f[R]
.fi
.PP
Redirections may appear anywhere in the command, except at the
beginning, (this may be restricted in future).
It\[cq]s usually good style to write redirections at the end of command
forms.
.SH Special commands
.PP
\f[B]Special commands\f[R] obey the same syntax rules as normal
commands, but have evaluation rules that are custom to each command.
Consider the following example:
.IP
.nf
\f[C]
\[ti]> or ?(echo x) ?(echo y) ?(echo z)
x
\[u25B6] $ok
\f[R]
.fi
.PP
In the example, the \f[C]or\f[R] command first evaluates its first
argument, which has the value \f[C]$ok\f[R] (a truish value) and the
side effect of outputting \f[C]x\f[R].
Due to the custom evaluation rule of \f[C]or\f[R], the rest of the
arguments are not evaluated.
.PP
If \f[C]or\f[R] were a normal command, the code above is still
syntactically correct.
However, Elvish would then evaluate all its arguments, with the side
effect of outputting \f[C]x\f[R], \f[C]y\f[R] and \f[C]z\f[R], before
calling \f[C]or\f[R].
.SS Declaring variables: \f[C]var\f[R] {#var}
.PP
The \f[C]var\f[R] special command declares local variables.
It takes any number of unqualified variable names (without the leading
\f[C]$\f[R]).
The variables will start out having value \f[C]$nil\f[R].
Examples:
.IP
.nf
\f[C]
\[ti]> var a
\[ti]> put $a
\[u25B6] $nil
\[ti]> var foo bar
\[ti]> put $foo $bar
\[u25B6] $nil
\[u25B6] $nil
\f[R]
.fi
.PP
To set alternative initial values, add an unquoted \f[C]=\f[R] and the
initial values.
Examples:
.IP
.nf
\f[C]
\[ti]> var a b = foo bar
\[ti]> put $a $b
\[u25B6] foo
\[u25B6] bar
\f[R]
.fi
.PP
Similar to \f[C]set\f[R], at most one of variables may be prefixed with
\f[C]\[at]\f[R] to function as a rest variable.
.PP
When declaring a variable that already exists, the existing variable is
shadowed.
The shadowed variable may still be accessed indirectly if it is
referenced by a function.
Example:
.IP
.nf
\f[C]
\[ti]> var x = old
\[ti]> fn f { put $x }
\[ti]> var x = new
\[ti]> put $x
\[u25B6] new
\[ti]> f
\[u25B6] old
\f[R]
.fi
.SS Setting the value of variables or elements: \f[C]set\f[R] {#set}
.PP
The \f[C]set\f[R] special command sets the value of variables or
elements.
.PP
It takes any number of \f[B]lvalues\f[R] (which refer to either
variables or elements), followed by an equal sign (\f[C]=\f[R]) and any
number of expressions.
The equal sign must appear unquoted, as a single argument.
.PP
An \f[B]lvalue\f[R] is one of the following:
.IP \[bu] 2
A variable name (without \f[C]$\f[R]).
.IP \[bu] 2
A variable name prefixed with \f[C]\[at]\f[R], for packing a variable
number of values into a list and assigning to the variable.
.RS 2
.PP
This variant is called a \f[B]rest variable\f[R].
There could be at most one rest variable.
.PP
\f[B]Note\f[R]: Schematically this is the reverse operation of exploding
a variable when using it, which is why they share the \f[C]\[at]\f[R]
sign.
.RE
.IP \[bu] 2
A variable name followed by one or more indices in brackets
(\f[C][]\f[R]), for assigning to an element.
.PP
The number of values the expressions evaluate to and lvalues must be
compatible.
To be more exact:
.IP \[bu] 2
If there is no rest variable, the number of values and lvalues must
match exactly.
.IP \[bu] 2
If there is a rest variable, the number of values should be at least the
number of lvalues minus one.
.PP
All the variables to set must already exist; use the \f[C]var\f[R]
special command to declare new variables.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> var x y z
\[ti]> set x = foo
\[ti]> put $x
\[u25B6] foo
\[ti]> x y = lorem ipsum
\[ti]> put $x $y
\[u25B6] lorem
\[u25B6] ipsum
\[ti]> set x \[at]y z = a b
\[ti]> put $x $y $z
\[u25B6] a
\[u25B6] []
\[u25B6] b
\[ti]> set x \[at]y z = a b c d
\[ti]> put $x $y $z
\[u25B6] a
\[u25B6] [b c]
\[u25B6] d
\[ti]> set y[0] = foo
\[ti]> put $y
\[u25B6] [foo c]
\f[R]
.fi
.PP
If the variable name contains any character that may not appear unquoted
in variable use expressions, it must be quoted even if it is otherwise a
valid bareword:
.IP
.nf
\f[C]
\[ti]> var \[aq]a/b\[aq]
\[ti]> set a/b = foo
compilation error: lvalue must be valid literal variable names
[tty 23], line 1: a/b = foo
\[ti]> set \[aq]a/b\[aq] = foo
\[ti]> put $\[aq]a/b\[aq]
\[u25B6] foo
\f[R]
.fi
.PP
Lists and maps in Elvish are immutable.
As a result, when assigning to the element of a variable that contains a
list or map, Elvish does not mutate the underlying list or map.
Instead, Elvish creates a new list or map with the mutation applied, and
assigns it to the variable.
Example:
.IP
.nf
\f[C]
\[ti]> var li = [foo bar]
\[ti]> var li2 = $li
\[ti]> set li[0] = lorem
\[ti]> put $li $li2
\[u25B6] [lorem bar]
\[u25B6] [foo bar]
\f[R]
.fi
.SS Deleting variables or elements: \f[C]del\f[R] {#del}
.PP
The \f[C]del\f[R] special command can be used to delete variables or map
elements.
Operands should be specified without a leading dollar sign, like the
left-hand side of assignments.
.PP
Example of deleting variable:
.IP
.nf
\f[C]
\[ti]> x = 2
\[ti]> echo $x
2
\[ti]> del x
\[ti]> echo $x
Compilation error: variable $x not found
[tty], line 1: echo $x
\f[R]
.fi
.PP
If the variable name contains any character that cannot appear unquoted
after \f[C]$\f[R], it must be quoted, even if it is otherwise a valid
bareword:
.IP
.nf
\f[C]
\[ti]> \[aq]a/b\[aq] = foo
\[ti]> del \[aq]a/b\[aq]
\f[R]
.fi
.PP
Deleting a variable does not affect closures that have already captured
it; it only removes the name.
Example:
.IP
.nf
\f[C]
\[ti]> x = value
\[ti]> fn f { put $x }
\[ti]> del x
\[ti]> f
\[u25B6] value
\f[R]
.fi
.PP
Example of deleting map element:
.IP
.nf
\f[C]
\[ti]> m = [&k=v &k2=v2]
\[ti]> del m[k2]
\[ti]> put $m
\[u25B6] [&k=v]
\[ti]> l = [[&k=v &k2=v2]]
\[ti]> del l[0][k2]
\[ti]> put $l
\[u25B6] [[&k=v]]
\f[R]
.fi
.SS Logics: \f[C]and\f[R], \f[C]or\f[R], \f[C]coalesce\f[R] {#and-or-coalesce}
.PP
The \f[C]and\f[R] special command outputs the first booleanly false
value the arguments evaluate to, or \f[C]$true\f[R] when given no value.
Examples:
.IP
.nf
\f[C]
\[ti]> and $true $false
\[u25B6] $false
\[ti]> and a b c
\[u25B6] c
\[ti]> and a $false
\[u25B6] $false
\f[R]
.fi
.PP
The \f[C]or\f[R] special command outputs the first booleanly true value
the arguments evaluate to, or \f[C]$false\f[R] when given no value.
Examples:
.IP
.nf
\f[C]
\[ti]> or $true $false
\[u25B6] $true
\[ti]> or a b c
\[u25B6] a
\[ti]> or $false a b
\[u25B6] a
\f[R]
.fi
.PP
The \f[C]coalesce\f[R] special command outputs the first non-nil value
the arguments evaluate to, or \f[C]$nil\f[R] when given no value.
Examples:
.IP
.nf
\f[C]
\[ti]> coalesce $nil a b
\[u25B6] a
\[ti]> coalesce $nil $nil
\[u25B6] $nil
\[ti]> coalesce $nil $nil a
\[u25B6] a
\[ti]> coalesce a b
\[u25B6] a
\f[R]
.fi
.PP
All three commands use short-circuit evaluation, and stop evaluating
arguments as soon as it sees a value satisfying the termination
condition.
For example, none of the following throws an exception:
.IP
.nf
\f[C]
\[ti]> and $false (fail foo)
\[u25B6] $false
\[ti]> or $true (fail foo)
\[u25B6] $true
\[ti]> coalesce a (fail foo)
\[u25B6] a
\f[R]
.fi
.SS Condition: \f[C]if\f[R] {#if}
.PP
\f[B]TODO\f[R]: Document the syntax notation, and add more examples.
.PP
Syntax:
.IP
.nf
\f[C]
if <condition> {
    <body>
} elif <condition> {
    <body>
} else {
    <else-body>
}
\f[R]
.fi
.PP
The \f[C]if\f[R] 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.
.PP
The condition part is an expression, not a command like in other shells.
Example:
.IP
.nf
\f[C]
fn tell-language [fname]{
    if (has-suffix $fname .go) {
        echo $fname\[dq] is a Go file!\[dq]
    } elif (has-suffix $fname .c) {
        echo $fname\[dq] is a C file!\[dq]
    } else {
        echo $fname\[dq] is a mysterious file!\[dq]
    }
}
\f[R]
.fi
.PP
The condition part must be syntactically a single expression, but it can
evaluate to multiple values, in which case they are and\[cq]ed:
.IP
.nf
\f[C]
if (put $true $false) {
    echo \[dq]will not be executed\[dq]
}
\f[R]
.fi
.PP
If the expression evaluates to 0 values, it is considered true,
consistent with how \f[C]and\f[R] works.
.PP
Tip: a combination of \f[C]if\f[R] and \f[C]?()\f[R] gives you a
semantics close to other shells:
.IP
.nf
\f[C]
if ?(test -d .git) {
    # do something
}
\f[R]
.fi
.PP
However, for Elvish\[cq]s builtin predicates that output values instead
of throw exceptions, the output capture construct \f[C]()\f[R] should be
used.
.SS Conditional loop: \f[C]while\f[R] {#while}
.PP
Syntax:
.IP
.nf
\f[C]
while <condition> {
    <body>
} else {
    <else-body>
}
\f[R]
.fi
.PP
Execute the body as long as the condition evaluates to a booleanly true
value.
.PP
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).
.SS Iterative loop: \f[C]for\f[R] {#for}
.PP
Syntax:
.IP
.nf
\f[C]
for <var> <container> {
    <body>
} else {
    <body>
}
\f[R]
.fi
.PP
Iterate the container (e.g.
a list).
In each iteration, assign the variable to an element of the container
and execute the body.
.PP
The else body, if present, is executed if the body has never been
executed (i.e.
the iteration value has no elements).
.SS Exception control: \f[C]try\f[R] {#try}
.PP
(If you just want to capture the exception, you can use the more concise
exception capture construct \f[C]?()\f[R] instead.)
.PP
Syntax:
.IP
.nf
\f[C]
try {
    <try-block>
} except except-varname {
    <except-block>
} else {
    <else-block>
} finally {
    <finally-block>
}
\f[R]
.fi
.PP
Only \f[C]try\f[R] and \f[C]try-block\f[R] are required.
This control structure behaves as follows:
.IP "1." 3
The \f[C]try-block\f[R] is always executed first.
.IP "2." 3
If \f[C]except\f[R] is present and an exception occurs in
\f[C]try-block\f[R], it is caught and stored in
\f[C]except-varname\f[R], and \f[C]except-block\f[R] is then executed.
Example:
.RS 4
.IP
.nf
\f[C]
\[ti]> try { fail bad } except e { put $e }
\[u25B6] ?(fail bad)
\f[R]
.fi
.PP
Note that if \f[C]except\f[R] is not present, exceptions thrown from
\f[C]try\f[R] are not caught: for instance, \f[C]try { fail bad }\f[R]
throws \f[C]bad\f[R]; it is equivalent to a plain \f[C]fail bad\f[R].
.PP
Note that the word after \f[C]except\f[R] names a variable, not a
matching condition.
Exception matching is not supported yet.
For instance, you may want to only match exceptions that were created
with \f[C]fail bad\f[R] with \f[C]except bad\f[R], but in fact this
creates a variable \f[C]$bad\f[R] that contains whatever exception was
thrown.
.RE
.IP "3." 3
If no exception occurs and \f[C]else\f[R] is present,
\f[C]else-block\f[R] is executed.
Example:
.RS 4
.IP
.nf
\f[C]
\[ti]> try { nop } else { echo well }
well
\f[R]
.fi
.RE
.IP "4." 3
If \f[C]finally-block\f[R] is present, it is executed.
Examples:
.RS 4
.IP
.nf
\f[C]
\[ti]> try { fail bad } finally { echo final }
final
Exception: bad
Traceback:
  [tty], line 1:
    try { fail bad } finally { echo final }
\[ti]> try { echo good } finally { echo final }
good
final
\f[R]
.fi
.RE
.IP "5." 3
If the exception was not caught (i.e.
\f[C]except\f[R] is not present), it is rethrown.
.PP
Exceptions thrown in blocks other than \f[C]try-block\f[R] are not
caught.
If an exception was thrown and either \f[C]except-block\f[R] or
\f[C]finally-block\f[R] throws another exception, the original exception
is lost.
Examples:
.IP
.nf
\f[C]
\[ti]> try { fail bad } except e { fail worse }
Exception: worse
Traceback:
  [tty], line 1:
    try { fail bad } except e { fail worse }
\[ti]> 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 }
\f[R]
.fi
.SS Function definition: \f[C]fn\f[R] {#fn}
.PP
Syntax:
.IP
.nf
\f[C]
fn <name> <lambda>
\f[R]
.fi
.PP
Define a function with a given name.
The function behaves in the same way to the lambda used to define it,
except that it \[lq]captures\[rq] \f[C]return\f[R].
In other words, \f[C]return\f[R] will fall through lambdas not defined
with \f[C]fn\f[R], and continues until it exits a function defined with
\f[C]fn\f[R]:
.IP
.nf
\f[C]
\[ti]> fn f {
     { echo a; return }
     echo b # will not execute
   }
\[ti]> f
a
\[ti]> {
     f
     echo c # executed, because f \[dq]captures\[dq] the return
   }
a
c
\f[R]
.fi
.PP
\f[B]TODO\f[R]: Find a better way to describe this.
Hopefully the example is illustrative enough, though.
.PP
The lambda may refer to the function being defined.
This makes it easy to define recursive functions:
.IP
.nf
\f[C]
\[ti]> fn f [n]{ if (== $n 0) { put 1 } else { * $n (f (- $n 1)) } }
\[ti]> f 3
\[u25B6] (float64 6)
\f[R]
.fi
.PP
Under the hood, \f[C]fn\f[R] defines a variable with the given name plus
\f[C]\[ti]\f[R] (see variable suffix).
Example:
.IP
.nf
\f[C]
\[ti]> fn f { echo hello from f }
\[ti]> var v = $f\[ti]
\[ti]> $v
hello from f
\f[R]
.fi
.SS Language pragmas: \f[C]pragma\f[R] {#pragma}
.PP
The \f[C]pragma\f[R] special command can be used to set
\f[B]pragmas\f[R] that affect the behavior of the Elvish language.
The syntax looks like:
.IP
.nf
\f[C]
pragma <name> = <value>
\f[R]
.fi
.PP
The name must appear literally.
The value must also appear literally, unless otherwise specified.
.PP
Pragmas apply from the point it appears, to the end of the lexical scope
it appears in, including subscopes.
.PP
The following pragmas are available:
.IP \[bu] 2
The \f[C]unknown-command\f[R] pragma affects the resolution of command
heads, and can take one of two values, \f[C]external\f[R] (the default)
and \f[C]disallow\f[R].
See ordinary command for details.
.RS 2
.PP
\f[B]Note\f[R]: \f[C]pragma unknown-command = disallow\f[R] enables a
style where uses of external commands must be explicitly via the
\f[C]e:\f[R] namespace.
You can also explicitly declare a set of external commands to use
directly, like the following:
.IP
.nf
\f[C]
pragma unknown-command = disallow
var ls = $e:ls\[ti]
var cat = $e:cat\[ti]
# ls and cat can be used directly;
# other external commands must be prefixed with e:
\f[R]
.fi
.RE
.SH Pipeline
.PP
A \f[B]pipeline\f[R] is formed by joining one or more commands together
with the pipe sign (\f[C]|\f[R]).
.PP
For each pair of adjacent commands \f[C]a | b\f[R], the standard output
of the left-hand command \f[C]a\f[R] (IO port 1) is connected to the
standard input (IO port 0) of the right-hand command \f[C]b\f[R].
Both the file and the value channel are connected, even if one of them
is not used.
.PP
Elvish may have internal buffering for both the file and the value
channel, so \f[C]a\f[R] may be able to write bytes or values even if
\f[C]b\f[R] is not reading them.
The exact buffer size is not specified.
.PP
Command redirections are applied before the connection happens.
For instance, the following writes \f[C]foo\f[R] to \f[C]a.txt\f[R]
instead of the output:
.IP
.nf
\f[C]
\[ti]> echo foo > a.txt | cat
\[ti]> cat a.txt
foo
\f[R]
.fi
.PP
A pipeline runs all of its command in parallel, and terminates when all
of the commands have terminated.
.SS Pipeline exception
.PP
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:
.IP \[bu] 2
If only one command has thrown an exception, that exception is rethrown.
.IP \[bu] 2
If more than one commands have thrown exceptions, a \[lq]composite
exception\[rq], containing information all exceptions involved, is
thrown.
.PP
If a command threw an exception because it tried to write output when
the next command has terminated, that exception is suppressed when it is
propagated to the pipeline.
.PP
For example, the \f[C]put\f[R] command throws an exception when trying
to write to a closed pipe, so the following loop will terminate with an
exception:
.IP
.nf
\f[C]
\[ti]> while $true { put foo } > &-
Exception: port has no value output
[tty 9], line 1: while $true { put foo } > &-
\f[R]
.fi
.PP
However, if it appears in a pipeline before \f[C]nop\f[R], the entire
pipeline will not throw an exception:
.IP
.nf
\f[C]
\[ti]> while $true { put foo } | nop
\[ti]> # no exception thrown from previous line
\f[R]
.fi
.PP
Internally, the \f[C]put foo\f[R] command still threw an exception, but
since that exception was trying to write to output when \f[C]nop\f[R]
already terminated, that exception was suppressed by the pipeline.
.PP
This can be more clearly observed with the following code:
.IP
.nf
\f[C]
\[ti]> var r = $false
\[ti]> { while $true { put foo }; set r = $true } | nop
\[ti]> put $r
\[u25B6] $false
\f[R]
.fi
.PP
The same mechanism works for builtin commands that write to the byte
output:
.IP
.nf
\f[C]
\[ti]> var r = $false
\[ti]> { while $true { echo foo }; set r = $true } | nop
\[ti]> put $r
\[u25B6] $false
\f[R]
.fi
.PP
On UNIX, if an external command was terminated by SIGPIPE, and Elvish
detected that it terminated after the next command in the pipeline, such
exceptions will also be suppressed by the pipeline.
For example, the following pipeline does not throw an exception, despite
the \f[C]yes\f[R] command being killed by SIGPIPE:
.IP
.nf
\f[C]
\[ti]> yes | head -n1
y
\f[R]
.fi
.SS Background pipeline
.PP
Adding an ampersand \f[C]&\f[R] to the end of a pipeline will cause it
to be executed in the background.
In this case, the rest of the code chunk will continue to execute
without waiting for the pipeline to finish.
Exceptions thrown from the background pipeline do not affect the code
chunk that contains it.
.PP
When a background pipeline finishes, a message is printed to the
terminal if the shell is interactive.
.SH Code Chunk
.PP
A \f[B]code chunk\f[R] is formed by joining zero or more pipelines
together, separating them with either newlines or semicolons.
.PP
Pipelines in a code chunk are executed in sequence.
If any pipeline throws an exception, the execution of the whole code
chunk stops, propagating that exception.
.SH Exception and Flow Commands
.PP
Exceptions have similar semantics to those in Python or Java.
They can be thrown with the fail command and caught with either
exception capture \f[C]?()\f[R] or the \f[C]try\f[R] special command.
.PP
If an external command exits with a non-zero status, Elvish treats that
as an exception.
.PP
Flow commands \[en] \f[C]break\f[R], \f[C]continue\f[R] and
\f[C]return\f[R] \[en] are ordinary builtin commands that raise special
\[lq]flow control\[rq] exceptions.
The \f[C]for\f[R], \f[C]while\f[R], and \f[C]peach\f[R] commands capture
\f[C]break\f[R] and \f[C]continue\f[R], while \f[C]fn\f[R] modifies its
closure to capture \f[C]return\f[R].
.PP
One interesting implication is that since flow commands are just
ordinary commands you can build functions on top of them.
For instance, this function \f[C]break\f[R]s randomly:
.IP
.nf
\f[C]
fn random-break {
  if eq (randint 2) 0 {
    break
  }
}
\f[R]
.fi
.PP
The function \f[C]random-break\f[R] can then be used in for-loops and
while-loops.
.PP
Note that the \f[C]return\f[R] flow control exception is only captured
by functions defined with \f[C]fn\f[R].
It falls through ordinary lambdas:
.IP
.nf
\f[C]
fn f {
  {
    # returns f, falling through the innermost lambda
    return
  }
}
\f[R]
.fi
.SH Namespaces and Modules
.PP
Like other modern programming languages, but unlike traditional shells,
Elvish has a \f[B]namespace\f[R] mechanism for preventing name
collisions.
.SS Syntax
.PP
Prepend \f[C]namespace:\f[R] to command names and variable names to
specify the namespace.
The following code
.IP
.nf
\f[C]
e:echo $E:PATH
\f[R]
.fi
.PP
uses the \f[C]echo\f[R] command from the \f[C]e:\f[R] namespace and the
\f[C]PATH\f[R] variable from the \f[C]E:\f[R] namespace.
The colon is considered part of the namespace name.
.PP
Namespaces may be nested; for example, calling
\f[C]edit:location:start\f[R] first finds the \f[C]edit:\f[R] namespace,
and then the \f[C]location:\f[R] namespace inside it, and then call the
\f[C]start\f[R] function within the nested namespace.
.SS Special namespaces
.PP
The following namespaces have special meanings to the language:
.IP \[bu] 2
\f[C]local:\f[R] and \f[C]up:\f[R] refer to lexical scopes, and have
been documented above.
.IP \[bu] 2
\f[C]e:\f[R] refers to externals.
For instance, \f[C]e:ls\f[R] refers to the external command
\f[C]ls\f[R].
.RS 2
.PP
Most of the time you can rely on static resolution rules of ordinary
commands and do not need to use this explicitly, unless a function
defined by you (or an Elvish builtin) shadows an external command.
.RE
.IP \[bu] 2
\f[C]E:\f[R] refers to environment variables.
For instance, \f[C]$E:USER\f[R] is the environment variable
\f[C]USER\f[R].
.RS 2
.PP
This \f[B]is\f[R] always needed, because unlike command resolution,
variable resolution does not fall back onto environment variables.
.RE
.IP \[bu] 2
\f[C]builtin:\f[R] refers to builtin functions and variables.
.RS 2
.PP
You don\[cq]t need to use this explicitly unless you have defined names
that shadows builtin counterparts.
.RE
.SS Modules
.PP
Apart from the special namespaces, the most common usage of namespaces
is to reference modules, reusable pieces of code that are either shipped
with Elvish itself or defined by the user.
.SS Importing modules with \f[C]use\f[R]
.PP
Modules are imported using the \f[C]use\f[R] special command.
It requires a \f[B]module spec\f[R] and allows a namespace alias:
.IP
.nf
\f[C]
use $spec $alias?
\f[R]
.fi
.PP
The module spec and the alias must both be a simple string literal.
Compound strings such as \f[C]\[aq]a\[aq]/b\f[R] are not allowed.
.PP
The module spec specifies which module to import.
The alias, if given, specifies the namespace to import the module under.
By default, the namespace is derived from the module spec by taking the
part after the last slash.
.PP
Module specs fall into three categories that are resolved in the
following order:
.IP "1." 3
\f[B]Relative\f[R]: These are relative to the file containing the
\f[C]use\f[R] command.
.IP "2." 3
\f[B]User defined\f[R]: These match a user defined module in a module
search directory.
.IP "3." 3
\f[B]Pre-defined\f[R]: These match the name of a pre-defined module,
such as \f[C]math\f[R] or \f[C]str\f[R].
.PP
If a module spec doesn\[cq]t match any of the above a \[lq]no such
module\[rq] exception is raised.
.PP
Examples:
.IP
.nf
\f[C]
use str # imports the \[dq]str\[dq] module as \[dq]str:\[dq]
use a/b/c # imports the \[dq]a/b/c\[dq] module as \[dq]c:\[dq]
use a/b/c foo # imports the \[dq]a/b/c\[dq] module as \[dq]foo:\[dq]
\f[R]
.fi
.SS Pre-defined modules
.PP
Elvish\[cq]s standard library provides the following pre-defined modules
that can be imported by the \f[C]use\f[R] command:
.IP \[bu] 2
edit is only available in interactive mode.
As a special case it does not need importing via \f[C]use\f[R], but this
may change in the future.
.IP \[bu] 2
epm
.IP \[bu] 2
math
.IP \[bu] 2
path
.IP \[bu] 2
platform
.IP \[bu] 2
re
.IP \[bu] 2
readline-binding
.IP \[bu] 2
store
.IP \[bu] 2
str
.IP \[bu] 2
unix is only available on UNIX-like platforms (see
\f[C]$platform:is-unix\f[R])
.SS User-defined modules
.PP
You can define your own modules in Elvish by putting them under one of
the module search directories and giving them a \f[C].elv\f[R] extension
(but see relative imports for an alternative).
For instance, to define a module named \f[C]a\f[R], you can put the
following in \f[C]\[ti]/.config/elvish/lib/a.elv\f[R] (on Windows,
replace \f[C]\[ti]/.config\f[R] with
\f[C]\[ti]\[rs]AppData\[rs]Roaming\f[R]):
.IP
.nf
\f[C]
\[ti]> cat \[ti]/.config/elvish/lib/a.elv
echo \[dq]mod a loading\[dq]
fn f {
  echo \[dq]f from mod a\[dq]
}
\f[R]
.fi
.PP
This module can now be imported by \f[C]use a\f[R]:
.IP
.nf
\f[C]
\[ti]> use a
mod a loading
\[ti]> a:f
f from mod a
\f[R]
.fi
.PP
Similarly, a module defined in
\f[C]\[ti]/.config/elvish/lib/x/y/z.elv\f[R] can be imported by
\f[C]use x/y/z\f[R]:
.IP
.nf
\f[C]
\[ti]> cat .config/elvish/lib/x/y/z.elv
fn f {
  echo \[dq]f from x/y/z\[dq]
}
\[ti]> use x/y/z
\[ti]> z:f
f from x/y/z
\f[R]
.fi
.PP
In general, a module defined in namespace will be the same as the file
name (without the \f[C].elv\f[R] extension).
.PP
There is experimental support for importing modules written in Go.
See the project repository (https://github.com/elves/elvish) for
details.
.SS Circular dependencies
.PP
Circular dependencies are allowed but has an important restriction.
If a module \f[C]a\f[R] contains \f[C]use b\f[R] and module \f[C]b\f[R]
contains \f[C]use a\f[R], the top-level statements in module \f[C]b\f[R]
will only be able to access variables that are defined before the
\f[C]use b\f[R] in module \f[C]a\f[R]; other variables will be
\f[C]$nil\f[R].
.PP
On the other hand, functions in module \f[C]b\f[R] will have access to
bindings in module \f[C]a\f[R] after it is fully evaluated.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> cat a.elv
var before = before
use ./b
var after = after
\[ti]> cat b.elv
use ./a
put $a:before $a:after
fn f { put $a:before $a:after }
\[ti]> use ./a
\[u25B6] before
\[u25B6] $nil
\[ti]> use ./b
\[ti]> b:f
\[u25B6] before
\[u25B6] after
\f[R]
.fi
.PP
Note that this behavior can be different depending on whether the REPL
imports \f[C]a\f[R] or \f[C]b\f[R] first.
In the previous example, if the REPL imports \f[C]b\f[R] first, it will
have access to all the variables in \f[C]a\f[R]:
.IP
.nf
\f[C]
\[ti]> use ./b
\[u25B6] before
\[u25B6] after
\f[R]
.fi
.PP
\f[B]Note\f[R]: Elvish caches imported modules.
If you are trying this locally, run a fresh Elvish instance with
\f[C]exec\f[R] first.
.PP
When you do need to have circular dependencies, it is best to avoid
using variables from the modules in top-level statements, and only use
them in functions.
.SS Relative imports
.PP
The module spec may begin with \f[C]./\f[R] or \f[C]../\f[R] to
introduce a \f[B]relative import\f[R].
When \f[C]use\f[R] is invoked from a file this will import the file
relative to the location of the file.
When \f[C]use\f[R] is invoked from an interactive prompt, this will
import the file relative to the current working directory.
.SS Scoping of imports
.PP
Namespace imports are lexically scoped.
For instance, if you \f[C]use\f[R] a module within an inner scope, it is
not available outside that scope:
.IP
.nf
\f[C]
{
    use some-mod
    some-mod:some-func
}
some-mod:some-func # not valid
\f[R]
.fi
.PP
The imported modules themselves are also evaluated in a separate 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 \f[C]ls\f[R] as a wrapper function in
\f[C]rc.elv\f[R]:
.IP
.nf
\f[C]
fn ls [\[at]a]{
    e:ls --color=auto $\[at]a
}
\f[R]
.fi
.PP
That definition is not visible in module files: \f[C]ls\f[R] will still
refer to the external command \f[C]ls\f[R], unless you shadow it in the
very same module.
.SS Re-importing
.PP
Modules are cached after one import.
Subsequent imports do not re-execute the module; they only serve the
bring it into the current scope.
Moreover, the cache is keyed by the path of the module, not the name
under which it is imported.
For instance, if you have the following in
\f[C]\[ti]/.config/elvish/lib/a/b.elv\f[R]:
.IP
.nf
\f[C]
echo importing
\f[R]
.fi
.PP
The following code only prints one \f[C]importing\f[R]:
.IP
.nf
\f[C]
{ use a/b }
use a/b # only brings mod into the lexical scope
\f[R]
.fi
.PP
As does the following:
.IP
.nf
\f[C]
use a/b
use a/b alias
\f[R]
.fi