Using builtin: explicitly¶

The builtin module is consulted implicitly when resolving unqualified names, so you usually don’t need to specify builtin: explicitly. However, there are some cases where it is useful to do that:

•

When a builtin function is shadowed by a local function, you can still use the builtin function by specifying builtin:. This is especially useful when wrapping a builtin function:

•

Introspecting the builtin module, for example keys $builtin:.

Usage Notation¶

The usage of a builtin command is described by giving an example usage, using variables as arguments. For instance, The repeat command takes two arguments and are described as:

repeat $n $v
    

Optional arguments are represented with a trailing ?, while variadic arguments with a trailing .... For instance, the count command takes an optional list:

count $input-list?
    

While the put command takes an arbitrary number of arguments:

put $values...
    

Options are given along with their default values. For instance, the echo command takes an sep option and arbitrary arguments:

echo &sep=' ' $value...
    

(When you calling functions, options are always optional.)

Supplying Input¶

Some builtin functions, e.g. count and each, can take their input in one of two ways:

1.

From pipe:

2.

From an argument – an iterable value:

When documenting such commands, the optional argument is always written as $input-list?. On the other hand, a trailing $input-list? always indicates that a command can take its input in one of two ways above: this fact is not repeated below.

Note: You should prefer the first form, unless using it requires explicit put commands. Avoid count [(some-command)] or each $some-func [(some-command)]; they are, most of the time, equivalent to some-command | count or some-command | each $some-func.

Rationale: An alternative way to design this is to make (say) count take an arbitrary number of arguments, and count its arguments; when there is 0 argument, count inputs. However, this leads to problems in code like count *; the intention is clearly to count the number of files in the current directory, but when the current directory is empty, count will wait for inputs. Hence it is required to put the input in a list: count [*] unambiguously supplies input in the argument, even if there is no file.

Commands That Operate On Numbers¶

Commands that operate on numbers are quite flexible about the format of those numbers. See the discussion of the number data type.

Because numbers are normally specified as strings, rather than as an explicit float64 data type, some builtin commands have variants intended to operate on strings or numbers exclusively. For instance, the numerical equality command is ==, while the string equality command is ==s. Another example is the + builtin, which only operates on numbers and does not function as a string concatenation command. Consider these examples:

~> + x 1
Exception: wrong type of 1'th argument: cannot parse as number: x
[tty], line 1: + x 1
~> + inf 1
▶ (float64 +Inf)
~> + -inf 1
▶ (float64 -Inf)
~> + -infinity 1
▶ (float64 -Inf)
~> + -infinityx 1
Exception: wrong type of 1'th argument: cannot parse as number: -infinityx
[tty], line 1: + -infinityx 1
    

Predicates¶

Predicates are functions that write exactly one output that is either $true or $false. They are described like “Determine ...” or “Test ...”. See is for one example.

“Do Not Use” Functions and Variables¶

The name of some variables and functions have a leading -. This is a convention to say that it is subject to change and should not be depended upon. They are either only useful for debug purposes, or have known issues in the interface or implementation, and in the worst case will make Elvish crash. (Before 1.0, all features are subject to change, but those ones are sure to be changed.)

Those functions and variables are documented near the end of the respective sections. Their known problem is also discussed.

$_¶

A blackhole variable.

Values assigned to it will be discarded. Referencing it always results in $nil.

$after-chdir¶

A list of functions to run after changing directory. These functions are always called with directory to change it, which might be a relative path. The following example also shows $before-chdir:

~> before-chdir = [[dir]{ echo "Going to change to "$dir", pwd is "$pwd }]
~> after-chdir = [[dir]{ echo "Changed to "$dir", pwd is "$pwd }]
~> cd /usr
Going to change to /usr, pwd is /Users/xiaq
Changed to /usr, pwd is /usr
/usr> cd local
Going to change to local, pwd is /usr
Changed to local, pwd is /usr/local
/usr/local>
    

@cf before-chdir

$args¶

A list containing command-line arguments. Analogous to argv in some other languages. Examples:

~> echo 'put $args' > args.elv
~> elvish args.elv foo -bar
▶ [foo -bar]
~> elvish -c 'put $args' foo -bar
▶ [foo -bar]
    

As demonstrated above, this variable does not contain the name of the script used to invoke it. For that information, use the src command.

@cf src

$before-chdir¶

A list of functions to run before changing directory. These functions are always called with the new working directory.

@cf after-chdir

$false¶

The boolean false value.

$nil¶

A special value useful for representing the lack of values.

$notify-bg-job-success¶

Whether to notify success of background jobs, defaulting to $true.

Failures of background jobs are always notified.

$num-bg-jobs¶

Number of background jobs.

$ok¶

The special value used by ?() to signal absence of exceptions.

$paths¶

A list of search paths, kept in sync with $E:PATH. It is easier to use than $E:PATH.

$pid¶

The process ID of the current Elvish process.

$pwd¶

The present working directory. Setting this variable has the same effect as cd. This variable is most useful in a temporary assignment.

Example:

## Updates all git repositories
for x [*/] {


  pwd=$x {


    if ?(test -d .git) {


      git pull


    }


  }
}
    

Etymology: the pwd command.

@cf cd

$true¶

The boolean true value.

$value-out-indicator¶

A string put before value outputs (such as those of of put). Defaults to '▶ '. Example:

~> put lorem ipsum
▶ lorem
▶ ipsum
~> value-out-indicator = 'val> '
~> put lorem ipsum
val> lorem
val> ipsum
    

Note that you almost always want some trailing whitespace for readability.

%¶

% $dividend $divisor
    

Output the remainder after dividing $dividend by $divisor. Both must be integers. Example:

~> % 23 7
▶ 2
    

< <= == != > >=¶

