Table of content

Work in progress.

This tutorial introduces the fundamentals of shell programming with Elvish. Familiarity with other shells or programming languages is useful but not required.

1. Commands and strings

Let’s begin with the traditional “hello world” program:

~> echo Hello, world!
Hello, world!

Here, we call the echo command with two arguments: Hello, and world!. The echo command prints them both, inserting a space in between and adding a newline at the end, and voilà, we get back the message Hello, world!.

1.1. Quoting the argument

We used a single space between the two arguments. Using more also works:

~> echo Hello,  world!
Hello, world!

The output still only has one space, because echo didn’t know how many spaces were used to separate the two arguments; all it sees is the two arguments, Hello, and world!. However, you can preserve the two spaces by quoting the entire text:

~> echo "Hello,  world!"
Hello,  world!

In this version, echo only sees one argument containing Hello,  world (with two spaces). A pair of double quotes tells Elvish that the text inside it is a single argument; the quotes themselves are not part of the argument.

On contrary, the Hello, and world! arguments are implicitly delimited by spaces (instead of explicitly by quotes); as such, they are known as barewords. Some special characters also delimit barewords, which we will see later. Barewords are useful to write command names, filenames and command-line switches, which usually do not contain spaces or special characters.

1.2. Editing the command line


1.3. Builtin and external commands

We demonstrated the basic command structure using echo, a very simple command. The same structure applies to all the commands. For instance, Elvish comes with a randint command that takes two arguments a and b and generates a random integer in the range a…b-1. You can use the command as a digital dice:

~> randint 1 7
▶ 3

Arithmetic operations are also commands. Like other commands, the command names comes first, making the syntax a bit different from common mathematical notations:

~> + 17 28 # addition
▶ (num 45)
~> * 17 28 # multiplication
▶ (num 476)

The commands above all come with Elvish; they are builtin commands. There are many more of them.

Some builtin commands are in importabled modules. For example, the command to compute exponention lives in the math: module:

~> use math
~> math:pow 2 10
▶ (num 1024)

Another kind of commands is external commands. They are separate programs from Elvish, and either come with the operating system or are installed by you manually. Chances are you have already used some of them, like ls for listing files, or cat for showing files.

There are really a myriad of external commands; to start with, you can manage code repositories with git, convert documents with pandoc, process images with ImageImagick, transcode videos with ffmpeg, test the security of websites with nmap and analyze network traffic with tcpdump. Many free and open-source software come with a command-line interface.

Here we show you how to obtain the latest version of Elvish entirely from the command line: we use curl to download the binary and its checksum, shasum to check the checksum, and chmod to make it executable (assuming that you are running macOS on x86-64):

~> curl -s -o elvish
~> curl -s
8b3db8cf5a614d24bf3f2ecf907af6618c6f4e57b1752e5f0e2cf4ec02bface0  elvish-HEAD
~> shasum -a 256 elvish
8b3db8cf5a614d24bf3f2ecf907af6618c6f4e57b1752e5f0e2cf4ec02bface0  elvish
~> chmod +x elvish
~> ./elvish

1.4. History and scripting

Some commands are useful to rerun; for instance, you may want to roll the digital dice several times in a roll, or for another occasion. Of course, you can just retype the command:

~> randint 1 7
▶ 1

The command is short, but still, it can become a chore if you want to run it repeatedly. Fortunately, Elvish remembers all the commands you have typed; you can just ask Elvish to recall it by pressing Up:

~> randint 1 7
▶ (num 6)
~> randint 1 7 elf@host

This will give you the last command you have run. However, it may have been a while when you have last run the randint command, and this will not give you what you need. You can either continue pressing Up until you find the command, or you can give Elvish a hint by typing some characters from the command line you want, e.g. ra, before pressing Up:

~> randint 1 7
▶ (num 5)
~> # more commands ...
~> randint 1 7 elf@host

Another way to rerun commands is saving them in a script, which is simply a text file containing the commands you want to run. Using your favorite text editor, save the command to dice.elv under your home directory:

# dice.elv
randint 1 7

After saving the script, you can run it with:

~> elvish dice.elv
▶ 4

Since the above command runs elvish explicitly, it works in other shells as well, not just from Elvish itself.

