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.
Write a file as badly laid out as you can, keeping it correct, and run
zeno formaton it.Run
zeno tokenson a line with a string, a number with a unit and a comment. Which of them are tokens?Run
zeno parseona or b and c, and onnot a == b. What does each tree say about which goes first?Set up your editor, make a mistake, and watch it underlined.