<  $number... # less
<= $number... # less or equal
== $number... # equal
!= $number... # not equal
>  $number... # greater
>= $number... # greater or equal
    

Number comparisons. All of them accept an arbitrary number of arguments:

1.

When given fewer than two arguments, all output $true.

2.

When given two arguments, output whether the two arguments satisfy the named relationship.

3.

When given more than two arguments, output whether every adjacent pair of numbers satisfy the named relationship.

Examples:

~> == 3 3.0
▶ $true
~> < 3 4
▶ $true
~> < 3 4 10
▶ $true
~> < 6 9 1
▶ $false
    

As a consequence of rule 3, the != command outputs $true as long as any adjacent pair of numbers are not equal, even if some numbers that are not adjacent are equal:

~> != 5 5 4
▶ $false
~> != 5 6 5
▶ $true
    

<s <=s ==s !=s >s >=s¶

<s  $string... # less
<=s $string... # less or equal
==s $string... # equal
!=s $string... # not equal
>s  $string... # greater
>=s $string... # greater or equal
    

String comparisons. They behave similarly to their number counterparts when given multiple arguments. Examples:

~> >s lorem ipsum
▶ $true
~> ==s 1 1.0
▶ $false
~> >s 8 12
▶ $true
    

+ - * /¶

+ $summand...
- $minuend $subtrahend...
* $factor...
/ $dividend $divisor...
    

Basic arithmetic operations of adding, subtraction, multiplication and division respectively.

All of them can take multiple arguments:

~> + 2 5 7 # 2 + 5 + 7
▶ 14
~> - 2 5 7 # 2 - 5 - 7
▶ -10
~> * 2 5 7 # 2 * 5 * 7
▶ 70
~> / 2 5 7 # 2 / 5 / 7
▶ 0.05714285714285715
    

When given one element, they all output their sole argument (given that it is a valid number). When given no argument,

•

