The Zeno Book Zeno 0.1 zeno-lang.org

26 The Tools

Everything Zeno does is done by one program, zeno, with a word after it that says what to do. This chapter goes through the words a program’s author uses every day, then the ones that show what the compiler sees, and then setting up an editor.

26.1 The commands

Command Does
zeno run file check a program, then run it
zeno check file check it for mistakes, without running it
zeno test [file or folder] run its tests (Testing)
zeno build file compile it to a program of its own (Compiling)
zeno format file lay it out the way Zeno lays programs out
zeno new name make a folder with a new program (Packages)
zeno fetch get the packages a program needs
zeno lsp the language server, which an editor starts
zeno tokens, parse, join, bytecode show what the compiler sees
zeno --version, zeno --help the version, and a list of all this

Appendix E lists every command and option.

26.2 run and check

zeno run reads the whole program, checks it, and runs it only if the check found nothing. zeno check does the first half and stops, which is quick and is what an editor or a build script wants. Both report every mistake they can be sure of, not only the first, and end with how many there were:

two.zeno

let speed = "fast" * 2
print(sped)
$ zeno check two.zeno
error: `*` does not work between str and int
 --> two.zeno:1:13
  |
1 | let speed = "fast" * 2
  |             ^

error: `sped` is not defined
 --> two.zeno:2:7
  |
2 | print(sped)
  |       ^

2 errors found. Nothing was run.

A mistake found before the program starts costs seconds. The same mistake found halfway through a run, with a motor already turning, costs more. The checker reports only what it is sure of, so untyped code is not held back. (Decision 4.4.)

Options that change how a program is checked or run go before the file. Words after the file are the program’s own (Reading and Writing):

Option Means
--strict every type must be known (Types)
--vm with run: compile to bytecode and run that, faster
--no-collector with check: check as a build with no collector would (Building with No Collector)

26.3 format

zeno format lays a file out the one way Zeno lays programs out. There is nothing to configure. Here is a file before:

queue.zeno

class  Queue{

  size:int      # how many fit


  function put(self,byte:u8)->bool{
    if self.size==0{return false}
  return true
 }
}

and after:

$ zeno format queue.zeno
Formatted queue.zeno
$ cat queue.zeno
class Queue {
    size: int      # how many fit

    function put(self, byte: u8) -> bool {
        if self.size == 0 { return false }
        return true
    }
}

The rules are few. Four spaces for each open bracket. One space around operators, = and ->, and after , and :. None inside brackets, nor before the bracket of a call or a type. Never two blank lines in a row, and none at the top or bottom of a block. A comment after code keeps the distance its author gave it.

And three things it never does. It never changes a token: 0x4000_4400 stays spelled so. It never moves a line break: a short case on one line stays on one line, and a call broken over three lines stays on three. And it never formats a file with a mistake in it; it shows the mistake instead.

zeno format folder lays out every .zeno file in the folder, and zeno format --check folder changes nothing and says which files are not laid out, for a build server.

When a language has one layout, nobody argues about layout, and every program in it looks familiar to every reader. Go’s gofmt showed that this is worth more than any one person’s taste. Because the formatter only decides spaces and indents between tokens it leaves alone, it cannot change what a program means. (Decisions 9.1 to 9.9.)

26.4 Seeing what the compiler sees

Four commands show a program at each stage of the compiler. They are for curiosity and for learning how a compiler works, which Inside Zeno is about.

zeno tokens shows the words the lexer cut the file into:

tiny.zeno

let total = 2 + 3 * 4
print(total)
$ zeno tokens tiny.zeno
   1:1   Let
   1:5   Ident("total")
   1:11  Assign
   1:13  Int(2)
   1:15  Plus
   1:17  Int(3)
   1:19  Star
   1:21  Int(4)
   1:22  Newline
   2:1   Ident("print")
   2:6   LParen
   2:7   Ident("total")
   2:12  RParen
   2:13  Newline
   3:1   Eof

zeno parse shows the tree the parser built from them, where 3 * 4 already sits below the +:

tiny.zeno

let total = 2 + 3 * 4
print(total)
$ zeno parse tiny.zeno
let total = (2 + (3 * 4))
print(total)

zeno join shows the one program that a file and the files it imports are joined into (Programs in Several Files), and zeno bytecode the instructions that zeno run --vm runs:

tiny.zeno

let total = 2 + 3 * 4
print(total)
$ zeno bytecode tiny.zeno
== main() ==
0000    1  Const        0          ; 2
0001    |  Const        1          ; 3
0002    |  Const        2          ; 4
0003    |  Binary       *
0004    |  Binary       +
0005    2  Const        3          ; <function print>
0006    |  GetLocal     0          ; total
0007    |  Call         1
0008    |  Pop          1
0009    |  Const        4          ; none
0010    |  Return

26.5 Your editor

zeno lsp is a language server: a program that an editor starts and talks to in a fixed way, the Language Server Protocol. With it, the editor underlines mistakes as you type, lays the file out when you save, jumps to where a name was declared, and shows a name’s type when you rest on it. What it underlines is exactly what zeno check would print, because it runs the same checker. VS Code, Neovim, Helix, Zed and Emacs all speak the protocol.

The editors folder of the Zeno repository has what each editor needs: an extension for VS Code with colours and the few lines that start zeno lsp, and a syntax file for Vim and Neovim. editors/README.md has the steps for each. For Neovim, the heart of it is:

vim.lsp.start({
  name = "zeno",
  cmd = { "zeno", "lsp" },
  root_dir = vim.fn.getcwd(),
})

and for Helix, in ~/.config/helix/languages.toml:

[language-server.zeno]
command = "zeno"
args = ["lsp"]

[[language]]
name = "zeno"
scope = "source.zeno"
file-types = ["zeno"]
language-servers = ["zeno"]

For every editor, zeno must be somewhere the editor finds it, on the PATH (Getting Zeno).

zeno run checks and runs, zeno check only checks, and both report every mistake they are sure of. zeno format lays a file out the one way, changing only spaces. tokens, parse, join and bytecode show the compiler’s view. zeno lsp brings the checker and the formatter into any editor that speaks the Language Server Protocol.

  1. Write a file as badly laid out as you can, keeping it correct, and run zeno format on it.

  2. Run zeno tokens on a line with a string, a number with a unit and a comment. Which of them are tokens?

  3. Run zeno parse on a or b and c, and on not a == b. What does each tree say about which goes first?

  4. Set up your editor, make a mistake, and watch it underlined.