2. Variables and lists

To change what a command does, we now need to change the commands themselves. For instance, instead of saying “Hello, world!”, we might want our command to say “Hello, John!”:

~> echo Hello, John!
Hello, John!

Which works until you want a different message. One way to solve this is using variables:

~> var name = John
~> echo Hello, $name!
Hello, John!

The command echo Hello, $name! uses the $name variable you just assigned in the previous command. To greet a different person, you can just change the value of the variable, and the command doesn’t need to change:

~> var name = Jane
~> echo Hello, $name!
Hello, Jane!

Using variables has another advantage: after defining a variable, you can use it as many times as you want:

~> var name = Jane
~> echo Hello, $name!
Hello, Jane!
~> echo Bye, $name!
Bye, Jane!

Now, if you change the value of $name, the output of both commands will change.

2.1. Environment variables

In the examples above, we have assigned value of $name ourselves. We can also make the $name variable automatically take the name of the current user, which is usually kept in an environment variable called USER. In Elvish, environment variables are used like other variables, except that they have an E: at the front of the name:

~> echo Hello, $E:USER!
Hello, elf!
~> echo Bye, $E:USER!
Bye, elf!

The outputs will likely differ on your machine.

2.2. Lists and indexing

The values we have stored in variables so far are all strings. It is possible to store a list of values in one variable; a list can be written by surrounding some values with [ and ]. For example:

~> var list = [linux bsd macos windows]
~> echo $list
[linux bsd macos windows]

Each element of this list has an index, starting from 0. In the list above, the index of linux is 0, that of bsd is 1, and so on. We can retrieve an element by writing its index after the list, also surrounded by [ and ]:

~> echo $list[0] is at index 0
linux is at index 0

We can even do:

~> echo [linux bsd macos windows][0] is at index 0
linux is at index 0

Note that in this example, the two pairs of [] have different meanings: the first pair denotes lists, while the second pair denotes an indexing operation.

2.3. Script arguments

Recall the dice.elv script above:

# dice.elv
randint 1 7

And how we ran it:

~> elvish dice.elv
▶ 4

We were using elvish itself as a command, with the sole argument dice.elv. We can also supply additional arguments:

~> elvish dice.elv a b c
▶ 4

But this hasn’t made any difference, because well, our dice.elv script doesn’t make use of the arguments.

The arguments are kept in a $args variable, as a list. Let’s try put this into a show-args.elv file in your home directory:

echo $args

And we can run it:

~> elvish show-args.elv
~> elvish show-args.elv foo
~> elvish show-args.elv foo bar
[foo bar]

Since $args is a list, we can retrieve the individual elements with $args[0], $args[1], etc.. Let’s rewrite our greet-and-bye script, taking the name as an argument. Put this in greet-and-bye.elv:

var name = $args[0]
echo Hello, $name!
echo Bye, $name!

We can run it like this:

~> elvish greet-and-bye.elv Jane
Hello, Jane!
Bye, Jane!
~> elvish greet-and-bye.elv John
Hello, John!
Bye, John!

3. Output capture and multiple values

Environment variables are not the only way to learn about a computer system; we can also gain more information by invoking commands. The uname command tells you which operation system the computer is running; for instance, if you are running Linux, it prints Linux (unsurprisingly):

~> uname

(If you are running macOS, uname will print Darwin, the open-source core of macOS.)

Let’s try to integrate this information into our “hello” message. The Elvish command-line allows us to run multiple commands in a batch, as long as they are separated by semicolons. We can build the message by running multiple commands, using uname for the OS part:

~> echo Hello, $E:USER, ; uname ; echo user!
Hello, xiaq,

This has the undesirable effect that “Linux” appears on its own line. Instead of running this command directly, we can first capture its output in a variable:

~> var os = (uname)
~> echo Hello, $E:USER, $os user!
Hello, elf, Linux user!

You can also use the output capture construct directly as an argument to echo, without storing the result in a variable first:

~> echo Hello, $E:USER, (uname) user!
Hello, elf, Linux user!

3.1. More arithmetic

You can use output captures to construct do complex arithmetic involving more than one operation:

~> # compute the answer to life, universe and everything
   * (+ 3 4) (- 100 94)
▶ 42