+ outputs 0, and * outputs 1. You can think that they both have a “hidden” argument of 0 or 1, which does not alter their behaviors (in mathematical terms, 0 and 1 are identity elements (https://en.wikipedia.org/wiki/Identity_element) of addition and multiplication, respectively).

•

- throws an exception.

•

/ becomes a synonym for cd /, due to the implicit cd feature. (The implicit cd feature will probably change to avoid this oddity).

all¶

all $input-list?
    

Passes inputs to the output as is. Byte inputs into values, one per line.

This is an identity function for commands with value outputs: a | all is equivalent to a if it only outputs values.

This function is useful for turning inputs into arguments, like:

~> use str
~> put 'lorem,ipsum' | str:split , (all)
▶ lorem
▶ ipsum
    

Or capturing all inputs in a variable:

~> x = [(all)]
foo
bar
(Press ^D)
~> put $x
▶ [foo bar]
    

When given a list, it outputs all elements of the list:

~> all [foo bar]
▶ foo
▶ bar
    

@cf one

assoc¶

assoc $container $k $v
    

Output a slightly modified version of $container, such that its value at $k is $v. Applies to both lists and to maps.

When $container is a list, $k may be a negative index. However, slice is not yet supported.

~> assoc [foo bar quux] 0 lorem
▶ [lorem bar quux]
~> assoc [foo bar quux] -1 ipsum
▶ [foo bar ipsum]
~> assoc [&k=v] k v2
▶ [&k=v2]
~> assoc [&k=v] k2 v2
▶ [&k2=v2 &k=v]
    

Etymology: Clojure (https://clojuredocs.org/clojure.core/assoc).

@cf dissoc

base¶

base $base $number...
    

Outputs a string for each $number written in $base. The $base must be between 2 and 36, inclusive. Examples:

~> base 2 1 3 4 16 255
▶ 1
▶ 11
▶ 100
▶ 10000
▶ 11111111
~> base 16 1 3 4 16 255
▶ 1
▶ 3
▶ 4
▶ 10
▶ ff
    

bool¶

bool $value
    

Convert a value to boolean. In Elvish, only $false and errors are booleanly false. Everything else, including 0, empty strings and empty lists, is booleanly true:

~> bool $true
▶ $true
~> bool $false
▶ $false
~> bool $ok
▶ $true
~> bool ?(fail haha)
▶ $false
~> bool ''
▶ $true
~> bool []
▶ $true
~> bool abc
▶ $true
    

@cf not

break¶

Raises the special “break” exception. When raised inside a loop it is captured and causes the loop to terminate.

Because break raises an exception it can be caught by a try block. If not caught, either implicitly by a loop or explicitly, it causes a failure like any other uncaught exception.

See the discussion about flow commands and exceptions

Note: You can create a break function and it will shadow the builtin command. If you do so you should explicitly invoke the builtin. For example:

> fn break []{ put 'break'; builtin:break; put 'should not appear' }
> for x [a b c] { put $x; break; put 'unexpected' }
▶ a
▶ break
    

cd¶

cd $dirname
    

Change directory. This affects the entire process; i.e., all threads whether running indirectly (e.g., prompt functions) or started explicitly by commands such as peach.

Note that Elvish’s cd does not support cd -.

@cf pwd

chr¶

chr $number...
    

This function is deprecated; use str:from-codepoints instead.

Outputs a string consisting of the given Unicode codepoints. Example:

~> chr 0x61
▶ a
~> chr 0x4f60 0x597d
▶ 你好
    

Etymology: Python (https://docs.python.org/3/library/functions.html#chr).

@cf ord

constantly¶

constantly $value...
    

Output a function that takes no arguments and outputs $values when called. Examples:

~> f=(constantly lorem ipsum)
~> $f
▶ lorem
▶ ipsum
    

The above example is actually equivalent to simply f = []{ put lorem ipsum }; it is most useful when the argument is not a literal value, e.g.

~> f = (constantly (uname))
~> $f
▶ Darwin
~> $f
▶ Darwin
    

The above code only calls uname once, while if you do f = []{ put (uname) }, every time you invoke $f, uname will be called.

Etymology: Clojure (https://clojuredocs.org/clojure.core/constantly).

continue¶

Raises the special “continue” exception. When raised inside a loop it is captured and causes the loop to begin its next iteration.

Because continue raises an exception it can be caught by a try block. If not caught, either implicitly by a loop or explicitly, it causes a failure like any other uncaught exception.

See the discussion about flow commands and exceptions

Note: You can create a continue function and it will shadow the builtin command. If you do so you should explicitly invoke the builtin. For example:

> fn break []{ put 'continue'; builtin:continue; put 'should not appear' }
> for x [a b c] { put $x; continue; put 'unexpected' }
▶ a
▶ continue
▶ b
▶ continue
▶ c
▶ continue
    

count¶

count $input-list?
    

Count the number of inputs.

Examples:

~> count lorem # count bytes in a string
▶ 5
~> count [lorem ipsum]
▶ 2
~> range 100 | count
▶ 100
~> seq 100 | count
▶ 100
    

deprecate¶

deprecate $msg
    

Shows the given deprecation message to stderr. If called from a function or module, also shows the call site of the function or import site of the module. Does nothing if the combination of the call site and the message has been shown before.

~> deprecate msg
deprecation: msg
~> fn f { deprecate msg }
~> f
deprecation: msg
[tty 19], line 1: f
~> exec
~> deprecate msg
deprecation: msg
~> fn f { deprecate msg }
~> f
deprecation: msg
[tty 3], line 1: f
~> f # a different call site; shows deprecate message
deprecation: msg
[tty 4], line 1: f
~> fn g { f }
~> g
deprecation: msg
[tty 5], line 1: fn g { f }
~> g # same call site, no more deprecation message
    

dir-history¶

dir-history
    

Return a list containing the directory history. Each element is a map with two keys: path and score. The list is sorted by descending score.

Example:

~> dir-history | take 1
▶ [&path=/Users/foo/.elvish &score=96.79928]
    

dissoc¶

dissoc $map $k
    

Output a slightly modified version of $map, with the key $k removed. If $map does not contain $k as a key, the same map is returned.

~> dissoc [&foo=bar &lorem=ipsum] foo
▶ [&lorem=ipsum]
~> dissoc [&foo=bar &lorem=ipsum] k
▶ [&lorem=ipsum &foo=bar]
    

@cf assoc

drop¶

drop $n $input-list?
    

Drop the first $n elements of the input. If $n is larger than the number of input elements, the entire input is dropped.

Example:

~> drop 2 [a b c d e]
▶ c
▶ d
▶ e
~> use str
~> str:split ' ' 'how are you?' | drop 1
▶ are
▶ 'you?'
~> range 2 | drop 10
    

Etymology: Haskell.

@cf take

each¶

each $f $input-list?
    

Call $f on all inputs. Examples:

~> range 5 8 | each [x]{ ^ $x 2 }
▶ 25
▶ 36
▶ 49
~> each [x]{ put $x[:3] } [lorem ipsum]
▶ lor
▶ ips
    

@cf peach

Etymology: Various languages, as for each. Happens to have the same name as the iteration construct of Factor (http://docs.factorcode.org/content/word-each,sequences.html).

eawk¶

eawk $f $input-list?
    

For each input, call $f with the input followed by all its fields. The function may call break and continue.

It should behave the same as the following functions:

fn eawk [f @rest]{


  each [line]{


    @fields = (re:split '[ \t]+'


    (re:replace '^[ \t]+|[ \t]+$' '' $line))


    $f $line $@fields


  } $@rest
}
    

This command allows you to write code very similar to awk scripts using anonymous functions. Example:

~> echo ' lorem ipsum
1 2' | awk '{ print $1 }'
lorem
1
~> echo ' lorem ipsum
1 2' | eawk [line a b]{ put $a }
▶ lorem
▶ 1
    

echo¶

echo &sep=' ' $value...
    

Print all arguments, joined by the sep option, and followed by a newline.

Examples:

~> echo Hello   elvish
Hello elvish
~> echo "Hello   elvish"
Hello   elvish
~> echo &sep=, lorem ipsum
lorem,ipsum
    

Notes: The echo builtin does not treat -e or -n specially. For instance, echo -n just prints -n. Use double-quoted strings to print special characters, and print to suppress the trailing newline.

@cf print

Etymology: Bourne sh.

eq¶

eq $values...
    

Determine whether all $values are structurally equivalent. Writes $true when given no or one argument.

~> eq a a
▶ $true
~> eq [a] [a]
▶ $true
~> eq [&k=v] [&k=v]
▶ $true
~> eq a [b]
▶ $false
    

@cf is not-eq

Etymology: Perl (https://perldoc.perl.org/perlop.html#Equality-Operators).

eval¶

eval $code &ns=$nil &on-end=$nil
    

Evaluates $code, which should be a string. The evaluation happens in a new, restricted namespace, whose initial set of variables can be specified by the &ns option. After evaluation completes, the new namespace is passed to the callback specified by &on-end if it is not nil.

The namespace specified by &ns is never modified; it will not be affected by the creation or deletion of variables by $code. However, the values of the variables may be mutated by $code.

If the &ns option is $nil (the default), a temporary namespace built by amalgamating the local and upvalue scopes of the caller is used.

If $code fails to parse or compile, the parse error or compilation error is raised as an exception.

Basic examples that do not modify the namespace or any variable:

~> eval 'put x'
▶ x
~> x = foo
~> eval 'put $x'
▶ foo
~> ns = (ns [&x=bar])
~> eval &ns=$ns 'put $x'
▶ bar
    

Examples that modify existing variables:

~> y = foo
~> eval 'y = bar'
~> put $y
▶ bar
    

Examples that creates new variables and uses the callback to access it:

~> eval 'z = lorem'
~> put $z
compilation error: variable $z not found
[ttz 2], line 1: put $z
~> saved-ns = $nil
~> eval &on-end=[ns]{ saved-ns = $ns } 'z = lorem'
~> put $saved-ns[z]
▶ lorem
    

exec¶

exec $command?
    

Replace the Elvish process with an external $command, defaulting to elvish. This decrements $E:SHLVL before starting the new process.

This command always raises an exception on Windows with the message “not supported on Windows”.

exit¶

exit $status?
    

Exit the Elvish process with $status (defaulting to 0).

external¶

external $program
    

Construct a callable value for the external program $program. Example:

~> x = (external man)
~> $x ls # opens the manpage for ls
    

@cf has-external search-external

fail¶

fail $v
    

Throws an exception; $v may be any type. If $v is already an exception, fail rethrows it.

~> fail bad
Exception: bad
[tty 9], line 1: fail bad
~> put ?(fail bad)
▶ ?(fail bad)
~> fn f { fail bad }
~> fail ?(f)
Exception: bad
Traceback:


  [tty 7], line 1:


    fn f { fail bad }


  [tty 8], line 1:


    fail ?(f)
    

fclose¶

fclose $file
    

Close a file opened with fopen.

@cf fopen

float64¶

float64 123
float64 NaN
float64 Inf
    

Explicitly convert a string to a float64 data type.

This command is seldom needed since commands that operate on numbers will convert a string to a number. See the discussion of the number data type.

fopen¶

fopen $filename
    

Open a file. Currently, fopen only supports opening a file for reading. File must be closed with fclose explicitly. Example:

~> cat a.txt
This is
a file.
~> f = (fopen a.txt)
~> cat < $f
This is
a file.
~> fclose $f
    

@cf fclose

from-json¶

from-json
    

Takes bytes stdin, parses it as JSON and puts the result on structured stdout. The input can contain multiple JSONs, which can, but do not have to, be separated with whitespaces.

Examples:

~> echo '"a"' | from-json
▶ a
~> echo '["lorem", "ipsum"]' | from-json
▶ [lorem ipsum]
~> echo '{"lorem": "ipsum"}' | from-json
▶ [&lorem=ipsum]
~> # multiple JSONs running together
echo '"a""b"["x"]' | from-json
▶ a
▶ b
▶ [x]
~> # multiple JSONs separated by newlines
echo '"a"
{"k": "v"}' | from-json
▶ a
▶ [&k=v]
    

@cf to-json

from-lines¶

from-lines
    

Splits byte input into lines, and writes them to the value output. Value input is ignored.

~> { echo a; echo b } | from-lines
▶ a
▶ b
~> { echo a; put b } | from-lines
▶ a
    

@cf to-lines

-gc¶

-gc
    

Force the Go garbage collector to run.

This is only useful for debug purposes.

get-env¶

get-env $name
    

Gets the value of an environment variable. Throws an exception if the environment variable does not exist. Examples:

~> get-env LANG
▶ zh_CN.UTF-8
~> get-env NO_SUCH_ENV
Exception: non-existent environment variable
[tty], line 1: get-env NO_SUCH_ENV
    

@cf has-env set-env unset-env

has-env¶

has-env $name
    

Test whether an environment variable exists. Examples:

~> has-env PATH
▶ $true
~> has-env NO_SUCH_ENV
▶ $false
    

@cf get-env set-env unset-env

has-external¶

has-external $command
    

Test whether $command names a valid external command. Examples (your output might differ):

~> has-external cat
▶ $true
~> has-external lalala
▶ $false
    

@cf external search-external

has-key¶

has-key $container $key
    

Determine whether $key is a key in $container. A key could be a map key or an index on a list or string. This includes a range of indexes.

Examples, maps:

~> has-key [&k1=v1 &k2=v2] k1
▶ $true
~> has-key [&k1=v1 &k2=v2] v1
▶ $false
    

Examples, lists:

~> has-key [v1 v2] 0
▶ $true
~> has-key [v1 v2] 1
▶ $true
~> has-key [v1 v2] 2
▶ $false
~> has-key [v1 v2] 0:2
▶ $true
~> has-key [v1 v2] 0:3
▶ $false
    

Examples, strings:

~> has-key ab 0
▶ $true
~> has-key ab 1
▶ $true
~> has-key ab 2
▶ $false
~> has-key ab 0:2
▶ $true
~> has-key ab 0:3
▶ $false
    

has-prefix¶

has-prefix $string $prefix
    

Determine whether $prefix is a prefix of $string. Examples:

~> has-prefix lorem,ipsum lor
▶ $true
~> has-prefix lorem,ipsum foo
▶ $false
    

This function is deprecated; use str:has-prefix instead.

has-suffix¶

has-suffix $string $suffix
    

Determine whether $suffix is a suffix of $string. Examples:

~> has-suffix a.html .txt
▶ $false
~> has-suffix a.html .html
▶ $true
    

This function is deprecated; use str:has-suffix instead.

has-value¶

has-value $container $value
    

Determine whether $value is a value in $container.

Examples, maps:

~> has-value [&k1=v1 &k2=v2] v1
▶ $true
~> has-value [&k1=v1 &k2=v2] k1
▶ $false
    

Examples, lists:

~> has-value [v1 v2] v1
▶ $true
~> has-value [v1 v2] k1
▶ $false
    

Examples, strings:

~> has-value ab b
▶ $true
~> has-value ab c
▶ $false
    

-ifaddrs¶

-ifaddrs
    

Output all IP addresses of the current host.

This should be part of a networking module instead of the builtin module.

is¶

is $values...
    

Determine whether all $values have the same identity. Writes $true when given no or one argument.

The definition of identity is subject to change. Do not rely on its behavior.

~> is a a
▶ $true
~> is a b
▶ $false
~> is [] []
▶ $true
~> is [a] [a]
▶ $false
    

@cf eq

Etymology: Python (https://docs.python.org/3/reference/expressions.html#is).

keys¶

keys $map
    

Put all keys of $map on the structured stdout.

Example:

~> keys [&a=foo &b=bar &c=baz]
▶ a
▶ c
▶ b
    

Note that there is no guaranteed order for the keys of a map.

kind-of¶

kind-of $value...
    

Output the kinds of $values. Example:

~> kind-of lorem [] [&]
▶ string
▶ list
▶ map
    

The terminology and definition of “kind” is subject to change.

-log¶

-log $filename
    

Direct internal debug logs to the named file.

This is only useful for debug purposes.

make-map¶

make-map $input?
    

Outputs a map from an input consisting of containers with two elements. The first element of each container is used as the key, and the second element is used as the value.

If the same key appears multiple times, the last value is used.

Examples:

~> make-map [[k v]]
▶ [&k=v]
~> make-map [[k v1] [k v2]]
▶ [&k=v2]
~> put [k1 v1] [k2 v2] | make-map
▶ [&k1=v1 &k2=v2]
~> put aA bB | make-map
▶ [&a=A &b=B]
    

nop¶

nop &any-opt= $value...
    

Accepts arbitrary arguments and options and does exactly nothing.

Examples:

~> nop
~> nop a b c
~> nop &k=v
    

Etymology: Various languages, in particular NOP in assembly languages (https://en.wikipedia.org/wiki/NOP).

not¶

not $value
    

Boolean negation. Examples:

~> not $true
▶ $false
~> not $false
▶ $true
~> not $ok
▶ $false
~> not ?(fail error)
▶ $true
    

Note: The related logical commands and and or are implemented as special commands instead, since they do not always evaluate all their arguments. The not command always evaluates its only argument, and is thus a normal command.

@cf bool

not-eq¶

not-eq $values...
    

Determines whether every adjacent pair of $values are not equal. Note that this does not imply that $values are all distinct. Examples:

~> not-eq 1 2 3
▶ $true
~> not-eq 1 2 1
▶ $true
~> not-eq 1 1 2
▶ $false
    

@cf eq

ns¶

ns $map
    

Constructs a namespace from $map, using the keys as variable names and the values as their values. Examples:

~> n = (ns [&name=value])
~> put $n[name]
▶ value
~> n: = (ns [&name=value])
~> put $n:name
▶ value
    

one¶

one $input-list?
    

Passes inputs to outputs, if there is only a single one. Otherwise raises an exception.

This function can be used in a similar way to all, but is a better choice when you expect that there is exactly one output:

@cf all

only-bytes¶

only-bytes
    

Passes byte input to output, and discards value inputs.

Example:

~> { put value; echo bytes } | only-bytes
bytes
    

only-values¶

only-values
    

Passes value input to output, and discards byte inputs.

Example:

~> { put value; echo bytes } | only-values
▶ value
    

ord¶

ord $string
    

This function is deprecated; use str:to-codepoints instead.

Output value of each codepoint in $string, in hexadecimal. Examples:

~> ord a
▶ 0x61
~> ord 你好
▶ 0x4f60
▶ 0x597d
    

The output format is subject to change.

Etymology: Python (https://docs.python.org/3/library/functions.html#ord).

@cf chr

order¶

order &reverse=$false $less-than=$nil $inputs?
    

Outputs the input values sorted in ascending order. The sort is guaranteed to be stable (https://en.wikipedia.org/wiki/Sorting_algorithm#Stability).

The &reverse option, if true, reverses the order of output.

The &less-than option, if given, establishes the ordering of the elements. Its value should be a function that takes two arguments and outputs a single boolean indicating whether the first argument is less than the second argument. If the function throws an exception, order rethrows the exception without outputting any value.

If &less-than has value $nil (the default if not set), the following comparison algorithm is used:

•

Numbers are compared numerically. For the sake of sorting, NaN is treated as smaller than all other numbers.

•

Strings are compared lexicographically by bytes, which is equivalent to comparing by codepoints under UTF-8.

•

Lists are compared lexicographically by elements, if the elements at the same positions are comparable.

If the ordering between two elements are not defined by the conditions above, no value is outputted and an exception is thrown.

Examples:

~> put foo bar ipsum | order
▶ bar
▶ foo
▶ ipsum
~> order [(float64 10) (float64 1) (float64 5)]
▶ (float64 1)
▶ (float64 5)
▶ (float64 10)
~> order [[a b] [a] [b b] [a c]]
▶ [a]
▶ [a b]
▶ [a c]
▶ [b b]
~> order &reverse [a c b]
▶ c
▶ b
▶ a
~> order &less-than=[a b]{ eq $a x } [l x o r x e x m]
▶ x
▶ x
▶ x
▶ l
▶ o
▶ r
▶ e
▶ m
    

Beware that strings that look like numbers are treated as strings, not numbers. To sort strings as numbers, use an explicit &less-than option:

~> order [5 1 10]
▶ 1
▶ 10
▶ 5
~> order &less-than=[a b]{ < $a $b } [5 1 10]
▶ 1
▶ 5
▶ 10
    

path-*¶

path-abs $path
path-base $path
path-clean $path
path-dir $path
path-ext $path
    

See godoc of path/filepath (https://godoc.org/path/filepath). Go errors are turned into exceptions.

These functions are deprecated. Use the equivalent functions in the path: module.

peach¶

peach $f $input-list?
    

Call $f on all inputs, possibly in parallel.

Example (your output will differ):

~> range 1 7 | peach [x]{ + $x 10 }
▶ 12
▶ 11
▶ 13
▶ 16
▶ 15
▶ 14
    

This command is intended for homogeneous processing of possibly unbound data. If you need to do a fixed number of heterogeneous things in parallel, use run-parallel.

@cf each run-parallel

pipe¶

pipe
    

Create a new Unix pipe that can be used in redirections.

A pipe contains both the read FD and the write FD. When redirecting command input to a pipe with <, the read FD is used. When redirecting command output to a pipe with >, the write FD is used. It is not supported to redirect both input and output with <> to a pipe.

Pipes have an OS-dependent buffer, so writing to a pipe without an active reader does not necessarily block. Pipes must be explicitly closed with prclose and pwclose.

Putting values into pipes will cause those values to be discarded.

Examples (assuming the pipe has a large enough buffer):

~> p = (pipe)
~> echo 'lorem ipsum' > $p
~> head -n1 < $p
lorem ipsum
~> put 'lorem ipsum' > $p
~> head -n1 < $p
# blocks
# $p should be closed with prclose and pwclose afterwards
    

@cf prclose pwclose

pprint¶

pprint $value...
    

Pretty-print representations of Elvish values. Examples:

~> pprint [foo bar]
[
foo
bar
]
~> pprint [&k1=v1 &k2=v2]
[
&k2=
v2
&k1=
v1
]
    

The output format is subject to change.

@cf repr

prclose¶

prclose $pipe
    

Close the read end of a pipe.

@cf pwclose pipe

print¶

print &sep=' ' $value...
    

Like echo, just without the newline.

@cf echo

Etymology: Various languages, in particular Perl (https://perldoc.perl.org/functions/print.html) and zsh (http://zsh.sourceforge.net/Doc/Release/Shell-Builtin-Commands.html), whose prints do not print a trailing newline.

printf¶

printf $template $value...
    

Prints values to the byte stream according to a template.

Like print, this command does not add an implicit newline; use an explicit "\n" in the formatting template instead.

See Go’s fmt (https://golang.org/pkg/fmt/#hdr-Printing) package for details about the formatting verbs and the various flags that modify the default behavior, such as padding and justification.

Unlike Go, each formatting verb has a single associated internal type, and accepts any argument that can reasonably be converted to that type:

•

The verbs %s, %q and %v convert the corresponding argument to a string in different ways:

•

The verb %t first convert the corresponding argument to a boolean using bool, and then uses its Go counterpart to format the boolean.

•

The verbs %b, %c, %d, %o, %O, %x, %X and %U first convert the corresponding argument to an integer using an internal algorithm, and use their Go counterparts to format the integer.

•

The verbs %e, %E, %f, %F, %g and %G first convert the corresponding argument to a floating-point number using float64, and then use their Go counterparts to format the number.

The special verb %% prints a literal % and consumes no argument.

Verbs not documented above are not supported.

Examples:

~> printf "%10s %.2f\n" Pi $math:pi


        Pi 3.14
~> printf "%-10s %.2f %s\n" Pi $math:pi $math:pi
Pi         3.14 3.141592653589793
~> printf "%d\n" 0b11100111
231
~> printf "%08b\n" 231
11100111
~> printf "list is: %q\n" [foo bar 'foo bar']
list is: [foo bar 'foo bar']
    

Note: Compared to the POSIX printf command (https://pubs.opengroup.org/onlinepubs/007908799/xcu/printf.html) found in other shells, there are 3 key differences:

•

The behavior of the formatting verbs are based on Go’s fmt (https://golang.org/pkg/fmt/) package instead of the POSIX specification.

•

The number of arguments after the formatting template must match the number of formatting verbs. The POSIX command will repeat the template string to consume excess values; this command does not have that behavior.

•

This command does not interpret escape sequences such as \n; just use double-quoted strings.

@cf print echo pprint repr

put¶

put $value...
    

Takes arbitrary arguments and write them to the structured stdout.

Examples:

~> put a
▶ a
~> put lorem ipsum [a b] { ls }
▶ lorem
▶ ipsum
▶ [a b]
▶ <closure 0xc4202607e0>
    

Etymology: Various languages, in particular C (https://manpages.debian.org/stretch/manpages-dev/puts.3.en.html) and Ruby (https://ruby-doc.org/core-2.2.2/IO.html#method-i-puts) as puts.

pwclose¶

pwclose $pipe
    

Close the write end of a pipe.

@cf prclose pipe

rand¶

rand
    

Output a pseudo-random number in the interval [0, 1). Example:

~> rand
▶ 0.17843564133528436
    

randint¶

randint $low $high
    

Output a pseudo-random integer in the interval [$low, $high). Example:

~> # Emulate dice
randint 1 7
▶ 6
    

range¶

range &step=1 $low? $high
    

Output $low, $low + $step, ..., proceeding as long as smaller than $high. If not given, $low defaults to 0.

Examples:

~> range 4
▶ 0
▶ 1
▶ 2
▶ 3
~> range 1 6 &step=2
▶ 1
▶ 3
▶ 5
    

Beware floating point oddities:

~> range 0 0.8 &step=.1
▶ 0
▶ 0.1
▶ 0.2
▶ 0.30000000000000004
▶ 0.4
▶ 0.5
▶ 0.6
▶ 0.7
▶ 0.7999999999999999
    

Etymology: Python (https://docs.python.org/3/library/functions.html#func-range).

read-line¶

read-line
    

Reads a single line from byte input, and writes the line to the value output, stripping the line ending. A line can end with "\r\n", "\n", or end of file. Examples:

~> print line | read-line
▶ line
~> print "line\n" | read-line
▶ line
~> print "line\r\n" | read-line
▶ line
~> print "line-with-extra-cr\r\r\n" | read-line
▶ "line-with-extra-cr\r"
    

read-upto¶

read-upto $delim
    

Reads byte input until $delim or end-of-file is encountered, and outputs the part of the input read as a string value. The output contains the trailing $delim, unless read-upto terminated at end-of-file.

The $delim argument must be a single rune in the ASCII range.

Examples:

~> echo "a,b,c" | read-upto ","
▶ 'a,'
~> echo "foo\nbar" | read-upto "\n"
▶ "foo\n"
~> echo "a.elv\x00b.elv" | read-upto "\x00"
▶ "a.elv\x00"
~> print "foobar" | read-upto "\n"
▶ foobar
    

repeat¶

repeat $n $value
    

Output $value for $n times. Example:

~> repeat 0 lorem
~> repeat 4 NAN
▶ NAN
▶ NAN
▶ NAN
▶ NAN
    

Etymology: Clojure (https://clojuredocs.org/clojure.core/repeat).

repr¶

repr $value...
    

Writes representation of $values, separated by space and followed by a newline. Example:

~> repr [foo 'lorem ipsum'] "aha\n"
[foo 'lorem ipsum'] "aha\n"
    

@cf pprint

Etymology: Python (https://docs.python.org/3/library/functions.html#repr).

resolve¶

resolve $command
    

Output what $command resolves to in symbolic form. Command resolution is described in the language reference.

Example:

~> resolve echo
▶ <builtin echo>
~> fn f { }
~> resolve f
▶ <closure 0xc4201c24d0>
~> resolve cat
▶ <external cat>
    

return¶

Raises the special “return” exception. When raised inside a named function (defined by the fn keyword) it is captured by the function and causes the function to terminate. It is not captured by an anonymous function (aka lambda).

Because return raises an exception it can be caught by a try block. If not caught, either implicitly by a named function or explicitly, it causes a failure like any other uncaught exception.

See the discussion about flow commands and exceptions

Note: If you want to shadow the builtin return function with a local wrapper, do not define it with fn as fn swallows the special exception raised by return. Consider this example:

~> fn return { put return; builtin:return }
~> fn test-return { put before; return; put after }
~> test-return
▶ before
▶ return
▶ after
    

Instead, shadow the function by directly assigning to local:return~:

~> local:return~ = { put return; builtin:return }
~> fn test-return { put before; return; put after }
~> test-return
▶ before
▶ return
    

run-parallel¶

run-parallel $callable ...
    

Run several callables in parallel, and wait for all of them to finish.

If one or more callables throw exceptions, the other callables continue running, and a composite exception is thrown when all callables finish execution.

The behavior of run-parallel is consistent with the behavior of pipelines, except that it does not perform any redirections.

Here is an example that lets you pipe the stdout and stderr of a command to two different commands:

pout = (pipe)
perr = (pipe)
run-parallel {
foo > $pout 2> $perr
pwclose $pout
pwclose $perr
} {
bar < $pout
prclose $pout
} {
bar2 < $perr
prclose $perr
}
    

This command is intended for doing a fixed number of heterogeneous things in parallel. If you need homogeneous parallel processing of possibly unbound data, use peach instead.

@cf peach

search-external¶

search-external $command
    

Output the full path of the external $command. Throws an exception when not found. Example (your output might vary):

~> search-external cat
▶ /bin/cat
    

@cf external has-external

set-env¶

set-env $name $value
    

Sets an environment variable to the given value. Example:

~> set-env X foobar
~> put $E:X
▶ foobar
    

@cf get-env has-env unset-env

show¶

show $e
    

Shows the value to the output, which is assumed to be a VT-100-compatible terminal.

Currently, the only type of value that can be showed is exceptions, but this will likely expand in future.

Example:

~> e = ?(fail lorem-ipsum)
~> show $e
Exception: lorem-ipsum
[tty 3], line 1: e = ?(fail lorem-ipsum)
    

sleep¶

sleep $duration
    

Pauses for at least the specified duration. The actual pause duration depends on the system.

This only affects the current Elvish context. It does not affect any other contexts that might be executing in parallel as a consequence of a command such as peach.

A duration can be a simple number (with optional fractional value) without an explicit unit suffix, with an implicit unit of seconds.

A duration can also be a string written as a sequence of decimal numbers, each with optional fraction, plus a unit suffix. For example, “300ms”, “1.5h” or “1h45m7s”. Valid time units are “ns”, “us” (or “µs”), “ms”, “s”, “m”, “h”.

Passing a negative duration causes an exception; this is different from the typical BSD or GNU sleep command that silently exits with a success status without pausing when given a negative duration.

See the Go documentation (https://golang.org/pkg/time/#ParseDuration) for more information about how durations are parsed.

Examples:

~> sleep 0.1    # sleeps 0.1 seconds
~> sleep 100ms  # sleeps 0.1 seconds
~> sleep 1.5m   # sleeps 1.5 minutes
~> sleep 1m30s  # sleeps 1.5 minutes
~> sleep -1
Exception: sleep duration must be >= zero
[tty 8], line 1: sleep -1
    

slurp¶

slurp
    

Reads bytes input into a single string, and put this string on structured stdout.

Example:

~> echo "a\nb" | slurp
▶ "a\nb\n"
    

Etymology: Perl, as File::Slurp (http://search.cpan.org/~uri/File-Slurp-9999.19/lib/File/Slurp.pm).

-source¶

-source $filename
    

Equivalent to eval (slurp <$filename). Deprecated.

src¶

src
    

Output a map-like value describing the current source being evaluated. The value contains the following fields:

•

name, a unique name of the current source. If the source originates from a file, it is the full path of the file.

•

code, the full body of the current source.

•

is-file, whether the source originates from a file.

Examples:

~> put (src)[name code is-file]
▶ '[tty]'
▶ 'put (src)[name code is-file]'
▶ $false
~> echo 'put (src)[name code is-file]' > show-src.elv
~> elvish show-src.elv
▶ /home/elf/show-src.elv
▶ "put (src)[name code is-file]\n"
▶ $true
Note: this builtin always returns information of the source of the function
calling `src`. Consider the following example:
```elvish-transcript
~> echo 'fn show { put (src)[name] }' > ~/.elvish/lib/src-fsutil.elv
~> use src-util
~> src-util:show
▶ /home/elf/.elvish/lib/src-fsutil.elv
    

-stack¶

-stack
    

Print a stack trace.

This is only useful for debug purposes.

styled¶

styled $object $style-transformer...
    

Construct a styled text by applying the supplied transformers to the supplied object. $object can be either a string, a styled segment (see below), a styled text or an arbitrary concatenation of them. A $style-transformer is either:

•

The name of a builtin style transformer, which may be one of the following:

•

A color name for setting the text color, which may be one of the following:

•

A color name prefixed by bg- to set the background color.

•

A color name prefixed by fg- to set the foreground color. This has the same effect as specifying the color name without the fg- prefix.

•

A lambda that receives a styled segment as the only argument and returns a single styled segment.

•

A function with the same properties as the lambda (provided via the $transformer~ syntax).

When a styled text is converted to a string the corresponding ANSI SGR code (https://en.wikipedia.org/wiki/ANSI_escape_code#SGR_.28Select_Graphic_Rendition.29_parameters) is built to render the style.

A styled text is nothing more than a wrapper around a list of styled segments. They can be accessed by indexing into it.

s = (styled abc red)(styled def green)
put $s[0] $s[1]
    

styled-segment¶

styled-segment $object &fg-color=default &bg-color=default &bold=$false &dim=$false &italic=$false &underlined=$false &blink=$false &inverse=$false
    

Constructs a styled segment and is a helper function for styled transformers. $object can be a plain string, a styled segment or a concatenation thereof. Probably the only reason to use it is to build custom style transformers:

fn my-awesome-style-transformer [seg]{ styled-segment $seg &bold=(not $seg[dim]) &dim=(not $seg[italic]) &italic=$seg[bold] }
styled abc $my-awesome-style-transformer~
    

As just seen the properties of styled segments can be inspected by indexing into it. Valid indices are the same as the options to styled-segment plus text.

s = (styled-segment abc &bold)
put $s[text]
put $s[fg-color]
put $s[bold]
    

take¶

take $n $input-list?
    

Retain the first $n input elements. If $n is larger than the number of input elements, the entire input is retained. Examples:

~> take 3 [a b c d e]
▶ a
▶ b
▶ c
~> use str
~> str:split ' ' 'how are you?' | take 1
▶ how
~> range 2 | take 10
▶ 0
▶ 1
    

Etymology: Haskell.

tilde-abbr¶

tilde-abbr $path
    

If $path represents a path under the home directory, replace the home directory with ~. Examples:

~> echo $E:HOME
/Users/foo
~> tilde-abbr /Users/foo
▶ '~'
~> tilde-abbr /Users/foobar
▶ /Users/foobar
~> tilde-abbr /Users/foo/a/b
▶ '~/a/b'
    

time¶

time &on-end=$nil $callable
    

Runs the callable, and call $on-end with the duration it took, as a number in seconds. If $on-end is $nil (the default), prints the duration in human-readable form.

If $callable throws an exception, the exception is propagated after the on-end or default printing is done.

If $on-end throws an exception, it is propagated, unless $callable has already thrown an exception.

Example:

~> time { sleep 1 }
1.006060647s
~> time { sleep 0.01 }
1.288977ms
~> t = ''
~> time &on-end=[x]{ t = $x } { sleep 1 }
~> put $t
▶ (float64 1.000925004)
~> time &on-end=[x]{ t = $x } { sleep 0.01 }
~> put $t
▶ (float64 0.011030208)
    

to-json¶

to-json
    

Takes structured stdin, convert it to JSON and puts the result on bytes stdout.

~> put a | to-json
"a"
~> put [lorem ipsum] | to-json
["lorem","ipsum"]
~> put [&lorem=ipsum] | to-json
{"lorem":"ipsum"}
    

@cf from-json

to-lines¶

to-lines $input?
    

Writes each value input to a separate line in the byte output. Byte input is ignored.

~> put a b | to-lines
a
b
~> to-lines [a b]
a
b
~> { put a; echo b } | to-lines
b
a
    

@cf from-lines

to-string¶

to-string $value...
    

Convert arguments to string values.

~> to-string foo [a] [&k=v]
▶ foo
▶ '[a]'
▶ '[&k=v]'
    

unset-env¶

unset-env $name
    

Unset an environment variable. Example:

~> E:X = foo
~> unset-env X
~> has-env X
▶ $false
~> put $E:X
▶ ''
    

@cf has-env get-env set-env

use-mod¶

use-mod $use-spec
    

Imports a module, and outputs the namespace for the module.

Most code should use the use special command instead.

Examples:

~> echo 'x = value' > a.elv
~> put (use-mod ./a)[x]
▶ value
    

wcswidth¶

wcswidth $string
    

Output the width of $string when displayed on the terminal. Examples:

~> wcswidth a
▶ 1
~> wcswidth lorem
▶ 5
~> wcswidth 你好，世界
▶ 10