The Zuri Programming Language

by the Zuri Project

Zuri is a language for building whole applications, and it ships with everything that takes. The runtime, the web server, the templating engine, the data formats, the cryptography and the toolchain were designed together and are delivered as one binary, so starting a real program does not begin with assembling an ecosystem out of third-party parts. Zuri has first-class language-level support for package management and vendoring, so the code you bring in from outside needs no third-party tooling either.

The standard library ships with the language, and it is large. Templating, HTTP/1.1 and HTTP/2, WebSockets, TLS, JSON, YAML, CSV, compression, cryptography, image decoding and drawing, HTML parsing, date arithmetic with the IANA time zone database, and OS-thread concurrency are all part of the installation. Every one of them is reachable with a bare import.

The tools ship in the same binary. zuri fmt lays out your code, zuri test runs your tests, and zuri lsp gives every editor completion, navigation and diagnostics. zuri install and zuri publish manage packages against Nyssa, a package registry any installation can serve, and zuri bundle ships a finished program to machines where Zuri is not installed, as a single executable if you like.

Zuri is dynamically typed, and it declines to be vague. A declared parameter type is enforced at the call, classes are sealed, a function cannot be quietly redefined, and a name beginning with an underscore stays inside the module that declared it. Your code runs as bytecode until a piece of it gets hot, and a JIT compiles that piece to machine code while the program is still running.

This book teaches the language from the first line of code to a complete web application. It is written against the Rust implementation of Zuri. Every program printed in these pages was run against that implementation, and the output shown underneath each one is the output it produced.

Introduction

Welcome. Open a terminal, keep it next to this page, and let’s begin.

This book teaches Zuri. It starts with installing the language and printing a line of text, and it ends with a task-board web application that stores data on disk, renders HTML from templates, serves a JSON API, and runs behind a stack of middleware. Everything in between is the road from one to the other.

What Zuri Looks Like

Here is a complete program. You do not need to understand all of it yet; read it the way you would read a paragraph in a language you are learning, and see how much comes through.

class Account {

  @new(owner: string, balance: number) {
    self.owner = owner
    self.balance = balance
  }

  deposit(amount: number) {
    if amount <= 0 {
      raise ValueError('deposit must be positive')
    }

    self.balance += amount
    return self.balance
  }

  to_string() {
    return '${self.owner}: ${self.balance}'
  }
}

var accounts = [
  Account('ada', 100),
  Account('grace', 250),
]

for account in accounts {
  account.deposit(50)
  echo account.to_string()
}

ada: 150
grace: 300

Most of that will be familiar if you have written code before. The pieces worth pointing at now, because they come up on the very first page of Chapter 3:

• var declares a variable, and class declares a class.
• A constructor is called @new. Methods whose names begin with @ hook into the language’s own syntax, and Chapter 6 covers the full set.
• self refers to the instance, and reading a field always goes through it: self.balance, never a bare balance.
• '${...}' interpolates an expression into a string.
• echo prints a value and a newline.
• raise signals an error; Chapter 7 shows how to catch one.
• Every block is written with braces, and every control-flow statement requires one.

What Comes With Zuri

Installing Zuri installs its whole toolchain with it. Every tool is a subcommand of zuri, and every one has its place in this book:

A project adds commands of its own the same way, and so can a package; Appendix I shows how.

Who This Book Is For

Chapters 1 through 6 assume you can open a terminal and nothing else. If this is your first programming language, start at the beginning and go slowly. Every idea is introduced before it is used, and every example is short enough to type out.

If you already write Python, JavaScript, Ruby, Go or Java, you can move through Chapters 3 to 5 quickly. Read Appendix H first: it lists the places where Zuri does something different from what the same syntax does in the language you already know, which is where the hours get lost.

How This Book Is Organised

Getting started, Chapters 1 and 2. Install the language, run something, start a project and format it, then build a small command-line application end to end so you have seen the shape of a real program before we take one apart.

The language, Chapters 3 to 8. Variables, types, operators, control flow, strings, numbers, collections, functions, closures, type annotations, classes, inheritance, decorated methods, errors and modules. Read these in order.

The world outside your program, Chapters 9 to 13. Files, binary data and byte streams, isolates and concurrency, sockets and networking, and a tour of the standard library.

The large modules, Chapters 14 to 20. Wire for templating, HTTP for clients and servers, Imagine for images, SQL for databases, Mail for the three protocols that move messages, env for the configuration all of them read, and args for the command line they are started from. Each is big enough to need a chapter of its own, and each is a reference you will come back to.

Depth, Chapters 21 to 24. Reflection and the compiler API, how Zuri executes your code and how to make it faster, how to test it, and how to debug a program that is doing something you did not expect.

The capstone, Chapter 25. One application, built in seven steps, using almost everything the book has covered.

Interoperability, Chapter 26. Calling C and Rust libraries, and being called back by them.

Sharing and shipping, Chapter 27. Installing and publishing packages, the lockfile, packaging a program to run where Zuri is not installed, and running Nyssa, the package repository, for a team or the public.

Talking to other programs, Chapter 28. JSON-RPC, for calling methods on another program and answering its calls over any connection.

Tooling, Chapter 29. The language server, and setting up your editor to use it.

Appendices. Keywords, operators and precedence, decorated methods, built-in functions, every method on every built-in type, the standard library index, the error hierarchy, the notes for readers arriving from another language, and writing commands of your own. These are reference material; the rest of the book is prose.

How to Read It

Read it with the interpreter running. Zuri has a REPL, every short example in this book can be pasted straight into it, and the fastest way to understand a rule is to break it on purpose and read the error.

Chapters build on each other. When a chapter needs something from later in the book, it says so and links to it, and you can carry on without following the link. When a chapter introduces something you will need again, it says that too.

Conventions

Commands you type in a shell appear with a $ prompt, and the output follows underneath:

$ zuri run main.zu
Hello, world!

Code that belongs in a file appears with the filename above it when the filename matters:

Filename: main.zu

echo 'Hello, world!'

Sessions in the interactive prompt use %> for the first line of an input and .. for its continuations, which is exactly what the REPL itself prints:

%> var name = 'zuri'
%> name.upper()
'ZURI'

Where a rule has an exception, the exception is stated in the same paragraph as the rule. Where a limit exists, it is stated as a limit. Nothing in this book is a guess about how the language behaves; every claim was checked by running it.

Let’s get started.

Getting Started

Three things before the language itself: putting Zuri on your machine, running a file, and using the interactive prompt.

The prompt matters more than it sounds. Zuri prints the value of any expression you type at it, which makes it the fastest way to answer “what does this actually return?” — and that question comes up constantly in the next five chapters.

Installation

Zuri installs with one command, which downloads the release for your machine, checks it, and puts zuri on your PATH. Releases cover:

• Linux on x86-64 and ARM (x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu)
• macOS on Intel and Apple silicon (x86_64-apple-darwin, aarch64-apple-darwin)
• Windows on x86-64 (x86_64-pc-windows-msvc)

Zuri also builds from source with Cargo, which the end of this page covers.

Linux and macOS

$ curl -fsSL https://zuri-lang.github.io/zuri/install.sh | sh
Downloading zuri 0.1.0 for x86_64-unknown-linux-gnu
Installed zuri 0.1.0 in /home/ada/.zuri/runtime
Added /home/ada/.zuri/bin to PATH in /home/ada/.bashrc

Open a new terminal, or run this one to use zuri straight away:

  export PATH="$HOME/.zuri/bin:$PATH"

Get started with:

  zuri --help

The installer downloads the archive for your machine and checks it against the checksum published beside it. It then runs the new zuri once to confirm the version it reports, and only after that moves it into ~/.zuri/runtime, so a failed or tampered download never replaces a working installation. zuri is linked into ~/.zuri/bin, the same directory that globally installed tools put their launchers in, and that one directory goes on your PATH through your shell’s startup file: .zshrc for zsh, .bashrc for bash (.bash_profile on macOS), config.fish for fish, and .profile for anything else.

Options go after sh -s --:

$ curl -fsSL https://zuri-lang.github.io/zuri/install.sh | sh -s -- --version 0.2.0

Windows

In PowerShell:

> powershell -c "irm https://zuri-lang.github.io/zuri/install.ps1 | iex"

The Windows installer makes the same checks and installs into %USERPROFILE%\.zuri\runtime. That directory goes on your user PATH, and so does %USERPROFILE%\.zuri\bin, where globally installed tools put their launchers. A terminal opened afterwards has both; the one the installer ran in has them already.

The same options are parameters, given by running the installer as a script block:

> & ([scriptblock]::Create((irm https://zuri-lang.github.io/zuri/install.ps1))) -Version 0.2.0

-Version, -Prerelease and -NoModifyPath match the options above.

Checking the Install

$ zuri
Zuri 0.1.0 (running on ZuriVM 0.1.0), REPL/Interactive mode = ON
Build No. => 2026-09-10 23:19:10 UTC
Type ".exit" to quit, ".help" for help or ".credits" for more information
%>

That %> is the Zuri prompt. Type .exit to leave.

zuri --version reports the same build without opening a session, which is the one to reach for from a script or a CI job, and zuri --help adds everything the runtime can run from here:

$ zuri --version
Zuri 0.1.0 (running on ZuriVM 0.1.0)
Build No. => 2026-09-10 23:19:10 UTC

Where It Goes

Both installers keep everything under ZURI_HOME, which is .zuri in your home directory unless the variable says otherwise:

~/.zuri/
  runtime/        zuri, with libs and cmds beside it
  bin/            the zuri link, and globally installed tools

runtime holds the executable with copies of the libs and cmds directories beside it. That pairing matters: the standard library is written mostly in Zuri itself, and the runtime finds it by looking for a libs directory beside the executable. cmds is the same arrangement for the commands the runtime ships.

Running an installer again installs over the top. zuri upgrade does the same from inside an installation, and Bundles and Upgrades covers it. Removing Zuri is deleting ~/.zuri/runtime and the zuri link in ~/.zuri/bin, along with the line the installer added to your shell’s startup file.

ZURI_RELEASES_URL points both installers, and zuri upgrade, at another listing of releases in the shape GitHub publishes them, such as a mirror. GITHUB_TOKEN, when set, is sent to GitHub’s API, where it raises the rate limit.

Downloading by Hand

Every release on the releases page carries an archive per platform, named zuri-<version>-<target>.tar.gz, or .zip for Windows, with a .sha256 beside it. Check the archive against it, unpack it, and put the zuri it holds on your PATH, keeping the libs and cmds directories beside it.

Building From Source

Building needs Rust’s package manager, Cargo. If you do not have Rust installed, get it from rustup.rs; it takes a minute and installs cargo for you.

$ git clone https://github.com/zuri-lang/zuri
$ cd zuri
$ cargo patch-crates
$ cargo build --release

cargo patch-crates prepares the few dependencies Zuri builds with changes of its own. It runs once per clone, and again only when one of those changes is updated; the build says when that is.

The first build compiles a large set of native dependencies, so it takes a few minutes. Builds after that are incremental and quick.

When it finishes you have an executable at target/release/zuri, and, sitting right next to it, copies of the libs/ and cmds/ directories, in the same arrangement a release has.

Putting a Build on Your PATH

The simplest arrangement is to keep the binary and its two directories together and symlink to the binary:

$ sudo ln -s "$PWD/target/release/zuri" /usr/local/bin/zuri

A symlink is resolved before the runtime looks for libs, so this works. Copying just the binary does not.

If you want them somewhere else entirely, set ZURI_ROOT to the directory that contains them:

$ export ZURI_ROOT=/opt/zuri
$ ls /opt/zuri
cmds  libs

ZURI_ROOT wins over the executable-adjacent lookup, which makes it handy when you are hacking on the standard library itself and want a build to pick up your edits immediately:

$ ZURI_ROOT=$PWD ./target/debug/zuri run myscript.zu

A Debug Build, and Why You Might Want One

Plain cargo build produces target/debug/zuri. It keeps the runtime assertions that the optimised build strips out, which makes it the build to reach for when a program is doing something you did not expect. It runs more slowly in exchange. Either build runs everything in this book.

Hello, World!

Make a directory, put one file in it, and run it.

$ mkdir hello
$ cd hello

Create a file called main.zu. The .zu extension is what the runtime looks for when resolving imports, so get in the habit early.

Filename: main.zu

echo 'Hello, world!'

Run it:

$ zuri run main.zu
Hello, world!

That is the whole program. No main function, no imports, no boilerplate. A Zuri file is a script, and its top level is code that runs.

Anatomy of One Line

echo 'Hello, world!'

echo is a keyword, not a function. You do not write echo(...), you write echo followed by an expression. It prints the value and adds a newline.

Strings are written between single or double quotes, and the two are identical in meaning. Most Zuri code uses single quotes and saves double quotes for strings that contain an apostrophe.

There is no semicolon. Zuri ends a statement at the end of the line. You can write a semicolon if you want two statements on one line, but almost nobody does.

echo and print

There is also a print() function, and the difference is worth learning now because it bites people later.

echo 'first'
echo 'second'

print('third')
print('fourth\n')

first
second
thirdfourth

echo appends a newline; print() does not, and it takes any number of arguments. Use echo for output meant for a human reading a terminal, and print() when you are assembling output character by character.

Running a Directory

run takes a directory as readily as a file. Point it at one and it looks for index.zu inside and runs that:

$ zuri run hello
Hello, world!

If there is no index.zu, you get told so plainly:

$ zuri run hello
(Zuri):
  Launch aborted for hello
  Reason: No entrypoint found in the directory

This is the same rule the module system uses for packages, which we will get to in Chapter 8. A directory with an index.zu is a unit you can run or import.

Leave the path off and run launches the directory you are standing in, which is how a project is usually started:

$ cd hello
$ zuri run
Hello, world!

Everything after the path belongs to the program rather than to zuri, so a script reads its own flags exactly as it would anywhere else:

$ zuri run main.zu --name Ada --verbose

Chapter 20 covers reading them.

Starting a Project

One file is where everybody starts, and it stops being enough about as soon as there are two of them. zuri init writes the layout a project grows into:

$ zuri init myproject

Run in a terminal, it asks what the project is called, what version it starts at and who wrote it, offering an answer to each. Press enter to take what it offers. Run anywhere there is nobody to ask — a script, a CI job — it takes those answers itself, which --yes also says outright.

What it leaves behind:

myproject/
  project.toml          what the project is
  index.zu              the entry point
  app/
    index.zu            the application
  tests/
    app.test.zu         its tests
  README.md
  .gitignore
  .gitattributes

It runs, and its tests pass, before you have written anything:

$ cd myproject
$ zuri run
Hello, world!
$ zuri test

  zuri test  1 file in tests

   PASS   app.test.zu  36ms  2 tests

  1 file
  2 passed  •  2 total

The root index.zu is two things at once:

Filename: index.zu

import @.app { * }

if __root__ == __file__ {
  main()
}

The import re-exports everything app declares, so another project can import myproject and reach all of it. The if starts the application, but only when this file is the one that was run: __root__ is the file zuri was pointed at, and __file__ is the file the line is written in. Importing the project leaves main() alone. That is the Zuri spelling of a main guard, and it is worth knowing early because every runnable package uses it.

app/index.zu is the application itself. Whatever it exports, the project exports:

Filename: app/index.zu

def greet(name: ?string) {
  return 'Hello, ${name or "world"}!'
}

def main() {
  echo greet()
}

project.toml is what the project is, for anything that reads it:

[project]
name = "myproject"
version = "0.1.0"
description = ""
authors = ["Ada Lovelace <ada@example.com>"]
license = "MIT"

[dependencies]

The name comes from the directory, the author from git config, and a git repository is created unless there is already one above. zuri init --help has the rest, and every question it asks has a flag that answers it:

$ zuri init myproject --name web-server --license Apache-2.0 --yes

Run inside a directory that already has files, init adds what is missing and writes over nothing. Run where a project already is, it refuses rather than overwrite one.

Chapter 8 is where packages and re-exports are covered properly, and Chapter 25 grows this layout into a full application.

Formatting

zuri fmt lays out Zuri source in one house style: two spaces to a level, one statement to a line, an explicit block wherever one belongs, spacing the way a reader expects it, and lines past eighty columns broken where the expression holds together least. Line breaks you made yourself are kept, so a list you laid out one entry to a line stays that way.

Here is a file written in a hurry:

Filename: rooms.zu

def area(width,height){return width*height}
var rooms=[ [3,4],[5,6] ]
for room in rooms { echo area(room[0],room[1]) }

$ zuri fmt rooms.zu
formatted rooms.zu
Formatted 1 file.

Filename: rooms.zu

def area(width, height) {
  return width * height
}

var rooms = [[3, 4], [5, 6]]
for room in rooms {
  echo area(room[0], room[1])
}

Given a directory, zuri fmt formats every .zu file beneath it apart from the packages a project has installed, and with no path at all it formats the current directory. It never changes what a program does: before it writes a file, it parses its own result and checks that the program and every comment in it are exactly what it started with, and a file it cannot format that way is left as it was.

--dry-run writes nothing. It names each file that would change, and exits with status 1 when any would, which is the check a commit hook or a CI job wants:

$ zuri fmt --dry-run
would format /home/ada/myproject/app/extra.zu
1 file would change. 3 files were already formatted.

Your editor runs the same formatter through the language server, on a whole file or a selection; Chapter 29 sets that up.

Commands

A first word that is not run names a command instead of a path:

$ zuri greet Ada
Hello, Ada!

A command is a .zu file, or a directory with an index.zu, sitting in a cmds directory. A project keeps its own in .zuri/cmds, so either of these answers to zuri greet:

.zuri/cmds/greet.zu           # a command in one file
.zuri/cmds/greet/index.zu     # a command with room to grow

The directory wins if both are there, so a command that has outgrown one file takes over the name as soon as its index.zu lands. Until then the directory is not a command, and the file goes on answering.

The commands the runtime itself ships live in the cmds directory beside the executable, and those win over a project’s. Everything after the name is forwarded to the command untouched, flags included.

A name that matches nothing is refused rather than guessed at:

$ zuri gret Ada
(Zuri):
  Launch aborted for gret
  Reason: Unknown command

A command says what it is in its own doc block, with two tags. zuri --help lists every command it can reach by exactly those:

Filename: .zuri/cmds/greet.zu

/**
 * @command greet
 * @description Say hello to somebody by name.
 */

import os

echo 'Hello, ${os.args[2]}!'

$ zuri --help
Zuri 0.1.0 (running on ZuriVM 0.1.0)
Build No. => 2026-09-10 23:19:10 UTC

Usage: zuri                    start the interactive REPL
       zuri run [PATH]         run a script, a package, or this directory
       zuri <command> [ARGS]   run a command

OPTIONS:
  -h, --help     Show this help message and exit
  -v, --version  Show version information and exit

COMMANDS:
  format  Lay out Zuri source in the project style.
  init    Scaffold a new Zuri project.
  test    Run a project's test files, each in its own process.

PROJECT COMMANDS:
  greet   Say hello to somebody by name.

Run "zuri <command> --help" for help on a specific command.

A description too long for one line carries on below it, indented:

/**
 * @command deploy
 * @description Ship the current build to staging, then wait for
 *    the health check to come back green.
 */

Two flags sit outside all of this and run nothing. zuri --help is the listing above, and zuri --version reports just the build:

$ zuri --version
Zuri 0.1.0 (running on ZuriVM 0.1.0)
Build No. => 2026-09-10 23:19:10 UTC

Both take the short spelling too, -h and -v.

The REPL

Run zuri with no arguments and you get an interactive prompt:

$ zuri
Zuri 0.1.0 (running on ZuriVM 0.1.0), REPL/Interactive mode = ON
Build No. => 2026-09-10 23:19:10 UTC
Type ".exit" to quit, ".help" for help or ".credits" for more information
%>

REPL stands for read-eval-print loop, and the print is the part that makes it useful. At the top level of the REPL, any expression whose value is not nil is printed for you, so you never need echo just to look at something:

%> 1 + 2
3
%> var name = 'Zuri'
%> name.upper()
ZURI
%> [1, 2, 3].map(@(n) { return n * n })
[1, 4, 9]

Notice that var name = 'Zuri' printed nothing. A declaration is not an expression, and anything that evaluates to nil stays quiet. That single rule is what keeps list.append(4) and echo x from doubling up on your screen.

Auto-printing applies only to the outermost level. Type a loop and the body does not print once per iteration:

%> iter var i = 0; i < 3; i++ {
..   i * 10
.. }
%>

Use echo inside a block when you want to see something.

Multi-line Input

The prompt changes from %> to .. when what you have typed so far is not yet a complete statement. Press Enter at the end of a line with an unclosed brace and keep going:

%> def double(n) {
..   return n * 2
.. }
%> double(21)
42

The same applies to an unclosed bracket, an unclosed parenthesis, or a string that has not been closed. The REPL decides when you are finished; you never have to signal it.

Everything Stays Defined

Variables, functions and classes you declare at the top level of the REPL remain defined for the rest of the session, because the whole session shares one namespace:

%> class Point {
..   @new(x, y) {
..     self.x = x
..     self.y = y
..   }
.. }
%> var p = Point(3, 4)
%> (p.x ** 2 + p.y ** 2).sqrt()
5

Redeclaring a name at the REPL’s top level replaces it rather than raising an error, so you can retype a function until it is right.

Getting Out

Type .exit. That is the only thing that ends the session.

Ctrl+C and Ctrl+D do not exit. Both print an interrupt line and hand the prompt back:

%> <KeyboardInterrupt [CtrlC]>
Type '.exit' to exit the REPL session
%>

Ctrl+C is how you abandon a half-typed line: the line is discarded and you start again on a fresh prompt.

Syntax Highlighting

On a terminal, the REPL colours what you type as you type it. Keywords are highlighted and everything else is left plain, so a misspelled retrun or whiel stands out before you press Enter — it simply does not change colour.

The highlighting understands string literals. A keyword inside quotes is text, not a keyword, and is left uncoloured:

%> var note = 'return it later'

return there stays plain, because it is part of the string.

Alongside it, a greyed-out suggestion appears to the right of the cursor when what you have typed so far matches something earlier in your history. Press the right arrow to accept it.

Both are terminal features. Piping input to zuri or redirecting its output produces plain text, so a session captured to a file has no escape codes in it.

The Other Dot Commands

.help reminds you that Tab offers completions.

.credits opens the project’s licence in a pager. Press q to come back.

Both are completed by Tab, along with every keyword in the language.

History

Up and Down walk through previous lines, and Ctrl+R searches backwards through them. History is written to a history.txt file sitting next to the zuri executable, so it survives between sessions.

What the REPL Is Good At

Each line is compiled and run on its own, which makes the REPL the right tool for a specific kind of question:

• What does this method return? 'a,b,,c'.split(',')
• Is this value truthy? !!(-1)
• What type am I actually holding? typeof(x)
• Does this syntax parse the way I think? Type it and find out.

It is a poor place to write a program, because you cannot go back and edit line four. Once you are past a few lines, put them in a .zu file and run it — which is what the next chapter does.

Programming a Bookmark Keeper

We are going to build something small and real: a command-line bookmark keeper. It asks you for a title and a URL, stores what you give it in a JSON file, and lets you list, search and delete entries later.

By the end of this chapter you will have used variables, functions, lists, dictionaries, loops, branching, string methods, file handling, JSON and error handling. We will not explain any of them thoroughly. That is what Chapters 3 to 8 are for. The goal here is to see a whole program, working, before we take it apart.

Follow along by typing the code rather than copying it. Mistakes are the fastest way to learn what the error messages mean.

Setting Up

$ mkdir bookmarks
$ cd bookmarks

Create main.zu and start with the modules we will need:

Filename: main.zu

import io
import json

var STORE = 'bookmarks.json'

echo 'Bookmark keeper.'

$ zuri run main.zu
Bookmark keeper.

Three things to notice. import brings in a module and binds it to a name you then reach through with a dot. var declares a variable. A .zu file’s top level is just code, running from top to bottom.

Asking a Question

The io module has readline(), which prints a prompt and waits for the user to type a line:

var title = io.readline('Title: ')
echo 'You typed: ' + title

$ zuri run main.zu
Title: Zuri docs
You typed: Zuri docs

The value that comes back includes whatever the user typed, whitespace included, so we almost always follow it with .trim():

var title = io.readline('Title: ').trim()

trim() is a method on strings. Every value in Zuri has methods, numbers, booleans and nil included, and you call them with a dot.

Storing One Bookmark

A bookmark has a title, a URL and some tags. The natural shape for that is a dictionary: a set of keys with values attached.

var bookmark = {
  title: 'Zuri docs',
  url: 'https://zuri.dev',
  tags: ['lang', 'docs'],
}

Square brackets make a list, an ordered sequence. Curly braces make a dictionary. You read a dictionary’s values with a dot, the same way you reach into a module:

echo bookmark.title
echo bookmark.tags

Zuri docs
[lang, docs]

Zuri has a shorthand you will use constantly. When the key you want and the variable holding its value have the same name, write the name once:

var title = 'Zuri docs'
var url = 'https://zuri.dev'

var bookmark = { title, url }

That is exactly the same dictionary as { title: title, url: url }, with half the noise.

Many Bookmarks

One bookmark is a dictionary. Many bookmarks is a list of them:

var bookmarks = []

bookmarks.append({ title: 'Zuri docs', url: 'https://zuri.dev' })
bookmarks.append({ title: 'Cranelift', url: 'https://cranelift.dev' })

echo bookmarks.length()

2

Saving to Disk

The json module turns Zuri values into text and back. file() opens a file; 'w' means open it for writing.

def save(bookmarks) {
  var handle = file(STORE, 'w')
  handle.write(json.encode(bookmarks, false))
  handle.close()
}

def declares a function. The parameter list needs no types (though it can have them; see Chapter 5). The body is a block, and blocks in Zuri always use braces.

That second argument to json.encode() is compact. It defaults to true, which gives you one dense line. Passing false asks for the indented form, which is what you want in a file a human might open:

[
  {
    "title": "Cranelift",
    "url": "https://cranelift.dev",
    "tags": [
      "compilers"
    ]
  }
]

Loading From Disk, Carefully

Reading is where a real program has to start thinking about what can go wrong. The file might not exist yet. It might exist and contain garbage because someone edited it by hand. Neither should stop the program.

def load() {
  var handle = file(STORE)

  if !handle.exists() {
    return []
  }

  catch {
    return json.decode(handle.read())
  } as error {
    echo 'Could not read ${STORE}: ${error.message}'
    return []
  }
}

Two new pieces here.

The first is ${...} inside a string. That is interpolation: the expression between the braces is evaluated and its value spliced into the string. It works in both single- and double-quoted strings.

The second is catch. Zuri does not have try. You write catch { ... } around the code that might fail, and as error { ... } to handle it. If nothing goes wrong, the handler never runs. If something does, error is an object with a message, a type and a stacktrace.

Notice there is no finally. Zuri does not have one. Code after the catch statement runs either way, which covers most of what finally is used for.

Adding a Bookmark

Now we can put the pieces together:

def add(bookmarks) {
  var title = io.readline('Title: ').trim()
  var url = io.readline('URL:   ').trim()

  if title.is_empty() or url.is_empty() {
    echo 'Both a title and a URL are required.'
    return
  }

  var tags = io.readline('Tags (comma separated): ').trim()

  bookmarks.append({
    title,
    url,
    tags: tags.is_empty() ? [] : tags.split(',').map(@(t) { return t.trim() }),
  })

  save(bookmarks)
  echo 'Saved "${title}".'
}

The tags line packs in three ideas.

cond ? a : b is the conditional operator: if cond is truthy the whole expression is a, otherwise b.

split(',') cuts a string into a list at every comma.

map() takes a function and applies it to every element, giving back a new list. @(t) { return t.trim() } is an anonymous function: @ followed by a parameter list and a body. You can also spell it def(t) { ... }; @ is the shorthand and it is what most Zuri code uses for a one-liner.

There is a shorter form still. When the body is a single expression that you want returned, => replaces the braces and the return:

tags.split(',').map(@(t) => t.trim())

That is the same function written three ways. Chapter 5 covers every spelling, and when each one reads best.

Also notice or rather than ||. Zuri spells its logical operators and, or and !.

Printing a Bookmark

def show(bookmark, index) {
  echo '${index + 1}. ${bookmark.title}'
  echo '   ${bookmark.url}'

  if !bookmark.tags.is_empty() {
    echo '   [' + ', '.join(bookmark.tags) + ']'
  }
}

join lives on the string, not on the list, and it reads exactly as it works: take this separator, and stitch that list together with it.

Listing and Searching

def list_all(bookmarks) {
  if bookmarks.is_empty() {
    echo 'Nothing saved yet.'
    return
  }

  bookmarks.each(@(bookmark, index) {
    show(bookmark, index)
  })
}

each() calls your function once per element, handing it the value first and the index second. That order catches people out; it is the same for lists, dictionaries and strings.

Search is a filter plus a test:

def find(bookmarks) {
  var needle = io.readline('Search: ').trim().lower()

  var hits = bookmarks.filter(@(bookmark) {
    if bookmark.title.lower().contains(needle) {
      return true
    }
    return bookmark.tags.some(@(tag) { return tag.lower() == needle })
  })

  if hits.is_empty() {
    echo 'No match for "${needle}".'
    return
  }

  hits.each(@(bookmark, index) {
    show(bookmark, index)
  })
}

filter() keeps the elements your function returns true for. some() answers “is this true of at least one element?” and stops at the first one that matches.

Removing a Bookmark

def remove(bookmarks) {
  list_all(bookmarks)

  if bookmarks.is_empty() {
    return
  }

  var answer = io.readline('Remove which number? ').trim()
  var position = answer.to_number() - 1

  if position < 0 or position >= bookmarks.length() {
    echo 'There is no bookmark ${answer}.'
    return
  }

  var gone = bookmarks[position]
  bookmarks.remove_at(position)
  save(bookmarks)
  echo 'Removed "${gone.title}".'
}

to_number() converts a string; bookmarks[position] indexes a list; remove_at() deletes by position and shifts the rest down.

The bounds check is not optional politeness. Indexing a list past its end raises an error, and an unhandled error ends the program.

The Main Loop

The last piece is a loop that reads a command and dispatches on it:

def main() {
  var bookmarks = load()

  echo 'Bookmark keeper. ${bookmarks.length()} saved.'

  while true {
    var command = io.readline('\n(a)dd (l)ist (f)ind (r)emove (q)uit > ').trim().lower()

    using command {
      when 'a' add(bookmarks)
      when 'l' list_all(bookmarks)
      when 'f' find(bookmarks)
      when 'r' remove(bookmarks)
      when 'q' {
        echo 'Bye.'
        return
      }
      default {
        echo 'Unknown command "${command}".'
      }
    }
  }
}

main()

using is Zuri’s multi-way branch, and when is its branch keyword. It compares the subject against each when value and runs the first match; default catches everything else. A when whose body is a single short statement can stay on one line, which is what makes the dispatch table above readable. Anything longer gets a block.

Unlike a C switch, there is no fall-through and no break to remember. One branch runs, then the statement is over.

The Whole Program

Filename: main.zu

import io
import json

var STORE = 'bookmarks.json'

def load() {
  var handle = file(STORE)

  if !handle.exists() {
    return []
  }

  catch {
    return json.decode(handle.read())
  } as error {
    echo 'Could not read ${STORE}: ${error.message}'
    return []
  }
}

def save(bookmarks) {
  var handle = file(STORE, 'w')
  handle.write(json.encode(bookmarks, false))
  handle.close()
}

def add(bookmarks) {
  var title = io.readline('Title: ').trim()
  var url = io.readline('URL:   ').trim()

  if title.is_empty() or url.is_empty() {
    echo 'Both a title and a URL are required.'
    return
  }

  var tags = io.readline('Tags (comma separated): ').trim()

  bookmarks.append({
    title,
    url,
    tags: tags.is_empty() ? [] : tags.split(',').map(@(t) { return t.trim() }),
  })

  save(bookmarks)
  echo 'Saved "${title}".'
}

def show(bookmark, index) {
  echo '${index + 1}. ${bookmark.title}'
  echo '   ${bookmark.url}'

  if !bookmark.tags.is_empty() {
    echo '   [' + ', '.join(bookmark.tags) + ']'
  }
}

def list_all(bookmarks) {
  if bookmarks.is_empty() {
    echo 'Nothing saved yet.'
    return
  }

  bookmarks.each(@(bookmark, index) {
    show(bookmark, index)
  })
}

def find(bookmarks) {
  var needle = io.readline('Search: ').trim().lower()

  var hits = bookmarks.filter(@(bookmark) {
    if bookmark.title.lower().contains(needle) {
      return true
    }
    return bookmark.tags.some(@(tag) { return tag.lower() == needle })
  })

  if hits.is_empty() {
    echo 'No match for "${needle}".'
    return
  }

  hits.each(@(bookmark, index) {
    show(bookmark, index)
  })
}

def remove(bookmarks) {
  list_all(bookmarks)

  if bookmarks.is_empty() {
    return
  }

  var answer = io.readline('Remove which number? ').trim()
  var position = answer.to_number() - 1

  if position < 0 or position >= bookmarks.length() {
    echo 'There is no bookmark ${answer}.'
    return
  }

  var gone = bookmarks[position]
  bookmarks.remove_at(position)
  save(bookmarks)
  echo 'Removed "${gone.title}".'
}

def main() {
  var bookmarks = load()

  echo 'Bookmark keeper. ${bookmarks.length()} saved.'

  while true {
    var command = io.readline('\n(a)dd (l)ist (f)ind (r)emove (q)uit > ').trim().lower()

    using command {
      when 'a' add(bookmarks)
      when 'l' list_all(bookmarks)
      when 'f' find(bookmarks)
      when 'r' remove(bookmarks)
      when 'q' {
        echo 'Bye.'
        return
      }
      default {
        echo 'Unknown command "${command}".'
      }
    }
  }
}

main()

A session looks like this:

$ zuri run main.zu
Bookmark keeper. 0 saved.

(a)dd (l)ist (f)ind (r)emove (q)uit > a
Title: Zuri docs
URL:   https://zuri.dev
Tags (comma separated): lang, docs
Saved "Zuri docs".

(a)dd (l)ist (f)ind (r)emove (q)uit > l
1. Zuri docs
   https://zuri.dev
   [lang, docs]

(a)dd (l)ist (f)ind (r)emove (q)uit > q
Bye.

What You Just Learned

You wrote a program with persistent state, user input, error recovery and a command loop, in about a hundred lines, using nothing that is not in the box.

Along the way you met: var, def, if/else, while, using/when, catch/as, return, lists, dictionaries, dictionary shorthand, string interpolation, the conditional operator, anonymous functions, and a handful of built-in methods.

The next six chapters take every one of those and explain it properly.

Common Programming Concepts

Every language gives you a way to name a value, a set of types those values come in, operators to combine them, and statements to decide what runs next. This chapter is those four things in the form Zuri gives them.

If this is your first language, read the sections in order; each one uses only what came before it. If you already program, read Operators and Control Flow attentively — those are where the same syntax you already know does something different here.

The Reserved Words

Before anything else, the words you cannot use as names. Zuri reserves 31 keywords:

and       as        assert    break     catch     class     const
continue  def       default   do        echo      else      false
for       if        import    in        iter      nil       or
parent    raise     return    self      static    true      using
var       when      while

Every one is lowercase, and every one is explained somewhere in this book. Appendix A is the index, with a one-line summary and a pointer for each.

Three things are not in that list, and are worth noticing now:

• print is not a keyword. It is an ordinary built-in function, and you could shadow it with a variable of your own if you wanted to. echo is a keyword.
• There is no function, int, string or bool keyword. Type names are ordinary identifiers, which is why they can appear as annotations without being reserved.
• There is no try, finally, switch, case, new, this, public or private. The equivalents are catch, using, when, calling the class directly, self, and a leading underscore.

Variables and Constants

A variable is a name for a value. In Zuri you introduce one with var, and from then on the name stands for whatever you last put in it.

var greeting = 'hello'
var count = 0

echo greeting
echo count

hello
0

That is the whole idea. The rest of this section is the detail: what a name may be called, what happens when you leave the value out, where the name can be seen, and what const adds.

Declaring

A var with no initializer holds nil, the value that means “nothing here yet”:

var pending

echo pending

nil

You can declare several names in one statement by separating them with commas, and each one may or may not have a value:

var a = 1, b = 2, c

echo [a, b, c]

[1, 2, nil]

This is worth using when the names genuinely belong together — the three components of a colour, the lower and upper bound of a window — and worth avoiding when they do not, because one long line of declarations is harder to read than three short ones.

var is a declaration, not an expression. It has no value, which is why you cannot write if var x = f() or echo var y = 1. Declare first, then use the name.

Naming

A name is made of letters, digits and underscores, and may not start with a digit. firstName, first_name and _first_name are all legal, and all three are different names.

Zuri code follows one set of conventions everywhere, and the standard library is written in it:

The leading underscore is the one convention that is not only a convention. A name beginning with _ is private, and the compiler enforces it: another file cannot reach module._helper, and code outside a class cannot reach instance._field. Chapter 6 and Chapter 8 cover what that means in each case.

The 31 keywords listed at the end of the previous section cannot be used as names at all. Trying produces a syntax error at the point of declaration.

Reassignment

Zuri is dynamically typed. A variable holds a value, not a type, and assigning a different kind of value to the same name is legal:

var value = 42
value = 'now a string'
value = [1, 2, 3]

echo value

[1, 2, 3]

Legal is not the same as advisable. A name that holds a number on one line and a list twenty lines later is a name no reader can predict. Reach for a second variable instead; they are free.

Assignment is an expression, and it evaluates to the value assigned. That lets you chain:

var x, y

x = y = 5

echo '${x} ${y}'

5 5

Compound Assignment

Every arithmetic and bitwise operator has an assignment form, which applies the operator to the variable’s current value and stores the result:

var n = 5

n += 10     # 15
n **= 2     # 225
n //= 7     # 32
n <<= 1     # 64

echo n

64

The full set is +=, -=, *=, /=, //=, **=, %=, &=, |=, ^=, ~=, <<=, >>= and >>>=. Each one means exactly what the matching binary operator means, applied in place.

Compound assignment works on anything you can assign to, not just plain variables:

var totals = { food: 0 }
var scores = [1, 2, 3]

totals.food += 12
scores[0] *= 10

echo totals
echo scores

{food: 12}
[10, 2, 3]

Increment and Decrement

++ and -- add or subtract one in place:

var n = 5

n++
echo n

n--
echo n

6
5

Two rules to remember. First, both are postfix only. ++n is a syntax error; the operator goes after the name.

Second, when n++ appears inside a larger expression it updates n and then evaluates to the new value:

var j = 5

echo j++
echo j

6
6

If you have written C, Java or JavaScript, this is the opposite of what you expect: there, j++ gives you the old value. In Zuri it gives you the new one. The habit that avoids the question entirely is to let ++ be a statement of its own, or to use it in the update clause of an iter loop where the value is discarded:

iter var i = 0; i < 3; i++ {
  echo i
}

0
1
2

const

const declares a name that cannot be reassigned:

def area(radius) {
  const PI = 3.141592653589793

  return PI * radius * radius
}

echo area(2)

12.566370614359172

Writing to it is caught when the file is compiled, before anything runs:

def f() {
  const K = 1
  K = 2
}

SyntaxError: cannot assign to constant 'K'
  --> /path/to/main.zu:3:3
  |
3 |   K = 2
  |   ^

A const must be given a value where it is declared. const K on its own does not compile, which is the point: a constant with no value would be a constant nil forever.

The const keyword is enforced in local scopes — inside functions, methods, and blocks. At the top level of a module, const declares an ordinary module global and the reassignment check does not apply. Use it where it does its work, which is inside the code that would otherwise be tempted to reassign.

Constant Does Not Mean Frozen

const prevents rebinding the name. It says nothing about the value. A constant list is still a list, and a list is still mutable:

def demo() {
  const items = [1, 2]

  items.append(3)
  echo items
}

demo()

[1, 2, 3]

items = [4] would be an error; items.append(3) is not. If you need a collection nothing can change, copy it at the boundary where you hand it out rather than relying on the declaration.

Scope

A block is a scope. Braces open one, and every name declared inside it is gone when the block closes:

var x = 'outer'

{
  var x = 'inner'
  echo x
}

echo x

inner
outer

The inner x hides the outer one for the length of the block. This is called shadowing, and it is allowed deliberately: a short block can use a short name without worrying about what that name means outside it.

Function bodies, loop bodies, if branches and bare { ... } blocks all work this way. So does the initialiser of an iter loop, whose variable belongs to the loop:

iter var i = 0; i < 2; i++ {
  echo i
}

echo i

0
1
Unhandled UndefinedError: undefined global 'i'
  --> /path/to/main.zu:4

After the loop, i is not a variable at all, and reading it is an error. That error is the good outcome: a name that does not exist is a mistake worth hearing about, and Zuri never invents a silent nil to paper over one.

One Declaration Per Scope

Shadowing across scopes is allowed. Declaring the same name twice in one scope is not:

def f() {
  var a = 1
  var a = 2
}

SyntaxError: 'a' is already declared in this scope
  --> /path/to/main.zu:3:7
  |
3 |   var a = 2
  |       ^

The exception is the top level of a script or module, where a second var a rebinds the existing global instead of erroring. That is what lets you retype a declaration in the REPL while you are experimenting.

Functions Follow the Same Rule

A def is scoped exactly like a var. One written at the top level of a file binds a module-level name; one written inside a function is a local of that function, and nothing outside can reach it:

def outer() {
  def helper() {
    return 'from helper'
  }

  return helper()
}

echo outer()
echo helper()

from helper
Unhandled UndefinedError: undefined global 'helper'
  --> /path/to/main.zu:9

The first call works because helper is a local of outer. The second fails because, outside outer, no such name was ever created.

Chapter 5 covers this in full.

Data Types

Zuri has ten built-in types. typeof() names the one you are holding:

var values = [1, 1.5, 'text', true, nil, [1], {a: 1}, 1..3, 10n, bytes(2)]

for v in values {
  echo typeof(v)
}

number
number
string
bool
nil
list
dict
range
bigint
bytes

On top of those there are function, class, instance, module, file and ptr, which you get from declaring things rather than from a literal.

number

A number is an IEEE-754 double. There is no separate integer type, which means 1 and 1.0 are the same value:

echo 1 == 1.0

true

is_int() asks whether a number’s value is integral, not whether it was written without a decimal point:

echo is_int(1)
echo is_int(1.0)
echo is_int(1.5)

true
true
false

Doubles hold integers exactly up to 2^53. Past that, precision goes:

echo 9007199254740993

9007199254740992

Numeric literals come in five forms:

var decimal = 1_000_000
var binary = 0b1010          # 10
var octal = 0c17             # 15
var hexadecimal = 0xff       # 255
var scientific = 6.02e23

echo [decimal, binary, octal, hexadecimal, scientific]

[1000000, 10, 15, 255, 602000000000000000000000]

Underscores are digit separators, and they are accepted in decimal literals only. 1_000_000 and 1_0.5_5 are fine; 0xdead_beef and 0b1010_1010 are not. Numbers has the full rules.

The special values behave the way the standard says:

echo 1 / 0
echo -1 / 0
echo 0 / 0

inf
-inf
NaN

Every number carries methods, so mathematics reads left to right:

echo 2.sqrt()
echo 16.log2()
echo (-3).abs()
echo 3.7.round()
echo 3.14159.fixed(2)
echo 255.hex()

1.4142135623730951
4
3
4
3.14
ff

A literal takes a method directly; the parentheses around (-3) are there because a method call binds tighter than the minus sign, so -3.abs() would negate the result instead of the operand. Numbers covers the rule in full.

bigint

When 2^53 is not enough, suffix the literal with n and you get an arbitrary-precision integer:

echo 9007199254740993n + 1n

9007199254740994n

Bigints never lose precision and never overflow. They are slower than numbers and they do not silently mix with them, so convert explicitly with to_bigint() and to_number(). Chapter 4 covers them properly.

bool

true and false. Every value in Zuri is either truthy or falsy, and that determines what if, while, and, or, ! and ? : do with it. The falsy values are:

Everything else is truthy, including every negative number, [], {} and '0'.

Two consequences deserve a second look.

A position of 0 is falsy. index_of() returns -1 when it finds nothing, which is truthy, and 0 when it finds the item first, which is falsy. So if list.index_of(x) { ... } gets both cases backwards. Compare the result explicitly:

var haystack = ['a', 'b', 'c']
var position = haystack.index_of('z')

if position == -1 {
  echo 'not found'
}

not found

An empty list is truthy. [] and {} are objects, and objects are truthy. Use is_empty():

var items = []

if items.is_empty() {
  echo 'nothing here'
}

nothing here

nil

nil is the absence of a value. An uninitialised var is nil, a function that falls off the end returns nil, and a missing dictionary key read through get() gives nil.

nil is falsy, and it still has a to_string():

echo nil.to_string()

nil

Calling any other method on nil raises a TypeError, which is usually exactly the error you wanted.

string

This is the short version. Strings covers quoting, escapes, interpolation, concatenation, repetition and regular expressions in full.

Strings are written in single or double quotes, with no difference in meaning:

echo 'single'
echo "double"

Both kinds may span multiple lines:

echo 'multi
line'

multi
line

The escape sequences are \0, \a, \b, \f, \n, \r, \t, \v, \\, \', \", plus \xNN for a byte, \uNNNN for a code point and \UNNNNNNNN for one outside the basic plane:

echo "tab:\there"
echo "hex: \x41"
echo "emoji: \U0001F600"

tab:	here
hex: A
emoji: 😀

A backslash followed by anything else is left alone, backslash and all.

Interpolation

${...} inside a string evaluates the expression and splices the result in. It works in both quote styles and the expression can be anything:

var name = 'Zuri'
echo 'Hi ${name}, ${1 + 2} and ${name.upper()}'

Hi Zuri, 3 and ZURI

To produce a literal ${, build it by concatenation:

echo 'B: $' + '{x}'

B: ${x}

Strings Are Sequences

Indexing gives you a one-character string, and negative indices count from the end:

var s = 'hello world'
echo s[0]
echo s[0,5]
echo s[-5,]

h
hello
world

s[a,b] is a slice: from a up to but not including b. Either side may be left out, so s[,3] is the first three characters and s[3,] is everything from index three onward.

+ concatenates and * repeats:

echo 'ab' + 'cd'
echo 'ab' * 3

abcd
ababab

list

An ordered, growable sequence, written in square brackets. Elements may be of any type, including other lists:

var mixed = [1, 'two', [3], { four: 4 }]
echo mixed.length()

4

Lists index and slice exactly like strings, negative indices included. Chapter 4 covers the forty methods they carry.

dict

An insertion-ordered mapping from keys to values:

var config = { host: 'localhost', port: 8080, debug: true }

A bare word key is taken as a string, so { host: ... } and { 'host': ... } are the same dictionary. Keys can also be numbers, and they can be computed:

var d = { name: 'Ada', 'age': 36, 3: 'three' }
echo d['name']
echo d.name
echo d[3]

Ada
Ada
three

Dot access and bracket access are the same operation. Use the dot when the key is a fixed name, brackets when it is computed or not a valid identifier.

When a key and the variable holding its value share a name, write it once:

var host = 'localhost'
var port = 8080

var config = { host, port }

range

a..b describes the integers from a up to but not including b:

echo 1..5
echo 1..5.to_list()

1..5
[1, 2, 3, 4]

A range is a real value, not loop syntax. You can store one, pass it around, and ask it questions:

var r = 0..10
echo r.lower()
echo r.upper()
echo r.within(7)

0
10
true

bytes

A fixed-size buffer of 8-bit values, for binary data. bytes(n) allocates n zero bytes; bytes(list) builds one from numbers in 0..256:

var b = bytes([72, 101, 108, 108, 111])
echo b
echo b.to_string()
echo b[0]

(48 65 6c 6c 6f)
Hello
72

Bytes print as hexadecimal in parentheses, which is how you can always tell one from a list at a glance. Chapter 10 is the full treatment.

Checking Types

typeof() gives you a name. The is_* family gives you a boolean, and there are fifteen of them:

is_bigint   is_bool     is_bytes    is_callable  is_class
is_dict     is_file     is_function is_instance  is_int
is_iterable is_list     is_number   is_object    is_string

echo is_string('x')
echo is_callable(print)
echo is_iterable([1, 2])

true
true
true

Use instance_of(value, SomeClass) for classes, which walks the inheritance chain. Chapter 6 covers that.

Operators

Arithmetic

/ never truncates. 7 / 2 is 3.5 even though both operands look like integers, because there is only one numeric type. When you want the integer, ask for it with //.

// rounds towards negative infinity, while % keeps the sign of the left operand:

echo -7 // 2
echo 7 // -2
echo -7 % 3
echo 7 % -3

-4
-4
-1
1

% works on non-integers too: 7.5 % 2 is 1.5.

Comparison

== compares by value for numbers, strings, lists and dictionaries, and by identity for everything else. A class changes that for its instances with @eq.

echo 1 == 1.0
echo [1, 2] == [1, 2]
echo {a: 1} == {a: 1}
echo '1' == 1

true
true
true
false

There is no coercion in ==. A string is never equal to a number.

The ordering operators are for numbers. Comparing two strings with < raises a TypeError; use compare(), which returns -1, 0 or 1:

echo 'abc'.compare('abd')

-1

Logic

Zuri spells these as words:

and and or short-circuit, and they return the operand, not a boolean:

echo 1 and 2
echo nil or 'fallback'

2
fallback

That is what makes var name = given or 'anonymous' work. Remember that 0, NaN, '' and false are falsy, so this idiom is only safe when those are not legitimate values.

The Conditional Operator

echo true ? 'yes' : 'no'

yes

cond ? a : b evaluates cond, then exactly one of the branches.

Bitwise

echo ~5
echo 5 >>> 1
echo 1 << 10

-6
2
1024

Bitwise operators work on the integer value of a number, and on bigints.

Concatenation and Repetition

+ on a string concatenates, and a number on either side is converted:

echo 'n=' + 5

n=5

+ on a list concatenates; * repeats:

echo [1, 2] + [3]
echo [1, 2] * 2

[1, 2, 3]
[1, 2, 1, 2]

Dictionaries do not support +. Use extend().

Anything the language does not define raises a TypeError that names the exact signature:

catch {
  echo nil + 1
} as e {
  echo e.message
}

operator '+' not defined for call signature (nil, number)

Classes can define what + and every other operator mean for their own instances. That is Chapter 6.

Member, Index and Slice

Negative indices count back from the end, for both strings and lists.

Precedence

From tightest to loosest. Everything on one row binds equally and associates left to right, except **, which associates right to left.

** follows the mathematical convention. It binds tighter than multiplication and tighter than a unary operator written before it, and it groups from the right:

echo 2 * 3 ** 2
echo 2 ** 3 ** 2
echo -2 ** 2
echo 2 ** -1

18
512
-4
0.5

2 * 3 ** 2 is 2 * (3 ** 2), 2 ** 3 ** 2 is 2 ** (3 ** 2), and -2 ** 2 is -(2 ** 2). The exponent itself may carry a sign, so 2 ** -1 needs no parentheses. Write (-2) ** 2 to raise a negative number.

.. binds very tightly, to primaries only. 1 + 2..5 parses as 1 + (2..5). Parenthesise any range whose endpoints are expressions.

Operators Zuri Does Not Have

There is no in operator for membership; use contains(). There is no ?. optional chaining and no ?? null coalescing; or covers the common case. There is no comma operator, and no += on a member that does not already exist.

Comments and Doc Blocks

Line Comments

# runs to the end of the line:

# Rates are quoted per thousand, not per unit.
var rate = 0.0125  # 1.25%

Block Comments

/* ... */ spans as many lines as you like, and nests:

/* This whole section is off.
   /* Including this inner comment. */
   Still off. */

Nesting is worth knowing about, because it means commenting out a region that already contains a block comment works the way you expect, and it also means an unbalanced /* inside a comment swallows the rest of your file.

Doc Blocks

A block comment that opens with /** is a doc block. The parser keeps doc blocks in the syntax tree rather than discarding them, which is what lets the zuri module read a file’s documentation without a separate parser. Put one directly above the thing it documents:

/**
 * Converts a duration in seconds to a human-readable string.
 *
 * Rounds to the nearest whole second. Durations below one second
 * render as `'0s'`.
 *
 * @param number seconds
 * @returns string
 */
def humanize(seconds) {
  # ...
}

The tag vocabulary used across the standard library is:

Two conventions from the standard library are worth copying. State the default of every optional parameter, and state what happens at the edges: an empty input, a zero length, a value out of range. Anything a caller would otherwise have to discover by experiment belongs in the doc block.

Doc blocks are not only for readers. Because the parser keeps them, a program can read them: zuri.parse() returns each one as a DocBlock node sitting immediately before the declaration it documents, which is enough to build a documentation generator in a few dozen lines. Chapter 21 shows how.

Commenting Style

A comment earns its place by explaining why, not what. The code already says what it does:

# Bad: restates the code.
# Add one to the counter.
counter++

# Good: explains a decision the code cannot.
# Servers count from one, and the wire protocol has no zero frame.
counter++

Control Flow

Control flow is how a program decides what to run next: run this only when that is true, run this until that stops being true, run this once for every item in a collection. Zuri has seven statements for it, and this section covers all of them.

Blocks and Single Statements

Every control-flow statement takes a body. A body is either a block in braces, or a single statement:

var ready = true

if ready {
  echo 'launching'
}

if ready echo 'launching again'

launching
launching again

Both forms are the language. if, else, while, do, for, and a when branch inside using all accept either one.

iter is the exception. Its body must be a block, because the semicolons in its header would otherwise be ambiguous with the statement that follows:

iter var i = 0; i < 3; i++ echo i

SyntaxError: Expected '{' at the start of iter body.

The standard library and the examples in this book brace every body except a short when branch. Braces make a one-line body easy to extend into a three-line one later, and they keep the shape of a nested statement obvious at a glance. It is a convention, not a rule — write whichever form reads better in the code you are writing.

if / else

var score = 73

if score >= 90 {
  echo 'A'
} else if score >= 70 {
  echo 'B'
} else {
  echo 'C'
}

B

There is no elif; else if is two keywords, and it works because the body of an else can itself be an if statement.

The condition is any expression at all, and it is judged by truthiness rather than by being a bool:

var name = ''

if name {
  echo 'have a name'
} else {
  echo 'no name'
}

no name

That is convenient and it is also where most bugs in new Zuri code come from, because a legitimate 0 is falsy. Re-read the table in Data Types before you write if count or if position.

The Conditional Expression

? : is the expression form of if. It chooses between two values rather than between two statements:

var age = 20
var status = age >= 18 ? 'adult' : 'minor'

echo status

adult

It nests, and it can span several lines. When breaking one across lines, ? and : may either end a line or begin the next, whichever reads better; leading each branch with its operator keeps the shape of the choice visible:

var n = 7

var size = n > 100
  ? 'large'
  : n > 5
    ? 'medium'
    : 'small'

echo size

medium

Use ? : when you are producing a value and if when you are performing an action. A conditional expression whose branches are both side effects is harder to read than the if it replaced.

while

while tests before each pass, so a body may run zero times:

var n = 0

while n < 3 {
  echo 'while ${n}'
  n++
}

while 0
while 1
while 2

do / while

do runs the body once and then tests, so the body always runs at least once. Reach for it when the test depends on something the body produces:

var m = 10

do {
  echo 'do ${m}'
  m++
} while m < 3

do 10

The condition was false from the very start, and the body still ran.

iter

iter is the counting loop. Its header has three clauses separated by semicolons: an initialiser, a condition, and an update.

iter var i = 0; i < 3; i++ {
  echo 'iter ${i}'
}

iter 0
iter 1
iter 2

The initialiser runs once. The condition is tested before every pass. The update runs after every pass. A variable declared in the initialiser belongs to the loop and does not exist after it.

The initialiser may declare several variables and the update may hold several expressions, each list separated by commas. The updates run in the order they are written:

iter var i = 0, j = 10; i < 3; i++, j-- {
  echo '${i} ${j}'
}

0 10
1 9
2 8

Every clause is optional:

var k = 0

iter ; k < 2; {
  echo 'bare ${k}'
  k++
}

bare 0
bare 1

iter ; ; { ... } loops forever, though while true says it more plainly.

The header may be spread over several lines, which is worth doing when the condition is long:

iter var i = 1;
  i <= 3;
  i++
{
  echo i
}

1
2
3

for / in

for walks an iterable: a list, a dictionary, a string, a range, a byte stream, or any class that implements the iterator protocol.

With one variable you get the value:

for ch in 'hey' {
  echo ch
}

h
e
y

With two, you get the key first and the value second:

for index, value in ['a', 'b'] {
  echo '${index} ${value}'
}

for key, value in { x: 1, y: 2 } {
  echo '${key}=${value}'
}

0 a
1 b
x=1
y=2

For a list the key is the index, for a dictionary it is the key, and for a string it is the character position. Dictionaries iterate in insertion order, and so does everything else with an order to preserve.

Ranges are exclusive at the top:

for i in 0..3 {
  echo i
}

0
1
2

The iterable expression is evaluated exactly once, before the first pass. Calling a function in that position calls it once, not once per element:

def source() {
  echo 'source() called'
  return [1, 2, 3]
}

for n in source() {
  echo n
}

source() called
1
2
3

Chapter 6 shows how to make your own class work with for by defining @key() and @value().

break and continue

continue skips to the next pass, and break leaves the loop entirely:

iter var i = 0; i < 5; i++ {
  if i == 1 {
    continue
  }

  if i == 3 {
    break
  }

  echo i
}

0
2

Both apply to the innermost enclosing loop, and there are no loop labels. To leave a nested loop you either carry a flag:

var found = false

iter var i = 1; i < 4; i++ {
  iter var j = 1; j < 4; j++ {
    if i * j == 4 {
      echo 'found ${i} x ${j}'
      found = true
      break
    }
  }

  if found {
    break
  }
}

found 2 x 2

or, more often, put the nested loop in a function and return out of it:

def first_product(target) {
  iter var i = 1; i < 4; i++ {
    iter var j = 1; j < 4; j++ {
      if i * j == target {
        return [i, j]
      }
    }
  }

  return nil
}

echo first_product(4)
echo first_product(99)

[2, 2]
nil

The second version says what it is looking for in its name, and it has no flag to keep in sync. Prefer it.

using / when

using compares one subject against several candidate values:

var grade = 'B'

using grade {
  when 'A' echo 'excellent'
  when 'B', 'C' echo 'good'
  default echo 'try again'
}

good

Several values on one when are alternatives, not a sequence: this when matches 'B' or 'C'. The first branch that matches runs, and then the statement is over — there is no fall-through, and no break to remember.

Matching uses the same equality as ==, which means using works on numbers, strings and booleans, and compares instances by identity, or through @eq when their class defines one.

default is optional. When nothing matches and there is no default, nothing happens:

using 99 {
  when 1 echo 'one'
}

echo 'nothing ran, and that is not an error'

nothing ran, and that is not an error

A when branch takes a block when it needs one:

var command = 'q'

using command {
  when 'a' echo 'adding'
  when 'q' {
    echo 'saving'
    echo 'goodbye'
  }
  default echo 'unknown command'
}

saving
goodbye

using is the right shape whenever you are dispatching on one value to many outcomes. A chain of else if comparing the same variable over and over is the same thing written longer.

assert

assert checks a condition and raises an AssertError when it is false:

var items = [1]

assert 1 + 1 == 2
assert items.length() == 1, 'list should have one item'

echo 'both assertions held'

both assertions held

The optional second argument is the message the error carries:

assert 1 == 2, 'arithmetic is broken'

Unhandled AssertError: arithmetic is broken

Assertions state what you believe is already true. They are for conditions that should be impossible, not for checking input that might legitimately be wrong — raise a ValueError for that. Chapter 7 draws the line in detail.

return

return leaves the current function, with a value if you give it one and nil if you do not:

def classify(n) {
  if n < 0 {
    return 'negative'
  }

  if n == 0 {
    return 'zero'
  }

  return 'positive'
}

echo classify(-5)
echo classify(0)
echo classify(3)

negative
zero
positive

A function that reaches its closing brace without a return yields nil. There are no implicit returns; the last expression in a body is not its value.

return is only legal inside a function. At the top level of a script it is a syntax error, because there is nothing to return from.

Text, Numbers and Collections

Chapter 3 introduced the built-in types and showed what the operators do to them. This chapter is the working manual for the five you will reach for every day: strings, numbers, lists, dictionaries and ranges.

One idea shapes all five. Zuri puts behaviour on the value itself. There is no len(x) and no str.upper(x); there is x.length() and x.upper(). That holds for numbers too, which carry the whole of the mathematics library as methods:

echo 'zuri'.upper()
echo [3, 1, 2].sort()
echo 16.sqrt()
echo 255.hex()

ZURI
[1, 2, 3]
4
ff

Because the methods live on the value, they chain, and a chain reads left to right in the order the work happens:

var line = '  Ada, Grace , Alan  '

echo line.trim().split(',').map(@(name) => name.trim()).length()

3

Each section here covers the methods worth knowing by name, the ones with a behaviour you would not guess, and the mistakes that come up most often. Appendix E is the complete list, generated from the same documentation the runtime ships.

Strings

A Zuri string is UTF-8 text. Indexing, slicing and length() work in characters, not bytes, so a string of emoji behaves the way a reader expects.

Text is the type you will write most, so this section starts with how you write one down — quoting, escapes and interpolation — before moving on to what you can do with it.

Writing a String

A string literal is written between single or double quotes:

echo 'single quotes'
echo "double quotes"

single quotes
double quotes

The two styles are identical. They are not the two different things they are in some other languages. Both process escape sequences, both interpolate expressions, and both may span several lines. Nothing at all changes except which quote character ends the string:

var name = 'Zuri'

echo 'escape \t and interpolate ${name}'
echo "escape \t and interpolate ${name}"

escape 	 and interpolate Zuri
escape 	 and interpolate Zuri

Pick whichever avoids escaping. A string containing an apostrophe is easiest in double quotes; a string containing a quotation mark is easiest in single quotes:

echo "it's clearer this way"
echo 'she said "hello"'

it's clearer this way
she said "hello"

Most Zuri code, and all of the standard library, uses single quotes by default and switches to double quotes when the content calls for it.

Multi-line Strings

A literal may simply contain newlines. There is no separate triple-quoted form and no continuation character:

var message = 'Dear reader,

Thank you for the strings.'

echo message

Dear reader,

Thank you for the strings.

Everything between the quotes is part of the string, indentation included. When a long string is indented inside a function, the leading spaces on each line are in the string too, which is why it is advisable that code that builds indented text should assemble it with join() rather than writing one long literal.

Escape Sequences

A backslash starts an escape. The full set is:

The three numeric forms take exactly the number of hex digits shown — two, four and eight — and the digits may be upper or lower case:

echo 'hex byte: \x41'
echo 'code point: \u00e9'
echo 'astral: \U0001F600'

hex byte: A
code point: é
astral: 😀

\u covers everything up to U+FFFF. Anything above that — emoji, most historic scripts, mathematical alphanumerics — needs \U and its eight digits. Zero-pad to fill them.

Unknown Escapes Are Left Alone

A backslash followed by anything not in the table above is not an error, and it is not silently dropped either. The backslash and the character both survive:

echo 'a regex: \d+ and \w+'
echo 'a path: C:\temp\notes'

a regex: \d+ and \w+
a path: C:	emp
otes

The first line came through untouched: \d and \w are not escapes, so both backslashes survived, which is exactly why regular expressions can be written as plain strings.

The second line did not. \t is an escape, so C:\temp became C: followed by a tab and then emp; \n is an escape too, so \notes became a newline followed by otes. One path, two silent substitutions. The rule is easy to state and easy to forget: unknown escapes pass through, known ones do not, and nothing in the way you write them tells you which is which.

For Windows paths and regular expressions — the two places this bites — double the backslashes:

echo 'a path: C:\\temp\\notes'

a path: C:\temp\notes

Escaping the Quote You Chose

You only need to escape the quote character that would end the string:

echo 'it\'s escaped'
echo "she said \"hi\""

it's escaped
she said "hi"

Escaping the other quote is harmless but pointless, and because an unnecessary escape is an unknown escape, the backslash stays in the result:

echo 'this \" keeps its backslash'

this \" keeps its backslash

That is a good reason to choose the quote style that lets you write the text plainly and escape nothing at all.

Interpolation

${...} inside a string evaluates the expression between the braces and splices its text into the result:

var name = 'Ada'
var year = 1843

echo 'In ${year}, ${name} wrote the first program.'

In 1843, Ada wrote the first program.

This works in both quote styles, and it is the way most Zuri code builds a string. The section after next covers +, which does the same job with more punctuation.

Any Expression Fits

The braces take a whole expression, not just a variable name. Arithmetic, method calls, indexing, comparisons and conditionals all work:

var items = ['a', 'b', 'c']
var user = { name: 'ada', admin: true }

echo 'count: ${items.length()}'
echo 'first: ${items[0].upper()}'
echo 'math: ${(2 ** 10) - 24}'
echo 'role: ${user.admin ? 'admin' : 'user'}'
echo 'name: ${user.name.capitalize()}'

count: 3
first: A
math: 1000
role: admin
name: Ada

Notice the third line. The quotes inside ${...} are the same quote character that opened the string, and it still parses correctly, because the expression inside the braces is lexed as its own piece of code rather than as text. You do not need to switch quote styles or escape anything to put a string literal inside an interpolation.

Interpolations Nest

A string literal inside ${...} is a string literal like any other, which means it may contain interpolations of its own, to any depth:

var n = 1

echo 'outer ${ 'inner ${n + 1}' }'
echo '${ '${ '${2 ** 3}' }' }'

outer inner 2
8

This is not a curiosity. It is what makes a conditional inside a string able to produce formatted text rather than a bare word, which comes up constantly in messages meant for a person to read:

var user = { name: 'ada', unread: 3 }

echo 'Hi ${user.name.capitalize()}, you have ${user.unread > 0 ? '${user.unread} new ${user.unread == 1 ? 'message' : 'messages'}' : 'nothing new'}.'

Hi Ada, you have 3 new messages.

Three levels of interpolation are at work there: the outer message, the branch that chooses between a count and “nothing new”, and the branch that picks the singular or the plural. Each one is an ordinary string literal in an ordinary expression, and each one uses single quotes, because the expression inside ${...} is lexed as code and its quotes never collide with the ones around it.

Nesting is equally useful inside a callback, where the inner string is building one element of a larger result:

var items = ['a', 'b']

echo 'list: ${', '.join(items.map(@(i) => '<${i}>'))}'

list: <a>, <b>

Depth costs readability quickly. When a line like the message above stops being scannable, lift the inner pieces into local variables on the lines before it; the language is happy either way.

What Each Type Looks Like

Interpolation renders a value the same way echo does:

var settings = { a: 1 }

echo 'number: ${1 / 3}'
echo 'list: ${[1, 2]}'
echo 'dict: ${settings}'
echo 'nil: ${nil}'
echo 'bool: ${true}'

number: 0.3333333333333333
list: [1, 2]
dict: {a: 1}
nil: nil
bool: true

A dictionary literal written directly inside ${...} does not parse, because its closing brace runs into the interpolation’s closing brace:

echo 'dict: ${{ a: 1 }}'

SyntaxError: Expected '}' after dictionary

Put it in a variable first, as above. A list literal has no such problem, since ] and } are different characters.

There is one important exception, and it catches everyone once. Interpolating a class instance does not call its to_string() method:

class Point {

  @new(x, y) {
    self.x = x
    self.y = y
  }

  to_string() {
    return '(${self.x}, ${self.y})'
  }
}

var p = Point(3, 4)

echo 'implicit: ${p}'
echo 'explicit: ${p.to_string()}'

implicit: <instance of Point>
explicit: (3, 4)

Call the method yourself. This applies to 'text ' + p too. Interpolation and + never call a method on your behalf to produce text; if you want to_string() to run, write it. echo is the exception, through @to_string(), which Decorated Methods covers.

Writing a Literal ${

A backslash does not escape an interpolation. \${x} is an unknown escape, so the backslash survives and the interpolation still does not happen — which is rarely what anyone wants:

echo 'literal attempt: \${x}'

literal attempt: \${x}

To produce the two characters ${ followed by text, split the string so the $ and the { are never adjacent inside one literal:

echo 'shell syntax: $' + '{HOME}'

shell syntax: ${HOME}

A lone $ is not special, so only the exact sequence ${ needs this treatment:

echo 'price: $5.00'
echo 'total: $${12 + 8}'

price: $5.00
total: $20

Joining Strings Together

Concatenation with +

+ joins two strings end to end:

echo 'Hello, ' + 'world'
echo 'a' + 'b' + 'c'

Hello, world
abc

When one side is a string, the other side is converted to its text form first. This works in both directions, and for every built-in type:

echo 'n=' + 5
echo 5 + 'n'
echo 'pi is about ' + 3.14
echo 'flag: ' + true
echo 'missing: ' + nil
echo 'items: ' + [1, 2]

n=5
5n
pi is about 3.14
flag: true
missing: nil
items: [1, 2]

Read the second line again: 5 + 'n' gives '5n', not an error and not arithmetic. A string on either side turns the whole expression into concatenation. That is worth knowing when a value arrives from somewhere you do not control:

var quantity = '2'

echo quantity + 3
echo quantity.to_number() + 3

23
5

The first line is text, the second is arithmetic, and nothing in the expression tells you which you are getting. When a number must be a number, convert it at the point it enters your program rather than hoping.

The one type that does not convert usefully is a class instance:

class Point {

  @new(x, y) {
    self.x = x
    self.y = y
  }

  to_string() {
    return '(${self.x}, ${self.y})'
  }
}

echo 'at ' + Point(1, 2).to_string()

at (1, 2)

Concatenating the instance directly would produce <instance of Point>, for the same reason interpolation does: Zuri does not call to_string() for you.

Concatenation Versus Interpolation

Both produce the same string, so choose on readability:

var host = 'localhost'
var port = 8080

echo 'connecting to ' + host + ':' + port + '/health'
echo 'connecting to ${host}:${port}/health'

connecting to localhost:8080/health
connecting to localhost:8080/health

Interpolation wins whenever there is more than one hole to fill: the literal text stays in one piece, the quotes do not multiply, and there is no chance of losing a separator between two + signs. Reach for + when you are gluing exactly two pieces together, or when one of them is already a variable holding a complete string.

Repetition with *

* repeats a string a whole number of times:

echo 'ab' * 3
echo '-' * 20
echo '  ' * 2 + 'indented'

ababab
--------------------
    indented

That second line is the reason this operator earns its place. Separators, rules, indentation and padding are all one short expression instead of a loop.

The rules for the count are worth stating exactly:

• A count of 1 returns the string unchanged.
• A count of 0 returns the empty string.
• A negative count also returns the empty string, rather than raising.
• A fractional count is truncated toward zero, so * 2.7 repeats twice.

echo '[' + 'ab' * 1 + ']'
echo '[' + 'ab' * 0 + ']'
echo '[' + 'ab' * -1 + ']'
echo '[' + 'ab' * 2.7 + ']'

[ab]
[]
[]
[abab]

The negative case is the one to watch. '-' * (width - label.length()) silently produces nothing when the label is longer than the width, and no error tells you so. When the count is computed, clamp it:

def rule(width, label) {
  var padding = (width - label.length()).max(0)

  return label + '-' * padding
}

echo rule(10, 'ab')
echo rule(10, 'a much longer label')

ab--------
a much longer label

Unlike +, repetition does not commute. The string has to be on the left:

echo 3 * 'ab'

Unhandled TypeError: operator '*' not defined for call signature (number, string)

Building a String from Many Pieces

For more than a handful of pieces, neither operator is the right tool. Collect them in a list and join():

var names = ['ada', 'grace', 'alan']

echo ', '.join(names)
echo '\n'.join(names.map(@(n) => '- ' + n.capitalize()))

ada, grace, alan
- Ada
- Grace
- Alan

join() lives on the separator, not on the list, and it converts each element to text on the way — so a list of numbers joins as readily as a list of strings:

echo '-'.join([1, 2, 3])

1-2-3

Note also that join() puts the separator between elements, never at either end, which is exactly the behaviour a hand-written loop usually gets wrong on the last item.

Inspecting

var s = 'Hello, Zuri'

echo s.length()
echo s.is_empty()
echo s.index_of('Zuri')
echo s.count('l')
echo s.starts_with('Hello')
echo s.ends_with('Zuri')
echo s.contains('Zuri')

11
false
7
2
true
true
true

index_of() returns -1 when there is no match, and takes an optional second argument to start the search from.

last_index_of() searches from the other end, which is what you want whenever the interesting separator is the final one:

var path = 'src/vm/value.rs'

echo path.index_of('/')
echo path.last_index_of('/')
echo path[path.last_index_of('/') + 1, path.length()]
echo path.last_index_of('\\')

3
6
value.rs
-1

Both take a second argument, and in both it bounds where a match may begin. That makes the pair split a string at one index: for any n, index_of(str, n) finds the first match at or after n and last_index_of(str, n) the last match at or before it.

There is a family of character-class predicates, each true when every character in the string qualifies:

echo 'abc'.is_alpha()
echo '123'.is_number()
echo 'ABC'.is_upper()
echo '  '.is_space()

true
true
true
true

The full set is is_alpha, is_alnum, is_number, is_lower, is_upper, is_space, plus is_empty.

Changing Case

var s = 'Hello, Zuri'

echo s.upper()
echo s.lower()
echo s.capitalize()
echo s.title()

HELLO, ZURI
hello, zuri
Hello, zuri
Hello, Zuri

capitalize() uppercases the first character and lowercases the rest. title() does that to every word.

For comparing text from users, reach for case_fold() rather than lower(). Case folding is the Unicode operation defined for case-insensitive matching, and it handles cases simple lowercasing gets wrong:

echo 'Straße'.case_fold()

strasse

Trimming and Padding

echo '[' + '  pad  '.trim() + ']'
echo '[' + '  pad  '.ltrim() + ']'
echo '[' + '  pad  '.rtrim() + ']'
echo 'xxhixx'.trim('x')
echo '-=hi=-'.trim('-=')

[pad]
[pad  ]
[  pad]
hi
hi

With no argument, all three strip whitespace: spaces, tabs, newlines, carriage returns, vertical tabs and form feeds. Given a string, they strip every character in it, in any order, so '-=hi=-'.trim('-=') is hi.

echo 'x'.lpad(5, '.')
echo 'x'.rpad(5, '.')

....x
x....

lpad and rpad take a target width and an optional fill character that defaults to a space. A string already at or over the width comes back unchanged.

Splitting and Joining

echo 'Hello, Zuri'.split(', ')
echo ', '.join(['a', 'b', 'c'])
echo 'abc'.to_list()
echo 'line1\nline2'.lines()

[Hello, Zuri]
a, b, c
[a, b, c]
[line1, line2]

join lives on the separator, not on the list. to_list() splits into single characters. lines() splits on newlines and handles both \n and \r\n.

Replacing

echo 'Hello, Zuri'.replace('Zuri', 'World')

Hello, World

Every occurrence is replaced. The pattern may be a regular expression, and the replacement can refer back to capture groups with $1, $2 or ${1}:

echo 'John Smith'.replace('/(\w+) (\w+)/', '$2, $1')

Smith, John

The optional third argument turns regex handling off, so a pattern that would otherwise be read as a regex is matched literally, delimiters included:

echo 'a/b/c'.replace('/b/', 'X')
echo 'a/b/c'.replace('/b/', 'X', false)

a/X/c
aXc

When the replacement depends on what was matched, use replace_with(), which calls a function for each match:

echo 'a1b2'.replace_with('/[0-9]/', @(m) => '<' + m + '>')

a<1>b<2>

Regular Expressions

Zuri’s regular expressions are PCRE2, the same engine that powers regular expressions in PHP, R and a long list of other tools. It is the real library rather than a subset of it, so named groups, backreferences, lookahead, lookbehind, atomic groups, possessive quantifiers, conditionals and recursion all work exactly as PCRE2 documents them.

This section covers how a pattern is written in Zuri, which methods accept one, what each modifier does, and the handful of places where Zuri’s surface differs from what you may expect. It does not teach regular expression syntax itself; any PCRE or Perl reference applies unchanged.

Writing a Pattern

A pattern is an ordinary string whose first character is a non-word character, repeated to close the pattern, with any modifier letters after the closing delimiter:

'/[a-z]+/'
'/[a-z]+/i'
'#\d{3}#'
'!https?://\S+!i'

A “non-word character” is anything that is not a letter, a digit or an underscore. Forward slash is the conventional choice, and every example in this book uses it, but the delimiter is yours to pick — which is worth doing when the pattern itself is full of slashes:

echo 'see https://example.com/docs now'.match('!https?://\S+!')

{0: https://example.com/docs}

Because the pattern is a string, the backslashes in it are subject to Zuri’s own escape rules first. This is almost never a problem, because \d, \w, \s, \b and \S are not escape sequences and therefore pass through untouched. The exceptions are the letters that are escapes — \t, \n, \r, \f, \v, \a, \b, \0, \x and \u. Of those, \t and \n mean the same thing to both, so they are harmless; \b (word boundary in a pattern, backspace in a string) is the one that will catch you:

echo 'one two'.match('/\btwo\b/')
echo 'one two'.match('/\\btwo\\b/')

false
{0: two}

Double the backslash whenever the pattern needs \b.

A Plain String Is a Literal

Every method in this section also accepts a plain string, and treats it as a literal substring rather than a pattern:

echo 'a.b'.replace('.', 'X')
echo 'a.b'.replace('/./', 'X')

aXb
XXX

The first call replaced the single full stop. The second compiled . as a pattern, where it means “any character”, and replaced all three.

That distinction is decided purely by whether the string looks like a delimited pattern. When you have text from elsewhere that might accidentally look like one, replace() takes a third argument that turns pattern handling off:

echo 'a/b/c'.replace('/b/', 'X')
echo 'a/b/c'.replace('/b/', 'X', false)

a/X/c
aXc

With false, the delimiters are matched as characters like anything else.

Which Methods Take a Pattern

Five, and only five:

Everything else — contains(), index_of(), count(), starts_with(), ends_with(), trim() — takes a literal string only. A regex-looking argument passed to one of those is matched as the literal characters it contains:

echo 'a1b'.contains('/[0-9]/')
echo 'a1b'.index_of('/[0-9]/')
echo 'a1b'.count('/[0-9]/')

false
-1
0

All three answered about the six-character string /[0-9]/, which is not in a1b. When you need a pattern there, reach for match() instead.

match() and matches()

match() finds the first match and returns it as a dictionary under key 0. It returns false — not nil — when nothing matches:

echo 'one two'.match('/\w+/')
echo 'nope'.match('/zzz/')
echo typeof('nope'.match('/zzz/'))

{0: one}
false
bool

Both are falsy, so if s.match(p) { ... } reads correctly. An equality test against nil does not, and this is the single most common regex mistake in Zuri code.

The dictionary holds the pattern’s capture groups as well, each under its number, and a named group under its name too. A group that takes no part in the match is nil:

echo '2024-01'.match('/(?<year>\d+)-(\d+)/')
echo 'ab'.match('/([a-z]+)(\d+)?/')

{0: 2024-01, 1: 2024, 2: 01, year: 2024}
{0: ab, 1: ab, 2: nil}

matches() finds every match and groups the results by capture group. Key 0 holds the whole matches, key 1 the first group’s, and so on — each as a list, parallel across the keys:

echo 'a1b2c3'.matches('/[0-9]/')
echo 'a1b2'.matches('/([a-z])([0-9])/')

{0: [1, 2, 3]}
{0: [a1, b2], 1: [a, b], 2: [1, 2]}

In the second result, match zero is a1 with groups a and 1, and match one is b2 with groups b and 2. Read down the lists, not across.

When nothing matches, matches() returns {0: []} rather than false. The two methods differ here, so test matches() with is_empty() on key zero:

var found = 'nope'.matches('/zzz/')

echo found
echo found[0].is_empty()

{0: []}
true

Capture Groups in a Replacement

replace() refers to a capture group with $1, $2 and so on:

echo 'John Smith'.replace('/(\w+) (\w+)/', '$2, $1')

Smith, John

Do not write ${1}. The braced form is Zuri’s own string interpolation, and it is consumed before replace() ever sees it. The expression 2 evaluates to the number two, so the replacement string is already '2, 1' by the time it arrives:

echo 'John Smith'.replace('/(\w+) (\w+)/', '${2}, ${1}')

2, 1

Use the bare $1 form throughout. This is one of the few places where Zuri’s interpolation and another language’s syntax collide, and it fails quietly rather than loudly.

Named Groups

Named groups are supported in the pattern, because PCRE2 supports them:

echo 'John Smith'.matches('/(?<first>\w+) (?<last>\w+)/')

{0: [John Smith], 1: [John], 2: [Smith]}

The results are keyed by position, not by name. A name in a pattern documents the group and lets a backreference such as \k<first> refer to it; it does not change how the result is keyed. Count the groups to find the one you want.

Computing the Replacement

When the replacement depends on what matched, replace_with() calls a function for each match:

echo 'a1b2'.replace_with('/[0-9]/', @(m) => '<' + m + '>')

a<1>b<2>

The callback receives the whole match first, then one argument per capture group, then the offset of the match, then the whole subject string. Take only the arguments you need, since extra arguments are dropped:

echo 'aXbXc'.replace_with('/X/', @(match, offset) => '[${offset}]')

a[1]b[3]c

Splitting on a Pattern

split() accepts a pattern, which is how you split on “one or more of something” rather than on an exact separator:

echo 'a1b22c'.split('/[0-9]+/')
echo 'a, b,c ,  d'.split('/\s*,\s*/')

[a, b, c]
[a, b, c, d]

The Modifiers

Modifier letters go after the closing delimiter, in any order and any combination. /[a-z]+/mi is both multi-line and case-insensitive.

Each one in use:

echo 'HELLO'.match('/hello/i')
echo 'a\nb'.matches('/^./m')
echo 'a\nb'.match('/a.b/s')
echo 'abc'.match('/ a b c /x')
echo 'héllo'.matches('/\w/u')
echo 'aaa'.match('/a+?/U')
echo 'abc'.match('/abc/A')
echo 'xabc'.match('/abc/A')

{0: HELLO}
{0: [a, b]}
{0: a
b}
{0: abc}
{0: [h, é, l, l, o]}
{0: aaa}
{0: abc}
false

Read the last two together: the pattern matched when it was at the start of the subject and failed when it was not, which is what A is for. Without it, the second would have matched at offset one.

u is worth a second look as well. Without it, \w is ASCII-only and é is not a word character; with it, the Unicode properties apply and it is. Matching itself is always per-character rather than per-byte, so indexes and offsets are correct on multi-byte text regardless of u.

The One Exception to PCRE2 Compatibility

PCRE2’s D (dollar-endonly) modifier has no effect in Zuri. $ always matches before a trailing newline as well as at the absolute end of the subject, and there is no way to change that. The letter is accepted rather than rejected, so a pattern carrying it compiles and runs; it simply does not do anything.

The same is true of any other unrecognised modifier letter: it is accepted and ignored rather than raising. A typo in a modifier is therefore silent, which is worth remembering when a pattern behaves as though a flag you wrote is not set.

Everything else in the table above is supported and behaves exactly as PCRE2 documents it.

Invalid Patterns

A pattern that PCRE2 cannot compile raises, naming the pattern and the engine’s own explanation:

catch {
  echo 'text'.match('/(unclosed/')
} as e {
  echo e.message
}

invalid regular expression '(unclosed': PCRE2: error compiling pattern at offset 9: missing closing parenthesis

Patterns are compiled once and reused, so repeating the same pattern in a loop costs nothing after the first time through.

Conversion

echo '5'.to_number() + 1
echo 'ff'.to_number(16)
echo 'H'.ord()
echo 72.chr()
echo 'Hi'.to_bytes()

6
255
72
H
(48 69)

to_number() takes an optional base. ord() requires a single-character string and gives its code point; chr() on a number goes the other way.

to_number() Never Fails

This is the one conversion behaviour worth memorising. to_number() does not raise, and it does not produce NaN. It reads the first number written in the string, and text with no number in it at all becomes zero:

echo '42'.to_number()
echo '3.5'.to_number()
echo '-5'.to_number()
echo 'eighty'.to_number()
echo ''.to_number()
echo '12abc'.to_number()
echo '  7  '.to_number()
echo '96.3 of 31'.to_number()

42
3.5
-5
0
0
12
7
96.3

Look at the last three. What surrounds the number is ignored, so '12abc' is 12, the spaces around ' 7 ' are simply not part of it, and only the first number is read however many follow.

That cuts both ways. '3 apples' giving 3 is usually what was meant; '2026-09-16' giving 2026 usually is not. A number is taken to start at a digit, or at a sign or decimal point directly in front of one, so '-5' is negative five and 'a - 42', where the sign stands apart, is 42.

There is no error to catch and no sentinel to test, so a form field a user left blank and a form field they filled with '0' produce the same number, and so do 'eighty' and '0'. When the difference matters, check the text before converting it:

def to_count(text) {
  var trimmed = text.trim()

  if !trimmed.match('/^\d+$/') {
    raise ValueError('not a whole number: ${text}')
  }

  return trimmed.to_number()
}

echo to_count('  12  ')

catch {
  to_count('twelve')
} as e {
  echo e.message
}

12
not a whole number: twelve

is_number() is a narrower test than it looks — it is true only for a string of digits, so '3.5' and '-5' both fail it. A regular expression is the reliable check for anything beyond unsigned integers.

Walking a String

A string is iterable, one character at a time, and the same four forms available for a list work here.

for, One Character at a Time

for ch in 'hey' {
  echo ch
}

h
e
y

This is the form to reach for by default. Each ch is a one-character string, not a code point number — use ord() when you want the number.

for With Two Variables, for the Position

for index, ch in 'hey' {
  echo '${index}: ${ch}'
}

0: h
1: e
2: y

The key comes first and the value second, and for a string the key is the character position.

iter, When the Position Drives the Walk

var s = 'hey'

iter var i = s.length() - 1; i >= 0; i-- {
  echo s[i]
}

y
e
h

s[i] indexes by character, not by byte, so this is correct on text that is not ASCII. Use iter when you need to skip, step backwards, or look at s[i + 1] from inside the body.

each(), With a Function

'Hi'.each(@(ch, index) {
  echo '${index}:${ch}'
})

0:H
1:i

As everywhere else, the callback receives the value first and the index second — the opposite order to for.

each_line() and lines(), for Text in Lines

var doc = 'first\nsecond\nthird'

doc.each_line(@(line, index) {
  echo '${index}: ${line}'
})

echo doc.lines()

0: first
1: second
2: third
[first, second, third]

each_line() calls the function once per line; lines() hands you the whole list so you can for over it, filter it, or count it. Both split on \n and \r\n, so both read a file written on any platform.

Ordering and Comparison

== compares two strings by value, which is almost always what you want:

echo 'abc' == 'abc'
echo 'abc' == 'ABC'

true
false

The ordering operators are a different story. <, <=, > and >= are defined for numbers only, and comparing two strings with one raises a TypeError. Use compare(), which returns -1, 0 or 1:

echo 'abc'.compare('abd')
echo 'abc'.compare('abc')
echo 'abd'.compare('abc')

-1
0
1

That three-way result is exactly the shape a sort comparison wants, and it compares by code point, so it is stable and locale-independent.

Strings Are Immutable

Every method in this section returns a new string. Nothing mutates in place:

var original = 'hello'
var shouted = original.upper()

echo original
echo shouted

hello
HELLO

This is worth internalising, because it is the source of the single most common string mistake:

var name = '  ada  '

name.trim()
echo '[${name}]'

name = name.trim()
echo '[${name}]'

[  ada  ]
[ada]

The first trim() produced a trimmed string and threw it away. Assign the result, or chain onto it.

Immutability also means you can pass a string anywhere without copying it defensively. Nothing you hand a string to can change the one you still hold.

A Worked Example

Here is a small parser that puts most of this section together. It takes a block of key = value configuration text and produces a dictionary, skipping blank lines and comments, and tolerating whatever spacing the author used.

def parse_config(text) {
  var config = {}

  for line in text.lines() {
    var trimmed = line.trim()

    if trimmed.is_empty() or trimmed.starts_with('#') {
      continue
    }

    var split_at = trimmed.index_of('=')

    if split_at == -1 {
      continue
    }

    var key = trimmed[0, split_at].trim()
    var value = trimmed[split_at + 1, trimmed.length()].trim()

    config[key] = value
  }

  return config
}

var source = '# server settings
host = localhost
port   =   8080

# empty lines and comments are skipped
name = zuri app
'

var config = parse_config(source)

echo config.host
echo config.port.to_number() + 1
echo config.name
echo config.length()

localhost
8081
zuri app
3

Three things in there are worth naming. lines() handles both \n and \r\n, so the same code reads a file written on Windows. index_of() returning -1 is checked explicitly rather than relied on for truthiness, because -1 is falsy and so is 0 — and 0 is a legitimate position. And every value arrives as a string, because that is what text is; to_number() is how you leave.

Numbers

There is one numeric type, number, and it is a 64-bit IEEE-754 double. Integers and fractions are the same type, and the distinction you care about is whether a particular value happens to be integral.

Writing a Number

There are five ways to write a numeric literal, and they all produce the same type:

echo 42
echo 3.5
echo 0b1011
echo 0c17
echo 0xff
echo 6.02e23
echo 1.5e-3

42
3.5
11
15
255
602000000000000000000000
0.0015

0b is binary, 0c is octal, and 0x is hexadecimal. The letters in a hexadecimal literal may be either case, so 0xff and 0xFF are the same number. Note that octal is 0c, not the 0o some other languages use.

The exponent form takes e or E, and the exponent may be negative. 1e3 is 1000; the mantissa needs no decimal point. Note that the exponent is a way of writing the literal, not a property the value keeps: 6.02e23 prints as its full decimal expansion, because that is the number it is.

Digit Separators

An underscore between digits is ignored, which makes long numbers readable:

echo 1_000_000
echo 1_0.5_5

1000000
10.55

Separators work in decimal literals only. 0xdead_beef and 0b1010_1010 are syntax errors, not clever formatting.

Two Forms That Do Not Exist

A literal needs a digit on both sides of its decimal point. Neither of these parses:

echo .5
echo 5.

Write 0.5 and 5.0. The second case matters more than it looks, because 5. is also how a method call on a literal starts — which is the subject of the next-but-one section.

Methods, Not Functions

Everything you would reach into a math library for is a method on the number:

echo 2.sqrt()
echo 8.log2()
echo 100.log10()
echo 100.log()
echo 1.exp()
echo 2.cbrt()

1.4142135623730951
3
2
4.605170185988092
2.718281828459045
1.2599210498948732

log() is the natural logarithm. There is also log1p() and expm1() for the precision-sensitive forms near zero.

The full trigonometric set is there: sin, cos, tan, asin, acos, atan, atan2, and the hyperbolic sinh, cosh, tanh, asinh, acosh, atanh.

echo 1.atan2(1)

0.7853981633974483

Calling a Method on a Literal

A numeric literal takes a method directly. No parentheses, no temporary variable, in every base and with a decimal point or without:

echo 2.sqrt()
echo 3.7.round()
echo 255.hex()
echo 0xff.bin()
echo 1e3.int()
echo 2n.bits()

1.4142135623730951
4
ff
11111111
1000
2

There is exactly one case where you need parentheses, and it is a negative literal. A method call binds tighter than unary minus, so the minus applies to the result rather than to the number:

echo -3.abs()
echo (-3).abs()

-3
3

-3.abs() is -(3.abs()), which is -3. When the receiver is negative, parenthesise it — or put it in a variable, where the question disappears:

var n = -3

echo n.abs()

3

The same rule covers any expression you want to call a method on: wrap it, because the call would otherwise bind to the last term alone.

echo (1 / 0).is_inf()
echo (2 ** 10).hex()

true
400

Rounding

echo 2.5.ceil()
echo 2.5.floor()
echo 2.5.trunc()
echo 2.5.int()
echo (-2.5).int()

3
2
2
2
-2

trunc() and int() both drop the fractional part, rounding towards zero.

round() rounds half away from zero:

echo 2.5.round()
echo 3.5.round()
echo (-2.5).round()

3
4
-3

fixed() rounds to a number of decimal places and gives you a number back:

echo 2.567.fixed(2)

2.57

fraction() gives the digits after the decimal point as a whole number:

echo 2.567.fraction()

567

Sign, Magnitude and Comparison

echo (-5).sign()
echo (-3).abs()
echo 5.max(9)
echo 5.min(9)

-1
3
9
5

sign() is -1, 0 or 1.

Bases and Characters

echo 255.bin()
echo 255.oct()
echo 255.hex()
echo 65.chr()

11111111
377
ff
A

chr() turns a code point into a one-character string; 'A'.ord() goes back the other way.

The Special Values

echo (0 / 0).is_nan()
echo (1 / 0).is_inf()
echo 1.is_finite()

true
true
true

NaN is falsy, like zero, so var x = a / b or fallback replaces the NaN from a 0 / 0 with the fallback. Test with is_nan() when you need to tell the two apart.

NaN is also not equal to itself, as the standard requires, so x == x is a valid way to spot one.

Other Methods

factorial() for small integers, to_string(), to_bool() and to_bigint() for conversion.

echo 5.factorial()
echo 17.to_bigint()

120
17n

The math Module

Constants live in math, because a constant is not a method on anything:

import math

echo math.PI
echo math.E
echo math.Infinity
echo math.NaN

3.141592653589793
2.718281828459045
inf
NaN

It also carries LOG_2, LOG_10, LOG_2_E, LOG_10_E, ROOT_2, ROOT_3 and ROOT_HALF.

Bigints

When 2^53 is not enough, use a bigint. Write one with an n suffix:

var a = 2n ** 100n
echo a
echo a.bits()

1267650600228229401496703205376n
101

Bigints are arbitrary precision. They never overflow and never lose a digit.

They also never mix with numbers implicitly:

catch {
  echo 5n + 3
} as e {
  echo e.message
}

operator '+' not defined for call signature (bigint, number)

Convert explicitly, in whichever direction you need:

echo 5.to_bigint() * 2n
echo (2n ** 100n).to_number()

10n
1267650600228229400000000000000

Going to number is lossy once you are past 2^53, which is the whole reason bigints exist. Going the other way is exact.

The same separation holds in type annotations. bigint is a type name alongside number and int, and it accepts nothing else:

def scale(n: bigint, factor: number) {
  return n * factor.to_bigint()
}

echo scale(2n, 50)

catch {
  scale(2, 50)
} as e {
  echo e.message
}

100n
scale() expects parameter 'n' (argument 1) to be a bigint, got number

The number-theory methods are the reason bigints are worth having:

echo 100n.gcd(75n)
echo 100n.lcm(75n)
echo 2n.modpow(10n, 1000n)
echo 3n.modinv(11n)
echo 144n.sqrt()

25n
300n
24n
4n
12n

modpow(exponent, modulus) is the operation every public-key algorithm is built on, and it is computed without ever materialising the full power. modinv gives the modular multiplicative inverse.

There is also nth_root(), cbrt(), bit(), set_bit(), trailing_zeros(), is_zero(), is_even(), is_odd(), abs(), sign(), max(), min(), pow(), and bin()/oct()/hex().

A bigint is the right choice when exactness past 2^53 is the point: cryptography, currency in minor units, factorials, identifiers that must survive a round trip. For everything else — measurements, coordinates, counters, ratios — a number is the type you want.

Lists

A list is an ordered, growable sequence. It holds values of any type, including other lists, and it grows and shrinks as you work with it.

var items = [3, 1, 4, 1, 5]
var mixed = [1, 'two', [3], { four: 4 }]
var empty = []

echo items.length()
echo mixed[3].four
echo empty.is_empty()

5
4
true

Lists carry 39 methods, and they fall into six groups: reading, searching, adding and removing, ordering, transforming, and walking. This section takes them in that order. The one distinction to keep in mind throughout is whether a method mutates the list you called it on or returns a new one, because Zuri’s lists do both and the method names do not tell you which.

Reading

var l = [3, 1, 4, 1, 5]

echo l.length()
echo l.is_empty()
echo l[0]
echo l[-1]
echo l.first()
echo l.last()
echo l[1, 3]

5
false
3
5
3
5
[1, 4]

Indexing

An index counts from zero, and a negative index counts back from the end:

var l = ['a', 'b', 'c', 'd']

echo l[0]
echo l[3]
echo l[-1]
echo l[-4]

a
d
d
a

l[-1] is the last element, which saves writing l[l.length() - 1] everywhere.

Indexing out of range raises rather than returning nil:

var l = [1, 2, 3]

catch {
  echo l[99]
} as e {
  echo e.message
}

index 99 out of bounds (length 3)

get() is the form that can fall back, but only when you give it something to fall back to. get(i) with one argument raises exactly like l[i] does:

var l = [1, 2, 3]

echo l.get(1)
echo l.get(99, 'missing')

catch {
  echo l.get(99)
} as e {
  echo e.message
}

2
missing
list index 99 out of range at get()

Slicing

l[a, b] takes the elements from a up to but not including b, and gives you a new list:

var l = [1, 2, 3, 4, 5]

echo l[1, 3]
echo l[, 3]
echo l[3, ]
echo l[-2, ]

[2, 3]
[1, 2, 3]
[4, 5]
[4, 5]

Either bound may be left out: l[, b] starts at the beginning and l[a, ] runs to the end. Negative bounds count from the end, just as an index does.

A slice checks its bounds, exactly as an index does. Running past the end raises rather than returning what it can:

catch {
  echo [1, 2, 3][1, 99]
} as e {
  echo e.message
}

slice bounds 1..99 out of range (length 3)

The one bound that is always legal is length() itself, since a slice’s upper bound is exclusive. l[0, l.length()] is the whole list, and l[3, 3] on a three-element list is empty rather than an error.

var l = [1, 2, 3]

echo l[0, l.length()]
echo l[3, 3]

[1, 2, 3]
[]

This same rule governs string slicing, which is why Strings uses s[split_at + 1, s.length()] rather than a large number to mean “the rest”.

A slice is a copy. Changing one does not touch the other:

var original = [1, 2, 3]
var part = original[0, 2]

part[0] = 99

echo original
echo part

[1, 2, 3]
[99, 2]

Nested Lists

A list holds lists, and indexes chain:

var grid = [[1, 2], [3, 4], [5, 6]]

echo grid[1]
echo grid[1][0]
echo grid.length()
echo grid[1].length()

[3, 4]
3
3
2

grid.length() counts rows, not elements. There is no two-dimensional index; grid[1, 0] is a slice from row one to row zero, which is empty.

Combining Lists

Concatenation with +

+ joins two lists into a new one, leaving both operands alone:

var a = [1, 2]
var b = [3]

echo a + b
echo a
echo b

[1, 2, 3]
[1, 2]
[3]

That is the difference between + and extend(): a + b builds a third list, while a.extend(b) modifies a in place and returns it. Use + when you want to keep the originals, and extend() when you are accumulating.

Repetition with *

* repeats a list a whole number of times:

echo [1, 2] * 3
echo [0] * 5

[1, 2, 1, 2, 1, 2]
[0, 0, 0, 0, 0]

[0] * 5 is the idiom for a fixed-size list of a starting value, and it is worth knowing before you write the loop.

The count behaves exactly as it does for strings: zero and any negative number both produce an empty list, and a fractional count is truncated.

echo [1] * 0
echo [1] * -3

[]
[]

There is one trap. Repetition copies the elements, and when an element is itself a list, all the copies are the same list:

var grid = [[0, 0]] * 3

grid[0][0] = 9

echo grid

[[9, 0], [9, 0], [9, 0]]

One assignment changed every row, because there is only one row. Build nested structure with a loop, or with map():

var grid = 0..3.to_list().map(@(i) => [0, 0])

grid[0][0] = 9

echo grid

[[9, 0], [0, 0], [0, 0]]

Comparing Lists

== compares lists by value, element by element, however deeply they nest:

echo [1, 2] == [1, 2]
echo [1, [2, 3]] == [1, [2, 3]]
echo [1, 2] == [2, 1]
echo [1, 2] == [1, 2, 3]

true
true
false
false

Order matters and length matters. To compare two lists as sets, sort copies of them first, or use the set module from Chapter 13.

Searching

var l = [3, 1, 4, 1, 5]

echo l.contains(4)
echo l.index_of(1)
echo l.count(1)

true
1
2

index_of() gives -1 when the value is absent. last_index_of() searches from the other end:

var l = [3, 1, 4, 1, 5]

echo l.index_of(1)
echo l.last_index_of(1)
echo l.last_index_of(1, 2)
echo l.last_index_of(9)

1
3
1
-1

Both take a second argument bounding where a match may sit, so the pair splits the list at one index: index_of(x, n) finds the first match at or after n, last_index_of(x, n) the last one at or before it. Both compare by value, so a list of dictionaries can be searched with a dictionary literal.

Adding and Removing

These mutate the list in place:

var l = [3, 1, 4]

l.insert(9, 1)
echo l
echo l.shift()
echo l

[3, 9, 1, 4]
3
[9, 1, 4]

var l = [1, 2, 3, 4, 5]
echo l.delete(1, 3)
echo l

3
[1, 5]

Note that delete() takes a from and a to, both inclusive, and returns the number of elements removed rather than the list.

Ordering

var l = [3, 1, 2]

echo l.sort()
echo l
echo l.reverse()
echo l

[1, 2, 3]
[1, 2, 3]
[3, 2, 1]
[1, 2, 3]

Look closely at those two. sort() mutates and returns the list. reverse() returns a new list and leaves the original alone. That asymmetry is the single most common source of list bugs in Zuri code.

sort() takes no comparator. To sort by a computed key, decorate, sort, and undecorate:

var people = [{ name: 'Ada', age: 36 }, { name: 'Bob', age: 24 }]

var by_age = people
  .map(@(p) => [p.age, p.name])
  .sort()
  .map(@(pair) => pair[1])

echo by_age

[Bob, Ada]

Transforming

Every one of these returns a new list and leaves the receiver untouched:

var l = [1, 2, 3, 4]

echo l.map(@(x) => x * 2)
echo l.filter(@(x) => x > 2)
echo l.unique()
echo l.compact()
echo l.take(2)
echo l.clone()

[2, 4, 6, 8]
[3, 4]
[1, 2, 3, 4]
[1, 2, 3, 4]
[1, 2]
[1, 2, 3, 4]

compact() drops nil entries:

echo [1, nil, 2, nil].compact()

[1, 2]

reduce() folds the list down to one value. With no initial value it starts from the first element:

echo [1, 2, 3].reduce(@(acc, x) => acc + x)
echo [1, 2, 3].reduce(@(acc, x) => acc + x, 100)

6
106

partition() splits in one pass, matches first:

echo [1, 2, 3, 4].partition(@(x) => x % 2 == 0)

[[2, 4], [1, 3]]

Finding

var l = [1, 2, 3]

echo l.find(@(x) => x > 1)
echo l.find_index(@(x) => x > 1)
echo l.find_last(@(x) => x > 1)
echo l.find_last_index(@(x) => x > 1)
echo l.find_all(@(x) => x > 1)

2
1
3
2
[2, 3]

Asking About Every Element

echo [1, 2, 3].every(@(x) => x > 0)
echo [1, 2, 3].some(@(x) => x > 2)

true
true

some() stops at the first match; every() stops at the first failure.

Walking

There are four ways to visit every element, and they are not interchangeable. Pick by what you need in the body.

for, When You Want the Values

for value in ['a', 'b', 'c'] {
  echo value
}

a
b
c

This is the default. Reach for it whenever the position does not matter.

for With Two Variables, When You Want the Index Too

for index, value in ['a', 'b', 'c'] {
  echo '${index}: ${value}'
}

0: a
1: b
2: c

With two variables you get the key first and the value second, and for a list the key is the index. No call to length(), no manual counter.

iter, When You Need Control of the Position

var items = ['a', 'b', 'c']

iter var i = 0; i < items.length(); i++ {
  echo '${i}: ${items[i]}'
}

0: a
1: b
2: c

iter costs more typing and earns it only when the traversal is not one step forward per pass: walking backwards, walking in twos, comparing an element with its neighbour, or advancing the index from inside the body.

var items = ['a', 'b', 'c', 'd']

iter var i = items.length() - 1; i >= 0; i-- {
  echo items[i]
}

iter var i = 0; i < items.length(); i += 2 {
  echo items[i]
}

d
c
b
a
a
c

each(), When You Have a Function Already

[10, 20].each(@(value, index) {
  echo '${index}: ${value}'
})

0: 10
1: 20

each() takes a function, which makes it the one that composes: it chains onto a map() or a filter() without a temporary variable, and it accepts a function you already have by name.

Watch the argument order. each() hands the callback the value first and the index second, which is the opposite of for. Every list callback in this chapter follows the same rule — map, filter, find, some, every all take (value, index) — so it is one thing to remember rather than several. for is a loop over key-value pairs; each is a callback over values that happens to tell you where it is.

break and continue work inside for and iter. They do not exist inside an each() callback; return there ends that one call, not the walk. When you need to stop early, use a loop, or find() / some(), which stop on their own.

Combining

echo ['a', 'b'].zip([1, 2])
echo [1, 2, 3].zip_from([[4, 5, 6]])

[[a, 1], [b, 2]]
[[1, 4], [2, 5], [3, 6]]

zip() pairs with one other list. zip_from() takes a list of lists and zips across all of them at once.

Lists Are References

Assigning a list does not copy it:

var a = [1, 2]
var b = a
b.append(3)
echo a

[1, 2, 3]

Use clone() when you need an independent copy. The clone is shallow: nested lists inside it are still shared.

var original = [[1, 2], 3]
var copy = original.clone()

copy[1] = 99
copy[0].append(4)

echo original
echo copy

[[1, 2, 4], 3]
[[1, 2, 4], 99]

Replacing the top-level 3 affected only the copy. Appending to the nested list affected both, because both lists point at the same inner list. When you need a deep copy, copy the levels you care about yourself.

Mutating or Not: The Summary

This is the table to come back to.

sort() is the one that catches people out: it is in the left column, and it also returns the list, so var sorted = items.sort() leaves items sorted too. If you need both orders, clone first:

var items = [3, 1, 2]
var sorted = items.clone().sort()

echo items
echo sorted

[3, 1, 2]
[1, 2, 3]

A Worked Example

A tiny report generator: take a list of records, drop the incomplete ones, group what is left, and print a summary. It uses filter, map, reduce, sort and each together, which is how they usually show up.

var sales = [
  { region: 'north', amount: 120 },
  { region: 'south', amount: 80 },
  { region: 'north', amount: 45 },
  { region: 'east', amount: nil },
  { region: 'south', amount: 200 },
]

def totals_by_region(records) {
  var totals = {}

  records
    .filter(@(r) => r.amount != nil)
    .each(@(r) {
      totals[r.region] = totals.get(r.region, 0) + r.amount
    })

  return totals
}

var totals = totals_by_region(sales)
var grand = totals.values().reduce(@(acc, n) => acc + n, 0)

totals
  .to_list()[0]
  .sort()
  .each(@(region) {
    echo '${region.rpad(6)} ${totals[region]}'
  })

echo 'total  ${grand}'

north  165
south  280
total  445

east is absent from the report, not present with a zero, because its one record was filtered out before any accumulating happened and nothing ever created the key. That is usually what you want from a report; when it is not, seed the dictionary with every region first.

Two other details are worth pulling out. totals.get(r.region, 0) supplies a starting value for a key that does not exist yet, which is what turns a dictionary into an accumulator. And totals.to_list()[0] takes the keys — to_list() returns keys and values as two parallel lists — which are then sorted so the report comes out in a stable order rather than in whatever order the records happened to arrive.

Dictionaries

A dictionary maps keys to values and remembers the order you inserted them.

var user = { name: 'Ada', age: 36 }
var empty = {}

A bare word key is a string, so { name: ... } and { 'name': ... } are the same. Keys may also be numbers:

echo { 1: 'one', 2.5: 'two-point-five' }

{1: one, 2.5: two-point-five}

A key that is a bare identifier is always taken as that literal name. To compute a key, make it an expression the parser cannot mistake for a name, which in practice means wrapping it in parentheses:

var key = 'dynamic'

echo { (key): 1 }
echo { 'a' + 'b': 2 }

{dynamic: 1}
{ab: 2}

Assigning through brackets is usually clearer:

var d = {}
d[key] = 3
echo d

{dynamic: 3}

Shorthand Keys

When a key and the variable holding its value have the same name, write it once:

var name = 'Ada'
var age = 36

echo { name, age }

{name: Ada, age: 36}

{ name, age } means exactly { name: name, age: age }. This comes up constantly in functions that build a result out of locals they have just computed, and Zuri code uses the shorthand whenever the names line up.

Nesting

A value may be another dictionary, or a list, to any depth. Access chains:

var config = {
  server: { host: 'localhost', port: 8080 },
  tags: ['web', 'internal'],
}

echo config.server.host
echo config['server']['port']
echo config.tags[0]

localhost
8080
web

Dot and bracket access mix freely, because they are the same operation. Use the dot when the key is a fixed identifier and brackets when it is computed, contains punctuation, or is a number.

Reading

Dot and bracket access are the same operation:

var user = { name: 'Ada', age: 36 }

echo user.name
echo user['name']
echo user.length()
echo user.is_empty()
echo user.keys()
echo user.values()

Ada
Ada
2
false
[name, age]
[Ada, 36]

Reading a key that is not there raises a PropertyError. get() is the safe form:

echo user.get('name')
echo user.get('nope', 'default')
echo user.contains('age')

Ada
default
true

With no fallback, get() on a missing key returns nil.

Writing

var user = { name: 'Ada' }

user.set('city', 'London')
user.age = 36
user['country'] = 'UK'

echo user

{name: Ada, city: London, age: 36, country: UK}

Assignment through a dot, a bracket or set() all do the same thing, and all three create the key if it does not exist. add() is a synonym for set().

To take a key back out:

echo user.remove('city')
echo user.contains('city')

London
false

remove() returns the value that was there.

clear() empties the dictionary.

Merging

var defaults = { host: 'localhost', port: 8080 }
var given = { port: 9000 }

defaults.extend(given)
echo defaults

{host: localhost, port: 9000}

extend() mutates the receiver and the right-hand side wins on conflicts. There is no + on dictionaries.

Transforming

var user = { name: 'Ada', age: 36, city: nil }

echo user.compact()
echo user.filter(@(value, key) => key == 'name')
echo user.some(@(value, key) => value == 36)
echo user.every(@(value, key) => value != nil)
echo user.reduce(@(acc, value, key) => acc + 1, 0)

{name: Ada, age: 36}
{name: Ada}
true
false
3

compact() drops entries whose value is nil.

Every callback here takes value, then key, the same order lists use.

Walking

Every form below visits the pairs in insertion order, which is the order they were first added, not the order they were last written to.

for With Two Variables, the Usual Form

var user = { name: 'Ada', age: 36 }

for key, value in user {
  echo '${key} = ${value}'
}

name = Ada
age = 36

Key first, value second. This is what you want almost every time.

for With One Variable Gives You the Values

var user = { name: 'Ada', age: 36 }

for value in user {
  echo value
}

Ada
36

This is worth stating plainly, because the equivalent loop in several other languages hands you the keys. In Zuri, one variable is always the value, whatever you are iterating.

iter Over the Keys, When You Need an Index

var user = { name: 'Ada', age: 36 }
var keys = user.keys()

iter var i = 0; i < keys.length(); i++ {
  echo '${i}. ${keys[i]} = ${user[keys[i]]}'
}

0. name = Ada
1. age = 36

A dictionary has no positional index of its own, so iter walks the key list instead. Reach for it when you need to number the output, or to look ahead to the next key.

each(), With a Function

var user = { name: 'Ada', age: 36 }

user.each(@(value, key) {
  echo '${key} -> ${value}'
})

name -> Ada
age -> 36

The callback receives the value first and the key second — the reverse of for, matching every other each() in the language.

Walking Just One Side

var user = { name: 'Ada', age: 36 }

for key in user.keys() {
  echo key
}

echo user.values()

name
age
[Ada, 36]

keys() and values() each return a plain list, so everything from Lists applies: sort them, filter them, reduce them. Sorting keys() is how you get output in a stable order regardless of insertion.

Converting

var user = { name: 'Ada', age: 36 }

echo user.to_list()
echo user.find_key('Ada')
echo user.clone()

[[name, age], [Ada, 36]]
name
{name: Ada, age: 36}

to_list() gives you two parallel lists, keys then values, not a list of pairs. find_key() searches by value and returns the first key holding it.

Dictionaries of Functions

A dictionary value can be a function, and that turns a dictionary into a dispatch table: a set of named behaviours you can choose between at runtime by looking a name up. It is the structure that replaces eval(), and it is worth knowing well.

def plus(a, b) {
  return a + b
}

var ops = {
  plus: plus,
  minus: @(a, b) => a - b,
  times: @(a, b) { return a * b },
}

All three forms are equivalent: a named function by name, an arrow function, and an anonymous function with a body.

Calling One

This is the part that surprises people, so it comes first. You cannot call one with a dot in a single step:

echo ops.plus(1, 2)

Unhandled TypeError: object of type dict does not define method 'plus'

A dot followed by a call looks for a method on the dictionary itself — length(), keys(), get() and the rest — not for a value stored under that key. Dictionaries have no method called plus, so the call fails.

There are two forms that do work. Read the function out first:

def plus(a, b) {
  return a + b
}

var ops = { plus: plus, minus: @(a, b) => a - b }

var chosen = ops.plus

echo chosen(1, 2)

3

Or index with brackets and call the result:

var ops = { plus: @(a, b) => a + b, minus: @(a, b) => a - b }

echo ops['minus'](5, 2)

3

The bracket form is the one to reach for when the key is computed, which is the whole point of a dispatch table:

var ops = {
  plus: @(a, b) => a + b,
  minus: @(a, b) => a - b,
  times: @(a, b) => a * b,
}

for name in ['plus', 'minus', 'times'] {
  echo '${name}: ${ops[name](6, 3)}'
}

plus: 9
minus: 3
times: 18

Beware of Names That Are Already Methods

A dictionary’s own methods take priority over its keys when you use a dot call. Storing a function under add, keys, get, length or any other method name produces a call that succeeds and does the wrong thing:

def plus(a, b) {
  return a + b
}

var d = { add: plus }

echo d.add(1, 2)
echo d.keys()

nil
[add, 1]

d.add(1, 2) called the dictionary’s own add(), which is a synonym for set() — so it stored the key 1 with the value 2 and returned nil. Nothing raised. The only sign is the extra key in the output.

Two habits avoid this entirely: use bracket calls for dispatch tables, and avoid method names as keys. Appendix E lists every name a dictionary already uses.

A Dispatch Table in Practice

The pattern is a table of handlers, a lookup with a fallback, and a call:

def _unknown(args) {
  return 'unknown command: ${args[0]}'
}

var commands = {
  greet: @(args) => 'hello, ${args[1]}',
  add: @(args) => args[1].to_number() + args[2].to_number(),
  version: @(args) => '1.0.0',
}

def run(line) {
  var args = line.split(' ')
  var handler = commands.get(args[0], _unknown)

  return handler(args)
}

echo run('greet ada')
echo run('add 2 40')
echo run('version')
echo run('explode')

hello, ada
42
1.0.0
unknown command: explode

commands.get(args[0], _unknown) is doing the work. A key that exists gives you its handler; one that does not gives you the fallback, so there is no separate contains() check and no branch for the error case.

The important property is that only the handlers in the table can ever run. A user typing anything at all selects one of four functions you wrote, or the fallback. That is the difference between a program that handles input and one that executes it, and it is why Zuri has no eval(). Chapter 21 covers the reasoning.

Storing Methods

zuri.reflect.bind_method() puts an instance’s method in a table with the instance still attached:

import zuri

class Counter {

  @new() {
    self.n = 0
  }

  increment() {
    self.n++
    return self.n
  }
}

var counter = Counter()

var actions = { up: zuri.reflect.bind_method(counter, 'increment') }

echo actions['up']()
echo actions['up']()
echo counter.n

1
2
2

The bound method keeps its receiver, so calling it through the table changes the counter it came from.

Comparing Dictionaries

== compares dictionaries by value, and order is not part of the comparison:

echo { a: 1 } == { a: 1 }
echo { a: 1 } == { a: 2 }
echo { a: 1, b: 2 } == { b: 2, a: 1 }

true
false
true

A dictionary remembers its insertion order for iteration, but two dictionaries with the same pairs in different orders are equal. That is the opposite of lists, where order is the whole point.

Dictionaries Are References

Like lists, assigning a dictionary shares it. clone() gives you a shallow copy.

Dictionaries and Objects

A dictionary is the right shape for data with a variable set of keys: configuration, a parsed JSON document, a set of HTTP headers. When the keys are fixed and there is behaviour attached to them, that is a class. Chapter 6 covers the difference.

A Worked Example

Dictionaries are the natural shape for counting, grouping and indexing. This example does all three over a list of log lines: it counts how often each level appears, groups the messages under their level, and builds an index from a request id back to the line that mentioned it.

var lines = [
  'INFO  req=a1 started',
  'WARN  req=a1 slow upstream',
  'INFO  req=b2 started',
  'ERROR req=b2 upstream refused',
  'INFO  req=a1 finished',
]

var counts = {}
var grouped = {}
var by_request = {}

for line in lines {
  var parts = line.split(' ').filter(@(p) => p != '')
  var level = parts[0]
  var request = parts[1].replace('req=', '', false)
  var message = ' '.join(parts[2, parts.length()])

  counts[level] = counts.get(level, 0) + 1

  if !grouped.contains(level) {
    grouped[level] = []
  }

  grouped[level].append(message)

  if !by_request.contains(request) {
    by_request[request] = []
  }

  by_request[request].append(level)
}

echo counts
echo grouped.ERROR
echo by_request.a1
echo by_request.get('zz', ['no such request'])

{INFO: 3, WARN: 1, ERROR: 1}
[upstream refused]
[INFO, WARN, INFO]
[no such request]

Four habits in there are worth taking away.

counts.get(level, 0) + 1 is the counting idiom. get() with a fallback means you never have to check whether the key exists before adding to it.

if !grouped.contains(level) { grouped[level] = [] } is the grouping idiom, and it has to be spelled out because get() would hand back a fresh default list each time rather than one you can keep appending to.

grouped.ERROR and by_request.a1 read keys with a dot, which works because both are valid identifiers. by_request['b2'] would be needed if the key were computed or awkward.

And the whole thing preserves order. counts came out INFO, WARN, ERROR — the order those levels were first seen, not alphabetical and not arbitrary.

Ranges and Iteration

Ranges

a..b builds a range value: the integers from a up to but not including b.

.. binds tighter than a method call, so a range takes a method directly with no parentheses around it:

echo 1..5.to_list()
echo 1..10.step(3).get_step()

[1, 2, 3, 4]
3

Parenthesise only when the bounds are themselves expressions, since .. takes primaries: (n * 2)..(n * 3).

A property access and a call are expressions too, so 0..self.size and 0..items.length() are (0..self).size and (0..items).length(). Write 0..(self.size) and 0..(items.length()) when the bound is the property rather than the range.

This is the price of the line above it. .. has to bind tighter than . for 1..10.step(3) to mean a range that steps, and once it does, there is no way for 0..self.step(5) to mean the instance’s own step instead. The parentheses say which one is meant, and the compiler cannot guess.

var r = 1..10

echo r
echo r.lower()
echo r.upper()
echo r.range()

1..10
1
10
9

range() is the distance between the bounds.

A range is a value, not loop syntax. Store it, pass it to a function, return it:

def page(number) {
  var size = 20
  return (number * size)..((number + 1) * size)
}

echo page(2)

40..60

Counting Down

Write the larger bound first and the range runs backwards:

for i in 10..1 {
  echo i
}

10
9
8
7
6
5
4
3
2

The rule is the same in both directions: the first bound is included, the second is not.

Stepping

for i in 1..10.step(3) {
  echo i
}

1
4
7

step() gives back a new range carrying that stride. get_step() reads it; the default is 1.

to_list() materialises a range into a list at stride one, ignoring any step you set:

echo 1..5.to_list()

[1, 2, 3, 4]

Membership

within() tests against the bounds inclusively on both sides, and it normalises direction, so 10..1.within(10) and 1..10.within(10) both answer the same:

var r = 1..10

echo r.within(5)
echo r.within(10)

true
true

That differs from iteration, which excludes the upper bound. When you want “would the loop visit this number”, compare against lower() and upper() yourself.

Walking a Range

for with one variable gives you the values, and with two it gives you the position first and the value second:

for value in 3..6 {
  echo value
}

for index, value in 3..6 {
  echo '${index}: ${value}'
}

3
4
5
0: 3
1: 4
2: 5

The index counts from zero regardless of where the range starts, which is what makes it useful: 3..6 yields values 3, 4, 5 at positions 0, 1, 2.

loop() is the callback form. It honours the step and the direction:

25..18.loop(@(i) { print('${i} ') })
print('\n')

25 24 23 22 21 20 19 

An iter loop needs no range at all — its three clauses already say everything a range says, and more, since the step can be any expression:

iter var i = 3; i < 6; i++ {
  echo i
}

3
4
5

Use a range with for when the bounds are the interesting part, and iter when the stepping is.

What Is Iterable

for ... in works on:

• lists, giving index and value
• dictionaries, giving key and value, in insertion order
• strings, giving character position and character
• bytes, giving index and the numeric byte
• ranges, giving position and value
• any class that defines @key() and @value()

is_iterable() answers the question for any value:

echo is_iterable([1, 2])
echo is_iterable('text')
echo is_iterable(42)

true
true
false

The Iterator Protocol

for is not magic. It desugars into a loop over two method calls.

Given for value in thing, Zuri evaluates thing once, then repeats:

1. key = thing.@key(key), starting from nil
2. stop if key is nil
3. value = thing.@value(key)
4. run the body

So @key(previous) answers “what comes after this one?”, returning nil when there is nothing left, and @value(key) answers “what is stored here?”.

Everything built in implements this. So can your own classes, which is what Chapter 6 shows.

Because the iterable is evaluated exactly once, this is safe:

for line in read_the_whole_file() {
  echo line
}

The function runs once, not once per line.

Functions

A function is a piece of behaviour with a name, a list of parameters, and a result. You have been calling them since Chapter 1; this chapter is about writing them.

Functions in Zuri are values. You can put one in a list, hand it to another function, return one from a function, store one in a dictionary, and call whatever comes back:

def double(n) {
  return n * 2
}

var operations = { twice: double, thrice: @(n) => n * 3 }

var chosen = operations.twice

echo chosen(5)
echo operations['thrice'](5)
echo [1, 2, 3].map(double)

10
15
[2, 4, 6]

That one property is what makes map, filter, reduce, every callback in the standard library, and every route handler in Chapter 15 possible.

Note the shape of those two calls. operations.twice reads the function out of the dictionary, and then you call what you read. Writing operations.twice(5) in one step does not work: a dot followed by a call looks for a method on the dictionary, and a dictionary has no method called twice. Either read it into a variable first, as above, or index with brackets and call the result: operations['twice'](5).

This chapter covers declaring a function, the spellings an anonymous one can take, how a closure captures the variables around it, and the optional type annotations that make the runtime check arguments for you.

Defining Functions

Declaration

def greet(name) {
  return 'Hello, ' + name
}

echo greet('Zuri')

Hello, Zuri

def, a name, a parameter list in parentheses, a block. There is no return type to declare, no forward declaration, and no separate signature.

A function with no return yields nil:

def silent() {
  echo 'working'
}

echo silent()

working
nil

There are no implicit returns. The last expression in a body is not its value; if you want something back, say return.

Arity Is Not Enforced

Call a function with fewer arguments than it declares and the missing ones arrive as nil. Call it with more and the extras are dropped:

def greet(name) {
  return 'Hello, ' + name
}

echo greet()
echo greet('Zuri', 'ignored')

Hello, nil
Hello, Zuri

This is not an oversight. It is the mechanism optional parameters are built on, since there is no default-value syntax in a parameter list. You write the default in the body instead:

def greet(name, greeting) {
  greeting = greeting or 'Hello'

  return '${greeting}, ${name}!'
}

echo greet('Ada')
echo greet('Ada', 'Hi')

Hello, Ada!
Hi, Ada!

The or Trap in Defaults

Because or does the work, a legitimately falsy argument is replaced by the default. In Zuri that set includes 0, NaN, '' and false:

def indent(text, width) {
  width = width or 2

  return ' ' * width + text
}

echo '[' + indent('a') + ']'
echo '[' + indent('a', 0) + ']'

[  a]
[  a]

The caller asked for zero indentation and got two. When a falsy value is a legitimate input, test for nil explicitly:

def indent(text, width) {
  if width == nil {
    width = 2
  }

  return ' ' * width + text
}

echo '[' + indent('a') + ']'
echo '[' + indent('a', 0) + ']'

[  a]
[a]

Use or for a default when every falsy value is genuinely absent — a name, a path, a list. Use == nil for numbers and booleans.

If you want the runtime to reject a missing argument rather than default it, annotate the parameter. Type Annotations covers that.

Variadic Functions

A final parameter prefixed with ... collects every remaining argument into a list:

def count(...items) {
  return items
}

echo count()
echo count(1)
echo count(1, 2, 3)

[]
[1]
[1, 2, 3]

Three facts about what it captures are worth being precise about.

It is always a list, including when nothing was passed. count() gives [], not nil, so items.length() is safe without a check.

It captures arguments, not contents. Passing a list passes one argument, which arrives as a list nested inside the variadic list:

def count(...items) {
  return items
}

echo count([1, 2])
echo count([1, 2], 3)

[[1, 2]]
[[1, 2], 3]

... marks a parameter, not an argument: count(...list) does not parse. To call a function with a list of arguments, use apply():

def count(...args) {
  return args.length()
}

echo count.apply([1, 2, 3])

3

When a function should accept a collection, though, take the list as an ordinary parameter and skip both.

Named parameters bind first. A variadic can follow named ones, and it takes whatever is left over:

def named(a, ...rest) {
  return [a, rest]
}

echo named()
echo named(1)
echo named(1, 2, 3)

[nil, []]
[1, []]
[1, [2, 3]]

The variadic must be last. def mid(a, ...rest, b) is a syntax error, because there is no rule that could decide how many arguments rest should keep.

A practical use is a function that formats an arbitrary number of pieces:

def log_line(level, ...parts) {
  return '[${level}] ' + ' '.join(parts)
}

echo log_line('warn', 'disk', 'almost', 'full')
echo log_line('info')

[warn] disk almost full
[info] 

Where a def Binds

A def scopes exactly like a var. Written at the top level of a file it binds a module-level name. Written anywhere else it binds a local of the block it appears in, and it goes away with that block:

def outer() {
  def helper() {
    return 'from helper'
  }

  return helper()
}

echo outer()

catch {
  helper()
} as e {
  echo e.message
}

from helper
undefined global 'helper'

A helper defined inside a function belongs to that function. Nothing outside can reach it, and nothing outside can be broken by it.

That extends to any block, not just a function body:

def choose(verbose) {
  if verbose {
    def describe(n) {
      return 'the number ${n}'
    }

    return describe(7)
  }

  return '7'
}

echo choose(true)
echo choose(false)

the number 7
7

Calling One Helper From Another

Helpers declared next to each other can call each other, in either direction:

def parity(n) {
  def even(k) {
    if k == 0 {
      return true
    }

    return odd(k - 1)
  }

  def odd(k) {
    if k == 0 {
      return false
    }

    return even(k - 1)
  }

  return even(n)
}

echo parity(10)
echo parity(7)

true
false

even mentions odd before odd is written, and that works because the compiler reserves a slot for every def in a block before it compiles any of them. What it does not do is move the declaration: until the def line itself runs, the slot holds nil, so calling a helper from above its declaration raises.

A helper can also call itself:

def factorial_of(n) {
  def factorial(k) {
    if k <= 1 {
      return 1
    }

    return k * factorial(k - 1)
  }

  return factorial(n)
}

echo factorial_of(6)

720

A Helper Captures What Surrounds It

A nested def is a closure over the locals around it, and it outlives the call that created it:

def make_counter(start) {
  var count = start

  def bump() {
    count++
    return count
  }

  return bump
}

var bump = make_counter(10)

echo bump()
echo bump()

11
12

An anonymous function bound to a var does the same job, and is the better choice when the helper is a one-liner or is being passed straight into something else:

def outer() {
  var helper = @() => 'private'

  return helper()
}

echo outer()

private

Pick whichever reads better. A def gives the function a real name in stack traces and can recurse without the extra var; a lambda is shorter.

One Declaration Per Name

Declaring the same function name twice in one scope is a compile error:

def pick() {
  return 'first'
}

def pick() {
  return 'second'
}

SyntaxError: multiple declaration for function 'pick' found
  --> /path/to/main.zu:5:5
  |
5 | def pick() {
  |     ^

A different parameter list does not make it a different function. Zuri has no overloading: one name, one function.

def render(value) {}
def render(value, width) {}

SyntaxError: multiple declaration for function 'render' found

When you want one name to handle several shapes of input, take the extra arguments as optional and branch in the body — which is what the greeting parameter above is doing.

The check is per scope, exactly like var’s. A function declared inside another is a separate declaration in a separate scope, so the compiler allows it, and it shadows the outer one for as long as its own scope lasts:

def render() {
  return 'top level'
}

def wrapper() {
  def render() {
    return 'inner'
  }

  return render()
}

echo wrapper()
echo render()

inner
top level

wrapper’s own render is a local of wrapper. It answers every call made inside that function and disappears when the call ends, leaving the module-level render untouched.

Classes follow the same rule for their methods:

class Duplicate {
  m() {}
  m() {}
}

SyntaxError: multiple declaration for method 'm' found in class 'Duplicate'

The REPL is the one exception. Retyping a def there replaces the previous one, because correcting something you just typed is what the prompt is for.

Declaration Order

A function must be declared before the top-level line that calls it:

echo later()

def later() {
  return 'nope'
}

Unhandled UndefinedError: undefined global 'later'

There is no hoisting. Declarations execute in order, like everything else.

Inside a function body the rule does not apply, because a name is resolved when the call runs rather than when it is compiled. That is what makes mutual recursion work with no forward declaration:

def is_even(n) {
  if n == 0 {
    return true
  }

  return is_odd(n - 1)
}

def is_odd(n) {
  if n == 0 {
    return false
  }

  return is_even(n - 1)
}

echo is_even(10)
echo is_odd(7)

true
true

is_even refers to is_odd before it exists. That is fine, because the reference is resolved when is_even(10) runs, by which time both declarations have executed.

Helpers nested inside a function get the same freedom by a different route: their slots are reserved together, before any of their bodies compile. Either way, what matters is that every declaration has run by the time the first call is made.

Functions as Values

A function is a value, so it can be passed, stored and returned:

def apply_twice(f, x) {
  return f(f(x))
}

def increment(n) {
  return n + 1
}

echo apply_twice(increment, 5)
echo apply_twice(@(s) => s + '!', 'hi')

7
hi!!

What a Function Knows About Itself

Every callable carries four methods:

def named(a, b, ...c) {
  return [a, b, c]
}

echo named.name()
echo named.arity()
echo named.is_variadic()
echo named.to_string()

named
3
true
<function named(3)>

arity() counts declared parameters, the variadic one included, so a variadic function’s arity is a minimum rather than a requirement.

An anonymous function is named after the order the compiler met it:

var f = @(x) => x

echo f.name()

@anon0

A method read off an instance keeps its receiver, and counts it:

class Greeter {

  hello() {
    return 'hi'
  }
}

var bound = Greeter().hello

echo bound()
echo bound.name()
echo bound.arity()

hi
hello
1

hello() declares no parameters, and arity() reports 1, because the instance is the first one.

call()

call() invokes a function with the arguments you give it:

def add(a, b) {
  return a + b
}

echo add.call(2, 3)

5

call() takes the arguments individually, exactly as a normal call does. It is not a spread: add.call([2, 3]) passes one argument, a list. Its use is calling something whose identity you only have as a value — a handler out of a dictionary, a method from zuri.reflect — in a place where the ordinary call syntax reads badly.

Testing Callability

def f() {}

echo is_callable(f)
echo is_callable(print)
echo is_callable(Error)
echo is_callable(42)

echo is_function(f)
echo is_function(Error)

true
true
true
false
true
false

is_callable() is true for anything you can put parentheses after, classes included — calling a class constructs an instance. is_function() is narrower: true for a def, an anonymous function and a built-in, false for a class.

A Worked Example

A small pipeline builder, using most of this section: functions as values, a variadic parameter, a default, and a returned closure.

def pipeline(...stages) {
  return @(input) {
    var value = input

    for stage in stages {
      value = stage(value)
    }

    return value
  }
}

def strip(text) {
  return text.trim()
}

def collapse_spaces(text) {
  return text.replace('/\s+/', ' ')
}

def truncate(text, limit) {
  limit = limit or 20

  if text.length() <= limit {
    return text
  }

  return text[0, limit - 1] + '…'
}

var tidy = pipeline(strip, collapse_spaces, @(t) => truncate(t, 12))

echo '[' + tidy('   too    many   spaces here   ') + ']'
echo '[' + tidy('  short  ') + ']'
echo '[' + pipeline()('untouched') + ']'

[too many sp…]
[short]
[untouched]

Four things to take from it.

pipeline() takes its stages variadically and returns a closure over them, so the returned function is a new function specialised to those stages.

pipeline() with no arguments still works, because a variadic parameter is an empty list rather than nil, and a for over an empty list runs zero times.

The third stage is wrapped in @(t) => truncate(t, 12) because truncate takes two parameters and a stage takes one. That wrapper is the thing a spread operator would otherwise be for.

And limit = limit or 20 is safe here precisely because 0 is not a sensible limit. Had it been, this would need the == nil form.

Anonymous Functions and Closures

The Spellings

An anonymous function has two halves you can vary independently: how it opens, and how its body is written. That gives a small grid rather than a list to memorise.

Opening. def is the keyword; @ is its shorthand. They are the same thing.

Body. A block in braces returns with return. An arrow returns the one expression after it.

var block_long = def(x) { return x * x }
var block_short = @(x) { return x * x }

var arrow_long = def(x) => x * x
var arrow_short = @(x) => x * x

echo [block_long(3), block_short(3), arrow_long(3), arrow_short(3)]

[9, 9, 9, 9]

When there are no parameters, the empty parentheses may be dropped as well:

var a = @() { return 1 }
var b = @() => 2
var c = def() { return 3 }
var d = def() => 4
var e = @ => 5
var f = @{ return 6 }
var g = def { return 7 }
var h = def => 8

echo [a(), b(), c(), d(), e(), f(), g(), h()]

[1, 2, 3, 4, 5, 6, 7, 8]

All eight are the same construct. Which to use:

• @(x) => expr for a one-expression callback. This is what most Zuri code uses, and what the standard library is written in.
• @(x) { ... } when the body needs more than one statement.
• def(x) { ... } when the function is long enough that you want it to look like the declarations around it.
• @ => expr for a thunk — a value computed on demand, with nothing passed in.

Compare the two common ones where they actually turn up:

echo ['  a ', ' b'].map(@(t) => t.trim())

echo [1, 2, 3].filter(@(n) {
  if n == 2 {
    return false
  }

  return n > 0
})

[a, b]
[1, 3]

The arrow form has no return because the expression is the return value. Adding one is a mistake the compiler will not catch: @(x) => return x does not parse, but @(x) { x } parses and returns nil.

Anonymous functions take variadic parameters and type annotations exactly like named ones:

var sum = @(...numbers) => numbers.reduce(@(a, b) => a + b, 0)
var doubled = @(n: number) => n * 2

echo sum(1, 2, 3)
echo doubled(4)

catch {
  doubled('four')
} as e {
  echo e.message.replace('/@anon\d+/', '@anonN')
}

6
8
@anonN() expects parameter 'n' (argument 1) to be a number, got string

The real message carries a number rather than the N shown here. An anonymous function is named @anonN in the order the compiler met it in the file, which is worth knowing when one turns up in a stack trace — and worth not depending on, since inserting another anonymous function above it renumbers everything below.

Closures

A function carries the variables it referenced from its surroundings, and keeps them alive after the enclosing function has returned:

def make_counter() {
  var n = 0

  return @() {
    n++
    return n
  }
}

var a = make_counter()
var b = make_counter()

echo a()
echo a()
echo b()

1
2
1

a and b each closed over their own n. Each call to make_counter() created a fresh one.

Capture Is by Reference

A closure captures the variable, not a snapshot of its value:

def demo() {
  var total = 0
  var add = @(n) { total += n }

  add(5)
  add(10)

  return total
}

echo demo()

15

This is what makes accumulator patterns work, and it is what makes loop variables surprising. If you want a per-iteration capture, declare a fresh variable inside the loop body:

var fns = []

iter var i = 0; i < 3; i++ {
  var captured = i
  fns.append(@() => captured)
}

echo fns.map(@(f) => f())

[0, 1, 2]

captured is a new variable on each pass, so each closure gets its own.

Closures over Parameters

Parameters are captured the same way, which is the basis of partial application:

def adder(amount) {
  return @(n) => n + amount
}

var add_five = adder(5)
var add_ten = adder(10)

echo add_five(1)
echo add_ten(1)

6
11

Recursion in an Anonymous Function

An anonymous function has no name to call itself by. Bind it first:

var factorial

factorial = @(n) {
  if n <= 1 {
    return 1
  }
  return n * factorial(n - 1)
}

echo factorial(5)

120

The variable is captured by reference, so by the time the body runs, factorial is bound.

Functions Compare by Identity

def f() {}

var g = f
echo f == g
echo f == @() {}

true
false

Two separately written functions are never equal, even with identical bodies.

A Worked Example

Closures are at their most useful when a function needs to remember something between calls without that something becoming a global. Here is a rate limiter: it hands back a function that answers “may I do this now?”, and keeps its own tally where nothing else can reach it.

def make_limiter(max_per_window: number) {
  var used = 0

  return {
    allow: @() {
      if used >= max_per_window {
        return false
      }

      used++
      return true
    },

    remaining: @() => max_per_window - used,

    reset: @() {
      used = 0
    },
  }
}

var limiter = make_limiter(2)
var allow = limiter.allow
var remaining = limiter.remaining
var reset = limiter.reset

echo allow()
echo allow()
echo allow()
echo remaining()

reset()
echo allow()

true
true
false
0
true

Three separate functions share one used, because all three closed over the same variable in the same call to make_limiter. A second call to make_limiter would produce a second, independent trio.

This is the closest Zuri gets to a private field without a class, and it is worth knowing for exactly that reason: there is no way for a caller to read or write used except through the three functions you gave them.

Type Annotations

Zuri is dynamically typed, and parameters may be annotated. An annotated parameter is checked at every call, and a mismatch raises a TypeError naming the parameter, its position and what actually arrived.

def repeat(text: string, times: number) {
  return text * times
}

echo repeat('ab', 3)

catch {
  repeat(42, 3)
} as e {
  echo e.message
}

ababab
repeat() expects parameter 'text' (argument 1) to be a string, got number

The Type Names

Anything that is not one of those names is read as a class name.

number and bigint are separate, in annotations exactly as they are everywhere else. A parameter typed bigint rejects 10, and one typed number rejects 10n:

def factorial(n: bigint) {
  if n <= 1n {
    return 1n
  }

  return n * factorial(n - 1n)
}

echo factorial(25n)

catch {
  factorial(25)
} as e {
  echo e.message
}

15511210043330985984000000n
factorial() expects parameter 'n' (argument 1) to be a bigint, got number

Write bigint|number when a function genuinely takes either, and convert inside it with to_bigint().

Required by Default

A plain annotation makes the argument required. Omitting it is a TypeError, because the parameter arrives as nil:

def needs_number(x: number) {}

catch {
  needs_number()
} as e {
  echo e.message
}

needs_number() expects parameter 'x' (argument 1) to be a number, got nil

That is how you get argument checking out of a language that otherwise lets you call anything with anything.

Optional Parameters

Prefix the type with ? to allow nil:

def connect(host: string, port: ?number) {
  port = port or 8080
  echo '${host}:${port}'
}

connect('localhost')
connect('localhost', 9000)

localhost:8080
localhost:9000

?any is the same as no annotation at all, which is what an unannotated parameter gets.

Union Types

Separate alternatives with |:

def render(value: string|number|list) {
  echo value
}

render('text')
render(42)
render([1])

catch {
  render({ a: 1 })
} as e {
  echo e.message
}

text
42
[1]
render() expects parameter 'value' (argument 1) to be a string, a number, or a list, got dict

The ? goes at the front and applies to the whole union: ?string|number.

Classes and Subclasses

A class name accepts instances of that class and of anything that inherits from it:

class Point {
  @new(x, y) {
    self.x = x
    self.y = y
  }
}

def distance_from_origin(p: Point) {
  return (p.x * p.x + p.y * p.y).sqrt()
}

echo distance_from_origin(Point(3, 4))

5

This is what makes error handling readable, since every built-in error subclasses Error:

def report(e: Error) {
  echo '${e.type}: ${e.message}'
}

catch {
  raise ValueError('bad value')
} as e {
  report(e)
}

ValueError: bad value

Where Annotations Work

Annotations go on parameters: in a def, in a method, and in an anonymous function.

class Report {
  render(rows: list, title: ?string) {
    # ...
  }
}

var f = @(n: int) => n * 2

The same syntax goes on var declarations and on class fields:

var count: number = 0
var name: ?string

class Report {
  var rows: list = []
  var title: ?string
}

A variable annotation is a statement of intent. It is not checked at runtime, so the runtime will not stop you from putting a string in count. What it does is make the declaration self-documenting, and give static analysis tools something to work with: an annotated declaration tells a linter, an editor’s completion engine or a type checker exactly what belongs there, and lets them flag the assignment your eyes would otherwise have to catch.

Annotate declarations for the reader and the tooling. Annotate parameters for the runtime.

When to Annotate

Annotations are optional, and a program with none of them is perfectly ordinary Zuri. The question is where they earn their place.

Annotate a boundary. A function that receives data from outside your program — a request handler, a file parser, a public function in a module other people import — is where a wrong type first arrives. An annotation there turns a confusing failure deep in the call stack into a clear one at the door:

def parse_port(raw: string) {
  var port = raw.to_number()

  if port < 1 or port > 65535 {
    raise ValueError('port out of range: ${raw}')
  }

  return port
}

catch {
  parse_port(8080)
} as e {
  echo e.message
}

echo parse_port('8080')

parse_port() expects parameter 'raw' (argument 1) to be a string, got number
8080

Note the division of labour there. The annotation handles wrong type, and the explicit check handles wrong value. An annotation can never do the second job, because 70000 is a perfectly good number.

Annotate to replace a manual check. Any function that opens with if !is_string(x) { raise TypeError(...) } is spelling out by hand what an annotation says in one word, and the annotation produces a better message:

def shout(text: string) {
  return text.upper() + '!'
}

echo shout('hello')

HELLO!

Leave internal helpers alone if you prefer. A private function called from three places in the same file, all of which you can see, gains less. Annotate it if it documents something non-obvious; skip it if it does not.

One thing an annotation is not: a substitute for validation. text: string guarantees you have a string, not that the string is a valid email address, a well-formed date or a non-empty name. The validate module covers that job, and Chapter 13 introduces it.

Classes and Objects

A dictionary holds data. A class holds data and the behaviour that goes with it, under a name you can check for and inherit from.

class Temperature {

  @new(celsius) {
    self.celsius = celsius
  }

  fahrenheit() {
    return self.celsius * 9 / 5 + 32
  }

  to_string() {
    return '${self.celsius}C'
  }
}

var t = Temperature(100)

echo t.fahrenheit()
echo t.to_string()

212
100C

Three facts about Zuri classes shape everything in this chapter, and it is worth having them up front.

The constructor is @new. Methods whose names start with @ are decorated methods, and each one connects the class to a piece of the language’s own syntax: construction, arithmetic, comparison, iteration, JSON encoding. There is a fixed set of them, and Decorated Methods covers all of it.

Fields are reached through self. Inside a method, self is the instance. There is no bare balance that means self.balance, and no self parameter in the declaration either.

A class is sealed. The set of fields and methods is fixed when the class is declared. Nothing at runtime can add a new field to an instance or a new method to a class, and an attempt raises an error rather than quietly creating one. That rules out a family of bugs — a typo in a field name is an error, not a new field — and it rules out monkey-patching, which is a technique some languages rely on and Zuri does not offer.

Inheritance is single: a class has at most one parent, written with <. There are no interfaces, no mixins and no abstract keyword. The sections that follow show what you write instead.

Sealed does not mean unchangeable forever, though. A separate declaration written with > instead of < — a class extension — can add methods to a class after the fact, including one you did not write. Class Extensions covers it.

Defining a Class

class Account {
  var balance = 0
  var owner

  @new(owner, balance) {
    self.owner = owner
    self.balance = balance or 0
  }

  deposit(amount) {
    self.balance += amount
    return self
  }
}

• class Name { ... } declares it. PascalCase is the convention.
• var inside the body declares a field, with an optional default. A field with no default starts as nil.
• A bare name(params) { ... } is a method. There is no def keyword on methods.
• @new is the constructor.
• self is the current instance.

Creating an Instance

Call the class. There is no new keyword:

var a = Account('Ada', 50)

echo a.owner
echo a.balance

Ada
50

If the class has no @new, calling it with no arguments gives you an instance with every field at its default.

The Constructor

@new is the constructor. It runs once, when the class is called, and its job is to put the instance into a usable state — which is what Account’s did above.

It Is Optional

A class with no @new is constructed with no arguments, and every field takes its declared default:

class Settings {
  var theme = 'dark'
  var retries
}

var s = Settings()

echo s.theme
echo s.retries

dark
nil

Extra arguments to a class with no @new are ignored rather than rejected, exactly as they are for a function.

It Declares Fields

self.x = value inside @new declares a field. This is the one place in the language where assignment creates a member, and it exists so a constructor does not have to repeat every field as a var line above it:

class Point {

  @new(x, y) {
    self.x = x
    self.y = y
    self.distance = (x * x + y * y).sqrt()
  }
}

var p = Point(3, 4)

echo p.distance

5

distance was never declared with var, and it is a real field.

That power belongs to @new’s own body and nowhere else. A constructor that delegates its setup to a helper must declare those fields:

class Delayed {
  var ready          # required: setup() cannot declare it

  @new() {
    self.setup()
  }

  setup() {
    self.ready = true
  }
}

echo Delayed().ready

true

Remove the var ready line and setup() raises undefined field 'ready'.

Arguments Are Not Checked Unless You Ask

@new is a function, so the usual rules apply: missing arguments arrive as nil, extra ones are dropped. A constructor that assumes it got something fails later, in a confusing place:

class Ctor {

  @new(x) {
    self.derived = x * 2
  }
}

Ctor()

Unhandled TypeError: operator '*' not defined for call signature (nil, float)

Annotate the parameter and the failure moves to the call, where it names the problem:

class Ctor {

  @new(x: number) {
    self.derived = x * 2
  }
}

echo Ctor(5).derived

catch {
  Ctor('five')
} as e {
  echo e.message
}

10
@new() expects parameter 'x' (argument 1) to be a number, got string

Constructors are the highest-value place in a program to annotate, because a badly built object goes wrong somewhere else entirely.

Validating in the Constructor

A constructor may raise. Nothing is returned to the caller, so an object that cannot be valid never exists:

class Port {

  @new(number: number) {
    if number < 1 or number > 65535 {
      raise ValueError('port out of range: ${number}')
    }

    self.number = number
  }
}

echo Port(8080).number

catch {
  Port(99999)
} as e {
  echo '${e.type}: ${e.message}'
}

8080
ValueError: port out of range: 99999

This is worth doing whenever a class has an invariant. Every other method can then assume it holds, instead of re-checking.

@new Cannot Return a Value

Calling a class always produces an instance of that class. A return in @new ends the constructor early; it does not change what the caller gets:

class Returns {

  @new() {
    self.v = 1

    return 'this is discarded'
  }
}

echo typeof(Returns())

Returns

If you want a call that may hand back something else — a cached instance, a subclass, nil on bad input — write a static factory method and call that instead.

Methods

A method is a name(params) { ... } declaration inside the class body. There is no def keyword on it:

class Account {

  @new(owner, balance) {
    self.owner = owner
    self.balance = balance
  }

  deposit(amount) {
    self.balance += amount
    return self
  }
}

var a = Account('Ada', 50)

a.deposit(25).deposit(25)

echo a.balance

100

deposit returns self, which is what makes the chain work. Returning self from a mutator is a common Zuri idiom.

Inside a method, self is required to reach a field or another method. There is no implicit receiver:

class Greeter {
  var name = 'world'

  greet() {
    return 'hello ' + self.name
  }
}

Writing name there would look for a local or a global, not a field.

Fields Are Declared, Not Discovered

The set of fields is fixed when the class is declared. Two things follow from that.

First, assigning to a field that was never declared is an error:

class Account {
  var balance = 0
}

var a = Account()

catch {
  a.nickname = 'rainy day'
} as e {
  echo e.message
}

undefined field 'nickname' on instance of 'Account'

Second, self.x = value inside @new does declare a field, as a convenience so that constructors do not have to repeat themselves:

class Point {
  @new(x, y) {
    self.x = x
    self.y = y
  }
}

echo Point(3, 4).x

3

That convenience applies to @new’s own body and nowhere else. A constructor that calls a helper to do its initialisation must declare those fields with var:

class A {
  var from_helper          # required

  @new() {
    self.setup()
  }

  setup() {
    self.from_helper = 2
  }
}

Without the var line, the assignment inside setup() raises undefined field 'from_helper'.

Static Members

static puts a field or method on the class rather than on each instance:

class Account {
  static var count = 0

  @new(owner) {
    self.owner = owner
    Account.count++
  }

  static open(owner) {
    return Account(owner)
  }
}

Account('Ada')
Account('Bob')

echo Account.count
echo Account.open('Carol').owner

2
Carol

A static method has no self:

SyntaxError: 'self' used outside of a method

Reach the class by name instead.

Static fields are the one mutable part of a class. The set of members is sealed; the values of static fields are not.

Duplicate Members Are Errors

Declaring the same method twice in one class does not silently keep the last one:

class B {
  m() {}
  m() {}
}

SyntaxError: multiple declaration for method 'm' found in class 'B'

The same applies to declaring the same class name twice in one module.

Instances and Dictionaries

Use a dictionary for data whose shape you learn at runtime: parsed JSON, HTTP headers, a config file. Use a class when the shape is known and there is behaviour to attach.

Inheritance

A class extends another with <:

class Shape {
  @new(name) {
    self.name = name
  }

  area() {
    raise NotImplementedError('${self.name} must define area()')
  }

  describe() {
    return '${self.name} with area ${self.area()}'
  }
}

class Circle < Shape {
  @new(radius) {
    parent('circle')
    self.radius = radius
  }

  area() {
    return 3.141592653589793 * self.radius ** 2
  }
}

echo Circle(1).describe()

circle with area 3.141592653589793

A subclass inherits every field and method. Single inheritance only; a class has at most one parent.

Note the direction of the arrow. class Circle < Shape creates a new class that borrows from Shape. Turning it around — class Anything > Shape — is a different declaration entirely: it adds methods to Shape itself and creates no class at all. See Class Extensions.

Naming the Parent

A class is a value like any other, so the parent does not have to be a bare name in the current file. Anything an expression starting with a name can reach works, which is what lets you build on a class another module owns:

import log

class MemoryTransport < log.Transport {
  @new() {
    self.lines = []
  }

  handle(record) {
    self.lines.append(record)
  }
}

echo instance_of(MemoryTransport(), log.Transport)

true

Property access, indexing and calls all work the same way, so a parent picked out of a registry (class Store < backends['redis']) or handed back by a function (class Store < chosen_backend()) is as valid as a name. The expression is evaluated once, where the class is declared.

The one rule is that it has to begin with a name. That is what keeps the { opening the body from ever being read as the start of a dictionary.

parent

parent means two related things.

parent(args) calls the parent’s constructor. That is the parent('circle') line in Circle above, and it comes first in @new, before the subclass sets up anything of its own. Calling it late means the parent’s constructor overwrites what you just assigned; not calling it at all means the parent’s fields are never initialised.

parent.method(args) calls the parent’s version of a method that this class has overridden:

class Square < Shape {
  @new(side) {
    parent('square')
    self.side = side
  }

  area() {
    return self.side ** 2
  }

  describe() {
    return 'a ' + parent.describe()
  }
}

echo Square(2).describe()

a square with area 4

Note what happened there. parent.describe() ran Shape’s describe, which calls self.area(), which dispatched back to Square’s area. A method always dispatches on the actual object, not on the class the code was written in.

Overriding

Redeclaring a method in a subclass replaces it. There is no keyword for it and no way to forbid it.

describe() above is the useful shape of this: a parent method written in terms of a method the child supplies. Shape.area() raises NotImplementedError, so a subclass that forgets to override it says so clearly:

catch {
  Shape('blob').area()
} as e {
  echo e.message
}

blob must define area()

That is Zuri’s abstract method. There is no abstract keyword because there does not need to be one.

A Subclass Without a Constructor

If a subclass declares no @new, it uses its parent’s:

class NoCtor < Shape {}

echo NoCtor('plain').name

plain

Testing Ancestry

instance_of() walks the whole chain:

echo instance_of(Circle(1), Shape)
echo instance_of(Circle(1), Square)

true
false

typeof() gives the most specific class name, as a string:

echo typeof(Circle(1))

Circle

The Depth Is Free

Inheritance chains cost nothing to walk at runtime. A method lookup on a class four levels deep is the same operation as one on a class with no parent, because every class’s method table is complete at declaration time. Write the hierarchy the design wants.

What You Write Instead of an Interface

Zuri has single inheritance and no interfaces, so the two patterns below do the jobs an interface would do elsewhere.

A base class that raises. When a base class needs every subclass to supply a method, declare it and raise:

class Shape {

  @new(name: string) {
    self.name = name
  }

  area() {
    raise NotImplementedError('${self.name} must define area()')
  }

  describe() {
    return '${self.name} has area ${self.area()}'
  }
}

class Circle < Shape {

  @new(radius: number) {
    parent('circle')
    self.radius = radius
  }

  area() {
    return 3.141592653589793 * self.radius ** 2
  }
}

class Blob < Shape {

  @new() {
    parent('blob')
  }
}

echo Circle(2).describe()

catch {
  echo Blob().describe()
} as e {
  echo '${e.type}: ${e.message}'
}

circle has area 12.566370614359172
NotImplementedError: blob must define area()

describe() calls self.area(), and self is the actual instance, so the subclass’s version runs. That is the whole of dynamic dispatch in Zuri: there is nothing to declare and nothing to mark virtual.

A parameter typed by the base class. An annotation naming a class accepts any subclass of it, which is how you say “anything that is a Shape”:

def total_area(shapes: list) {
  return shapes.reduce(@(sum, shape: Shape) => sum + shape.area(), 0)
}

Checking What Something Is

Two built-ins answer questions about an instance’s type, and they answer different questions.

instance_of(value, Class)

instance_of() asks “does this behave like a Class?”, and it walks the whole inheritance chain to answer:

class Shape {}
class Circle < Shape {}
class Square < Shape {}
class Ellipse < Circle {}

var c = Circle()

echo instance_of(c, Circle)
echo instance_of(c, Shape)
echo instance_of(c, Square)
echo instance_of(Ellipse(), Shape)

true
true
false
true

Ellipse is two levels below Shape and still answers true. There is no depth limit: the check follows parents until it finds a match or runs out. A sibling — Circle against Square — is false, because siblings share an ancestor rather than a lineage.

It never raises for the first argument. Anything that is not an instance of the class simply answers false, including values that are not instances at all:

class Shape {}

echo instance_of(42, Shape)
echo instance_of('circle', Shape)
echo instance_of(nil, Shape)
echo instance_of([1, 2], Shape)

false
false
false
false

That makes it safe to use as a guard on a value you know nothing about; no is_instance() check has to come first.

A class is not an instance of itself. Passing the class rather than an object gives false:

class Shape {}
class Circle < Shape {}

echo instance_of(Circle, Shape)
echo instance_of(Circle(), Shape)

false
true

This trips people up when a variable might hold either. Circle is a class; Circle() is an instance; only the second is “a Shape”.

The second argument must be a class, and here it does raise:

class Shape {}

catch {
  instance_of(Shape(), 'Shape')
} as e {
  echo e.message
}

instance_of() expects argument 2 to be a class, got string

The class name as a string is the common version of this mistake. Pass the class itself.

A class held in a variable works, because the check is on the value rather than on the spelling:

class Base {}
class Derived < Base {}

var Alias = Base

echo instance_of(Derived(), Alias)

true

So does a class reached through a module:

import set

echo instance_of(set.set([1, 2]), set.Set)

true

It Is How the Error Hierarchy Works

Every built-in error inherits from Error, so instance_of() is what lets one handler sort them:

echo instance_of(ValueError('bad'), Error)
echo instance_of(ValueError('bad'), TypeError)

true
false

That is the mechanism behind the “handle one kind, re-raise the rest” pattern in Error Handling, and behind mapping a domain error to an HTTP status in Chapter 25.

typeof(value)

typeof() asks a different question: “what exactly is this?”. On an instance it names the concrete class, and it never mentions ancestors:

class Shape {}
class Circle < Shape {}

echo typeof(Circle())
echo typeof(Shape())
echo typeof(Circle)
echo typeof(42)
echo typeof('text')

Circle
Shape
class
number
string

Note the third line. typeof() on the class itself answers class, not Circle — the class is a value of kind “class”, and its name is not what typeof() reports.

Which to Use

Reach for instance_of() by default. It is the one that respects inheritance, and code written with typeof(x) == 'Circle' breaks the day someone subclasses Circle — the subclass is a perfectly good Circle, and the string comparison says otherwise.

A Type Annotation Is the Same Check

Annotating a parameter with a class name performs exactly the instance_of() test, at every call, with a better error message:

class Shape {}
class Circle < Shape {}

def describe(shape: Shape) {
  return 'a shape of type ${typeof(shape)}'
}

echo describe(Circle())
echo describe(Shape())

catch {
  describe(42)
} as e {
  echo e.message
}

a shape of type Circle
a shape of type Shape
describe() expects parameter 'shape' (argument 1) to be a Shape, got number

Prefer the annotation when the answer decides whether the function should run at all, and instance_of() when the answer decides which branch to take.

Decorated Methods

A method whose name begins with @ is a decorated method. The runtime calls it for you when a piece of language syntax is applied to your instance. That is how a class hooks into construction, arithmetic, comparison and iteration without any special syntax of its own.

Decorated methods are ordinary methods. They can be inherited, overridden and called by name.

@new: Construction

Already covered. It runs when the class is called, receives the arguments, and is the one place self.x = value may declare a new field.

Arithmetic

Define the operator you want and it works on your instances:

class Vector {
  @new(x, y) {
    self.x = x
    self.y = y
  }

  @add(other) {
    return Vector(self.x + other.x, self.y + other.y)
  }

  @sub(other) {
    return Vector(self.x - other.x, self.y - other.y)
  }

  @mul(k) {
    return Vector(self.x * k, self.y * k)
  }

  @neg() {
    return Vector(-self.x, -self.y)
  }

  to_string() {
    return '(${self.x}, ${self.y})'
  }
}

var a = Vector(1, 2)
var b = Vector(3, 4)

echo (a + b).to_string()
echo (b - a).to_string()
echo (a * 3).to_string()
echo (-a).to_string()

(4, 6)
(2, 2)
(3, 6)
(-1, -2)

The full arithmetic set:

Bitwise and Logic

class Flags {
  @new(bits) {
    self.bits = bits
  }

  @and(mask) {
    return self.bits & mask
  }

  @not() {
    return Flags(~self.bits)
  }
}

echo Flags(5) & 4
echo (~Flags(5)).bits

4
-6

@not is bound to ~, the bitwise complement. ! is logical negation and it is not overridable: an instance is always truthy, so !instance is always false.

Comparison

class Version {
  @new(major, minor) {
    self.major = major
    self.minor = minor
  }

  @lt(other) {
    if self.major != other.major {
      return self.major < other.major
    }
    return self.minor < other.minor
  }

  @gt(other) {
    return other < self
  }
}

echo Version(1, 2) < Version(1, 10)
echo Version(2, 0) > Version(1, 10)

true
true

Each Operator Is Separate

There is no derivation between them. Defining @lt does not give you >, and defining @add does not give you += on the other side:

class Price {

  @new(cents) {
    self.cents = cents
  }

  @lt(other) {
    return self.cents < other.cents
  }
}

echo Price(250) < Price(500)

catch {
  echo Price(500) > Price(250)
} as e {
  echo e.message
}

true
operator '>' not defined for Price and Price

Define every operator you want to support. @gt is usually one line, as the Version example above shows.

The Other Operand Is Not Checked

A decorated method is an ordinary method, and its parameter is an ordinary parameter. Nothing guarantees the other side is the same class:

class Amount {

  @new(cents) {
    self.cents = cents
  }

  @add(other) {
    return Amount(self.cents + other.cents)
  }
}

catch {
  echo Amount(500) + 5
} as e {
  echo '${e.type}: ${e.message}'
}

catch {
  echo 5 + Amount(500)
} as e {
  echo '${e.type}: ${e.message}'
}

TypeError: cannot read property 'cents' on a number
TypeError: operator '+' not defined for call signature (number, Amount)

Read those two together. With the instance on the left, @add ran and failed inside your own method with a confusing message. With it on the right, the operator was never dispatched to your class at all — a decorated method only handles the case where its own instance is the left operand.

Annotate the parameter to fix the first message, and accept the second as the rule:

class Sum {

  @new(cents) {
    self.cents = cents
  }

  @add(other: Sum) {
    return Sum(self.cents + other.cents)
  }
}

catch {
  echo Sum(500) + 5
} as e {
  echo e.message
}

@add() expects parameter 'other' (argument 1) to be a Sum, got number

Equality

@eq defines == for your class, and != is always its negation:

class Point {
  @new(x, y) {
    self.x = x
    self.y = y
  }

  @eq(other) {
    if !instance_of(other, Point) {
      return false
    }

    return self.x == other.x and self.y == other.y
  }
}

var p = Point(1, 2)

echo p == Point(1, 2)
echo p != Point(1, 2)
echo p == Point(2, 1)
echo p == nil

true
false
false
false

@eq runs only when the value on the right is an object too: a string, a list, another instance and so on. p == nil, p == 5 and p == true compare the ordinary way without calling it, so a nil check stays a nil check whatever the class defines. It must return a bool; anything else raises a TypeError. Without @eq, two instances are equal only when they are the same object.

using matches through @eq as well, since it compares the way == does.

@eq decides == and nothing else. Lists and dictionaries compare the instances inside them by identity, and so do contains(), index_of() and dictionary keys:

class Point {
  @new(x, y) {
    self.x = x
    self.y = y
  }

  @eq(other) {
    if !instance_of(other, Point) {
      return false
    }

    return self.x == other.x and self.y == other.y
  }
}

var p = Point(1, 2)

echo [p] == [Point(1, 2)]
echo [p].contains(Point(1, 2))
echo [p].contains(p)

false
false
true

Iteration

@key and @value together make a class work with for ... in. They are the largest of the decorated methods to get right, so they have a section of their own: Making a Class Iterable.

@to_json

json.encode() calls @to_json() on an instance and encodes whatever it returns:

import json

class User {
  @new(name, password) {
    self.name = name
    self.password = password
  }

  @to_json() {
    return { name: self.name }
  }
}

echo json.encode(User('ada', 'hunter2'))

{"name":"ada"}

Without it, encoding an instance has nothing to work from. With it, you decide exactly what crosses the wire, which is the right place to leave a password behind.

@to_string

@to_string() decides what echo and print() show for an instance:

class Money {
  @new(cents) {
    self.cents = cents
  }

  @to_string() {
    return '$' + (self.cents / 100)
  }
}

var m = Money(500)

echo m
echo [m, Money(250)]
echo { total: m }

$5
[$5, $2.5]
{total: $5}

It applies wherever the instance sits in what is being shown, inside lists and dictionaries, as a key or as a value. Without it, an instance shows as <instance of Money>. It must return a string; anything else raises a TypeError.

to_string()

to_string() has no @ because it is not a decorator; it is a real method every value already has, and a class may override it to give its instances a plain string form.

Nothing calls it for you. String interpolation and + render an instance as <instance of Money>, so call it inside the interpolation. A class that has both usually builds one from the other:

class Money {
  @new(cents) {
    self.cents = cents
  }

  to_string() {
    return '$' + (self.cents / 100)
  }

  @to_string() {
    return '<Money ${self.to_string()}>'
  }
}

var m = Money(500)

echo m
echo 'cost: ${m.to_string()}'

<Money $5>
cost: $5

That is the split the standard library follows: to_string() is the value as text, and @to_string() is how the instance looks when you print it.

Keep both cheap and free of side effects. Error messages, logging and debugging all reach for them.

Encapsulation and Class Immutability

Private Members

A field or method whose name starts with _ is private. It can be reached through self or parent, and nowhere else:

class Box {
  var _items = []

  add(value) {
    self._items.append(value)
    return self
  }

  count() {
    return self._items.length()
  }
}

echo Box().add(1).add(2).count()

2

Reaching in from outside does not compile:

var b = Box()
echo b._items

SyntaxError: '_items' is private and can only be accessed via 'self' or 'parent'
  --> /path/to/main.zu:2:8
   |
 2 | echo b._items
   |        ^

This is a compile-time check, not a runtime one, so it costs nothing and cannot be worked around by computing the name.

A subclass can reach its parent’s private members, through self for fields and parent for methods:

class Base {
  var _secret = 'base secret'

  _internal() {
    return 'base internal'
  }
}

class Child < Base {
  reveal() {
    return self._secret + '/' + parent._internal()
  }
}

echo Child().reveal()

base secret/base internal

The same underscore convention governs modules: a module member whose name starts with _ cannot be imported by name. Chapter 8 covers that side of it.

Classes Are Sealed

Once a class is declared, its shape is final. You cannot add a field or a method to it, and you cannot add one to an instance:

class Account {
  var balance = 0
}

var a = Account()

catch {
  a.nickname = 'rainy day'
} as e {
  echo e.message
}

undefined field 'nickname' on instance of 'Account'

The practical consequence is that a misspelled field name is an error at the point you write it, rather than a new field that silently shadows the one you meant. Every field a class has is declared in one place, and that place is @new.

Static field values are mutable; the set of static fields is not.

Reflective Access

Four built-in functions read and write fields by name:

var b = Box()

echo hasprop(b, '_items')
echo getprop(b, '_items')
echo delprop(b, '_items')
echo getprop(b, '_items')

true
[]
true
nil

setprop(obj, name, value) writes; delprop resets the slot to nil. Both return false when the field does not exist on the class, because neither can create one.

These bypass the underscore rule, which is deliberate: they exist for serialisers, debuggers and test helpers, where reaching into an object is the entire point. Regular code should not use them.

The zuri module goes further, with a full reflection API over classes, functions and modules. Chapter 21 covers it.

Designing With Sealed Classes

Two habits follow from sealing.

Declare every field on the class, even the ones the constructor fills in. self.x = value inside @new will declare one for you, but a var line at the top of the body is documentation the next reader gets for free, and it is required the moment a helper method does the assigning instead.

Model optional state as a field holding nil, not as an absent field. There is no such thing as an absent field, so a var cached_result that starts nil is the shape you want.

A Worked Example

Privacy earns its place when a class has an invariant to protect. Here is a bounded history buffer: it keeps the last n entries and nothing else, and there is no way for a caller to break that from outside.

class History {
  var _entries = []
  var _limit = 0

  @new(limit: number) {
    if limit < 1 {
      raise ValueError('limit must be at least 1, got ${limit}')
    }

    self._limit = limit
  }

  record(entry) {
    self._entries.append(entry)

    if self._entries.length() > self._limit {
      self._entries.shift()
    }

    return self
  }

  # A copy, so a caller cannot append through the value we hand back.
  entries() {
    return self._entries.clone()
  }

  length() {
    return self._entries.length()
  }
}

var history = History(3)

history.record('a').record('b').record('c').record('d')

echo history.entries()
echo history.length()

var taken = history.entries()
taken.append('e')

echo history.entries()

catch {
  History(0)
} as e {
  echo '${e.type}: ${e.message}'
}

[b, c, d]
3
[b, c, d]
ValueError: limit must be at least 1, got 0

Four decisions are doing the work.

The list is private, so nothing outside can append to it and skip the trimming. history._entries.append('x') does not compile.

entries() returns a clone. Without it, the caller would hold the real list and could grow it past the limit — which is exactly what the fourth output line shows not happening. Handing out a private mutable collection is the most common way encapsulation leaks.

The invariant is established in the constructor. _limit is validated once, so record() never has to wonder whether it is sensible.

The class is sealed, so history.limit = 999 is an error rather than a second, ignored field sitting alongside _limit.

Making a Class Iterable

Any class can be walked with for ... in. It takes two decorated methods and no other ceremony: no interface to declare, no iterator object to return, and no state kept between passes.

This section covers the protocol, the two shapes it usually takes, what happens when a piece is missing, and the rules that keep a custom iterator well behaved.

The Protocol

for value in thing is not magic. Zuri evaluates thing once, then repeats three steps:

1. key = thing.@key(key), starting from nil
2. stop if key is nil
3. value = thing.@value(key), and run the body

So the two methods answer two separate questions:

• @key(previous) — “given the last position, what is the next one?” It receives nil on the first call and must return nil when there is nothing left.
• @value(key) — “what is stored at this position?”

The loop never stores a cursor of its own. The key is the cursor, which is why @key gets the previous one back each time.

A Counting Example

class Countdown {

  @new(from) {
    self.from = from
  }

  @key(previous) {
    if previous == nil {
      return self.from
    }

    if previous <= 1 {
      return nil
    }

    return previous - 1
  }

  @value(key) {
    return key * 10
  }
}

for value in Countdown(3) {
  echo value
}

30
20
10

Trace it once and the protocol stops being abstract. @key(nil) returned 3, so the first value is @value(3), which is 30. @key(3) returned 2, then @key(2) returned 1, then @key(1) returned nil and the loop ended.

Note that the key and the value are genuinely different things here: the key counts down from three, the value is ten times it. Two variables in the loop give you both:

for key, value in Countdown(3) {
  echo '${key} -> ${value}'
}

3 -> 30
2 -> 20
1 -> 10

Wrapping a Collection

The more common case is a class holding a list, where the key is an index. The shape is always the same three checks:

class Stack {

  @new() {
    self.items = []
  }

  push(value) {
    self.items.append(value)
    return self
  }

  @key(previous) {
    if self.items.is_empty() {
      return nil
    }

    if previous == nil {
      return 0
    }

    if previous >= self.items.length() - 1 {
      return nil
    }

    return previous + 1
  }

  @value(key) {
    return self.items[key]
  }
}

var stack = Stack().push('a').push('b').push('c')

for value in stack {
  echo value
}

for index, value in stack {
  echo '${index}: ${value}'
}

a
b
c
0: a
1: b
2: c

Each of the three checks in @key earns its place:

The empty check comes first. Without it, @key(nil) would return 0 for an empty stack and @value(0) would index past the end.

previous == nil starts the walk, and 0 is the first index.

previous >= length() - 1 ends it. Using >= rather than == means a collection that shrank mid-loop still terminates.

An empty collection iterates zero times rather than failing:

for value in Stack() {
  echo 'never printed'
}

echo 'done'

done

What You Get for Free

Defining both methods makes is_iterable() answer true, and makes the class usable everywhere for is:

echo is_iterable(Stack().push('a'))
echo is_iterable(Countdown(1))

true
true

Both Are Required

for calls @key and then @value. Defining only one produces an error naming the one that is missing:

class OnlyKey {

  @key(previous) {
    return previous == nil ? 0 : nil
  }
}

catch {
  for value in OnlyKey() {
    echo value
  }
} as e {
  echo '${e.type}: ${e.message}'
}

PropertyError: undefined property '@value' on instance of 'OnlyKey'

A class with neither fails on @key instead:

class Plain {}

catch {
  for value in Plain() {
    echo value
  }
} as e {
  echo '${e.type}: ${e.message}'
}

PropertyError: undefined property '@key' on instance of 'Plain'

Rules Worth Knowing

A nil key ends the loop, always. That means a collection whose keys could legitimately be nil cannot use them as keys. Use indices and look the real key up in @value.

The instance is evaluated once. for x in build_thing() calls build_thing() a single time, before the first pass, so @key and @value are always called on the same object.

Neither method should mutate. They are called once per pass, in a loop you do not control, and a @key with a side effect is a loop whose behaviour depends on how many times something asked for the next key.

Iteration order is whatever @key says. There is no requirement to count upwards, or to visit everything; Countdown walks backwards, and a class could just as well skip, filter or repeat.

Class Extensions

An extension adds methods to a class that already exists. It is written with > rather than <, and it is a different thing from inheritance: inheritance creates a new class that borrows from an old one, while an extension modifies the old one in place.

class Account {

  @new(owner) {
    self.owner = owner
  }

  describe() {
    return 'account for ${self.owner}'
  }
}

class AccountExtras > Account {

  static shout(account) {
    return account.describe().upper()
  }

  static initials(account) {
    return account.owner[0]
  }
}

var a = Account('ada')

echo a.shout()
echo a.initials()
echo a.describe()

ACCOUNT FOR ADA
a
account for ada

Account gained two methods. There is no new class, no subclass, and no wrapper object: a is the same Account instance it was, and it now answers to shout() and initials() alongside the methods its own declaration gave it.

< Versus >

The two are easy to tell apart once you read the arrow as pointing at where the methods end up.

The Rules

Four rules are enforced at compile time, and the error messages say exactly what is wrong.

The Name Is a Label

An extension’s own name is never bound to anything. It exists so the declaration reads like a declaration and so the error messages have something to say:

class AccountExtras > Account {
  static shout(account) { return 'hi' }
}

echo typeof(AccountExtras)

Unhandled UndefinedError: undefined global 'AccountExtras'

Name it after what it adds. AccountExtras, ShapeFormatting, NodeDebugging all read well; the name appears in no other code.

Every Method Must Be static

class Target {}

class Bad > Target {
  helper() {
    return 1
  }
}

SyntaxError: extension method 'helper' must be declared 'static' and receive the instance explicitly as their own first parameter if desired

static here does not mean the method ends up on the class rather than on instances. It means the method is compiled without an implicit receiver, so self does not exist inside it. The instance arrives as an ordinary argument instead.

No Fields

class Target {}

class Bad > Target {
  var cache = {}
}

SyntaxError: extension 'Bad' can only declare static methods but not fields

An extension adds behaviour, never state. A class’s set of fields is fixed when the class is declared, and nothing — including an extension — can add one afterwards. When your extension needs somewhere to keep something, keep it in the extending module, keyed by whatever identifies the instance.

The Target Must Exist

The target is evaluated when the extension is declared, so it has to be a name that is already bound to a class:

class Orphan > NoSuchClass {
  static m(x) {
    return 1
  }
}

Unhandled UndefinedError: undefined global 'NoSuchClass'

The name does not have to be a bare one. Anything an expression starting with an identifier reaches works, so a class another module owns can be named straight through that module:

import set

class SetExtras > set.Set {
  static summary(s) {
    return 'set of ${s.length()}'
  }
}

echo set.Set([1, 2, 3]).summary()

set of 3

Built-in types are not classes in scope, so string, list, number and the rest cannot be extended. Error and every class the standard library exports can be.

The Receiver

An extension method receives the instance as its first parameter. The name is yours to choose:

class Reading {

  @new(celsius) {
    self.celsius = celsius
  }
}

class ReadingConversion > Reading {

  static fahrenheit(reading) {
    return reading.celsius * 9 / 5 + 32
  }

  static scaled(reading, factor) {
    return reading.celsius * factor
  }
}

var r = Reading(100)

echo r.fahrenheit()
echo r.scaled(3)

212
300

r.scaled(3) passes r as reading and 3 as factor. Every argument at the call site shifts one place to the right of the receiver, exactly as it would for an ordinary method.

Because arity is not enforced, the receiver parameter is optional. A method that does not need the instance can simply not declare one:

class Widget {

  @new() {}
}

class WidgetVersion > Widget {

  static api_version() {
    return '1.0'
  }
}

echo Widget().api_version()

1.0

self Does Not Exist Here

class Thing {

  @new(n) {
    self.n = n
  }
}

class ThingBroken > Thing {

  static value(t) {
    return self.n
  }
}

SyntaxError: 'self' used outside of a method

Use the receiver parameter. t.n, not self.n.

Private Members Stay Private

An extension is outside code, and the underscore rule applies to it in full:

class Safe {
  var _hidden = 'secret'

  @new() {}
}

class Peek > Safe {

  static reveal(s) {
    return s._hidden
  }
}

SyntaxError: '_hidden' is private and can only be accessed via 'self' or 'parent'

This is the important limit on extensions. They can add behaviour built out of a class’s public surface, and they cannot reach inside it. An extension is not a way around encapsulation.

Replacing an Existing Method

An extension method with the same name as one the class already has replaces it:

class Greeter {

  @new(name) {
    self.name = name
  }

  greet() {
    return 'hello ${self.name}'
  }
}

var g = Greeter('ada')

echo g.greet()

class GreeterLoud > Greeter {

  static greet(greeter) {
    return 'HELLO ${greeter.name.upper()}'
  }
}

echo g.greet()

hello ada
HELLO ADA

Read that carefully. g was constructed before the extension was declared, and calling greet() on it after the declaration runs the new one. The replacement is not a shadow or a wrapper: the method table of the class itself changed, and every instance of it — past, present and future — sees the change.

This holds no matter how thoroughly the original has already been used. Build an eight-level tree, call the original count() four thousand times, then replace it:

var t = tree_with(8)
var total = 0

iter var i = 0; i < 4000; i++ {
  total = total + t.count()
}

echo total

class TreeNodeExt > TreeNode {

  static count(node) {
    return 999
  }
}

echo t.count()

2044000
999

Four thousand calls to the old method, and the next call runs the new one. Replacement is unconditional: there is no warm-up state, cached lookup or earlier result that can keep an old body alive past the extension.

Decorated Methods

An extension can add decorated methods, which is how you give operators, iteration or a string form to a class you did not write. The receiver still comes first, and the decorator’s own parameters follow it:

class Box {

  @new(n) {
    self.n = n
  }
}

class BoxOps > Box {

  static @add(a, b) {
    return Box(a.n + b.n)
  }

  static @key(box, previous) {
    return previous == nil ? 0 : nil
  }

  static @value(box, key) {
    return box.n
  }

  static to_string(box) {
    return 'Box(${box.n})'
  }
}

echo (Box(2) + Box(3)).n
echo Box(9).to_string()

for value in Box(7) {
  echo value
}

5
Box(9)
7

@add(a, b) gets the left operand as a and the right as b. @key(box, previous) gets the instance and then the previous key, which is the argument @key would normally take on its own.

They Are Instance Methods, Not Statics

static in the declaration describes how the method is compiled, not where it lands. The methods go onto instances:

class Item {

  @new() {}
}

class ItemExtras > Item {

  static label(item) {
    return 'an item'
  }
}

echo Item.label(Item())

Unhandled PropertyError: undefined static member 'label' on class 'Item'

Call it on the instance: Item().label().

Extensions and Inheritance

The two interact in one way worth knowing, and the rule is about when each declaration runs.

An extension changes the target’s method table. A subclass copies its parent’s methods when the subclass is declared. So a subclass sees an extension only if the extension came first:

class Vehicle {

  @new(wheels) {
    self.wheels = wheels
  }
}

class VehicleExtras > Vehicle {

  static doubled(vehicle) {
    return vehicle.wheels * 2
  }
}

class Car < Vehicle {

  @new() {
    parent(4)
  }
}

echo Vehicle(2).doubled()
echo Car().doubled()

4
8

Car was declared after the extension, so it inherited doubled. Move the class Car declaration above the extension and Car().doubled() raises undefined property 'doubled' on instance of 'Car', while Vehicle keeps it.

Declare extensions before the subclasses that should inherit them. In practice that means at the top of a module, or in a module imported at the top.

Extending a subclass never touches its parent:

class Animal {

  @new() {}
}

class Dog < Animal {

  @new() {}
}

class DogExtras > Dog {

  static speak(dog) {
    return 'woof'
  }
}

echo Dog().speak()

catch {
  echo Animal().speak()
} as e {
  echo e.message
}

woof
undefined property 'speak' on instance of 'Animal'

Extensions Are Global

This is the property that makes extensions powerful and the one that makes them worth using sparingly. An extension is not scoped to the module that declares it. It changes the class everywhere in the program, and it takes effect the moment the declaring module runs — which, for an imported module, is the moment it is imported.

Filename: shape.zu

class Shape {

  @new(name) {
    self.name = name
  }
}

Filename: extras.zu

import .shape { Shape }

class ShapeExtras > Shape {

  static label(s) {
    return 'shape: ${s.name}'
  }
}

Filename: main.zu

import .shape { Shape }

var s = Shape('circle')

catch {
  echo s.label()
} as e {
  echo 'before import: ${e.message}'
}

import .extras

echo s.label()
echo Shape('square').label()

before import: undefined property 'label' on instance of 'Shape'
shape: circle
shape: square

main.zu never mentions label’s definition. Importing extras — for any reason, including a reason unrelated to Shape — added a method to a class declared in a third file, and the instance created before the import gained it too.

Two consequences follow.

An import can change behaviour you did not ask it to change. A module that extends a class you use will alter it for your code as well, and nothing at your call site says so.

Two extensions of the same method collide silently. The last one to run wins, and the winner depends on import order:

class Slot {

  @new() {}
}

class First > Slot {

  static which(s) {
    return 'first'
  }
}

class Second > Slot {

  static which(s) {
    return 'second'
  }
}

echo Slot().which()

second

When to Use One

Extensions answer a question inheritance cannot: how do you add behaviour to a class whose instances are created somewhere you do not control? A subclass only helps if you are the one calling the constructor.

Good reasons:

Adding a view or a format to a domain class. to_string(), a @to_json, a summary() — presentation that does not belong in the model itself, added from the module that cares about it.

Giving a standard library class an operator or an iterator so it works with syntax it was not written for.

Instrumenting during debugging. Replacing a method with one that logs, then deleting the extension, is a diagnostic technique that costs nothing in the original file.

Reasons to think twice:

It is invisible at the call site. account.shout() gives no hint that shout lives in a different file from Account. A reader who greps the class body will not find it.

It is global. Everything above.

A plain function is usually enough. shout(account) is a function, it is obvious where it lives, and it cannot collide with anything. Reach for an extension when the thing genuinely needs to be a method — because syntax demands it, as with a decorated method, or because callers already have the instance and nothing else.

Error Handling

Things go wrong. A file is not there, a number arrives as text, a network peer stops answering. Zuri has one mechanism for all of it: an Error object, raised with raise and intercepted with catch. There is no try, no finally, and no checked exceptions.

This chapter covers raising, the three shapes of catch, what an error carries, the built-in hierarchy, writing your own, and the patterns that replace finally.

Raising

def withdraw(balance, amount) {
  if amount > balance {
    raise ValueError('cannot withdraw ${amount} from ${balance}')
  }
  return balance - amount
}

raise takes an instance of Error or any subclass, and nothing else. A bare string or number is a TypeError in its own right:

catch {
  raise 'something went wrong'
} as e {
  echo e.message
}

can only raise an Error or subclass, got a string

That rule is worth the small inconvenience: every value that travels through the error system has a type, a message and a stack trace, because there is no way to put anything else in.

An error that nobody catches ends the program with a message, a source excerpt and a stack trace:

Unhandled ValueError: cannot withdraw 100 from 50
  --> /path/to/main.zu:3

   1 | def withdraw(balance, amount) {
   2 |   if amount > balance {
>  3 |     raise ValueError('cannot withdraw ${amount} from ${balance}')
   4 |   }
   5 |   return balance - amount

Stack trace (most recent call last):
  at withdraw() /path/to/main.zu:3
  at @.script() /path/to/main.zu:8

Catching

catch {
  risky()
} as e {
  echo '${e.type}: ${e.message}'
}

The catch block runs. If anything inside it raises, execution jumps to the handler with the error bound to e. If nothing raises, the handler never runs.

There are three shapes, and each does something different.

catch { ... } with nothing after it swallows the error and carries on:

catch {
  raise Error('silent')
}
echo 'swallowed'

swallowed

Use this when failure genuinely does not matter, and nowhere else.

catch { ... } as e with no handler block binds the error to a variable that survives the statement. e is nil when nothing went wrong:

catch {
  raise Error('boom')
} as e

if e {
  echo e.message
}

boom

This is the shape to use when the recovery does not belong inside a handler, for example when you want to check several things in a row.

catch { ... } as e { ... } is the full form, and the one you will write most.

What an Error Carries

catch {
  raise ValueError('bad input')
} as e {
  echo e.type
  echo e.message
  echo e.stacktrace
}

ValueError
bad input
[/path/to/main.zu:2 -> @.script()]

• message is the text.
• type is the class name, as a string.
• stacktrace is a list of frames, innermost first, each naming a file, a line and a function.

The stack trace is captured where the error was raised, not where it was caught, so it points at the origin no matter how many frames it travelled through:

def inner() {
  raise ValueError('deep')
}

def middle() {
  inner()
}

catch {
  middle()
} as e {
  echo e.stacktrace.length()
}

3

Three frames: inner, middle, and the script’s top level. Printing them is often the fastest way to answer “how did we get here?” in code you did not write.

The Built-in Errors

Every one of these is a class, and every one inherits from Error:

Because they all inherit from Error, catching Error catches everything, and a parameter annotated Error accepts any of them.

Custom Errors

Subclass Error and carry whatever the caller needs:

class HttpError < Error {
  @new(message, status) {
    parent(message)
    self.type = 'HttpError'
    self.status = status
  }
}

catch {
  raise HttpError('not found', 404)
} as e {
  echo '${e.type} ${e.status}: ${e.message}'
  echo instance_of(e, Error)
}

HttpError 404: not found
true

Two things make this work well. Call parent(message) so the base constructor sets message and captures the stack trace. Set self.type so the class name shows up in logs and in the uncaught-error banner.

Deciding Which Error to Catch

catch catches everything inside its block. To handle one kind and let the others through, test and re-raise:

catch {
  load_config()
} as e {
  if !instance_of(e, ModuleNotFoundError) {
    raise e
  }
  echo 'no config, using defaults'
}

instance_of() walks the inheritance chain, so a test against Error matches everything and a test against HttpError matches only that branch.

There Is No finally

Code after the catch statement runs whether the block raised or not, because the handler either recovers or re-raises:

def cleanup_demo() {
  catch {
    raise Error('mid')
  } as e {
    echo 'caught'
  }

  echo 'always runs'
}

cleanup_demo()

caught
always runs

That covers the common case. When the handler re-raises, or when the block contains a return, the trailing code is skipped, so a resource that must be released either way goes in the handler as well:

var handle = file(path, 'w')

catch {
  write_everything(handle)
} as e {
  handle.close()
  raise e
}

handle.close()

The Bare as e Form Does It Once

The version above repeats handle.close(), once in the handler and once after the statement, because those are two different paths out. The third shape of catch — as e with no handler block — collapses them into one:

var handle = file(path, 'w')

catch {
  write_everything(handle)
} as e

handle.close()

if e {
  raise e
}

The difference is the missing { ... } after as e, and it changes the control flow rather than just the layout. With no handler there is nothing to jump into, so a raise inside the block is recorded in e and execution simply continues on the next line. Both paths — the one that raised and the one that did not — now run the same trailing code:

  fallthrough: closing
  fallthrough: re-raising
  caught: disk full

That gives you close() written once, running unconditionally, followed by an explicit decision about whether to re-raise. It is the closest thing Zuri has to finally, and it is assembled out of the ordinary pieces rather than being a separate construct:

Two things to be deliberate about.

e is nil when nothing went wrong, which is what makes if e { raise e } the whole of the decision. On the success path the cleanup runs and the function carries on normally.

Re-raising e itself keeps the original stack trace, pointing at the line that actually failed rather than at the raise you just wrote. Wrap it in a new error only when you have something to add, as Nesting and Re-raising shows.

Use the handler form when the failure needs handling. Use this form when it needs only cleaning up after.

return Inside catch

A return from inside a catch block or its handler leaves the enclosing function, exactly as it would anywhere else:

def find(items, needle) {
  catch {
    var i = items.index_of(needle)

    if i == -1 {
      raise ValueError('${needle} not in list')
    }

    return items[i]
  } as e {
    echo 'handled: ' + e.message
    return nil
  }
}

echo find([1, 2], 2)
echo find([1, 2], 9)

2
handled: 9 not in list
nil

Nesting

Handlers can raise, and an outer catch will see it:

catch {
  catch {
    raise Error('inner')
  } as inner {
    raise Error('outer: ' + inner.message)
  }
} as outer {
  echo outer.message
}

outer: inner

assert Versus raise

assert items.length() > 0, 'caller must pass a non-empty list'

assert raises an AssertError when its condition is falsy. The message is optional.

Draw the line like this. raise is for things that happen: a file that is not there, a number that does not parse, a network that times out. The caller is expected to handle it. assert is for things that cannot happen: an invariant the code itself is responsible for maintaining. A failed assertion means the program has a bug, not that the world was uncooperative.

Style

Keep the catch block small. The block should contain the operation that can fail and nothing else, so the handler is not accidentally catching a mistake somewhere further down:

Too wide — a failure inside render() is reported as a parse failure:

def show_wide(text) {
  catch {
    var data = json.decode(text)
    render(data)
  } as e {
    echo 'bad json'
  }
}

Right — only the call that can fail is inside the block:

def show_narrow(text) {
  var data

  catch {
    data = json.decode(text)
  } as e {
    echo 'bad json: ' + e.message
    return
  }

  render(data)
}

Note the var data outside the block. A catch block is a scope like any other, so a variable declared inside it is gone by the time the next statement runs.

Write messages that name the value:

raise ValueError('port must be between 1 and 65535, got ${port}')

The person reading that message is trying to work out what went wrong from one line of a log file. Give them the number.

Catching Inside a Loop

A catch inside a loop body handles one iteration and lets the rest carry on. This is the shape for processing a batch where individual items are allowed to fail:

def parse_positive(text) {
  if !text.match('/^\d+$/') {
    raise ValueError('not a number: ${text}')
  }

  var n = text.to_number()

  if n <= 0 {
    raise ValueError('must be positive: ${text}')
  }

  return n
}

var inputs = ['12', 'not a number', '30']
var total = 0
var rejected = []

for raw in inputs {
  catch {
    total += parse_positive(raw)
  } as e {
    rejected.append(raw)
  }
}

echo total
echo rejected

42
[not a number]

Put the catch outside the loop instead, and the first failure ends the whole loop — which is the right choice when one bad item makes the rest meaningless, and the wrong one when it does not. The placement of the block is the decision; there is no flag to set.

Nesting and Re-raising

A catch inside a handler works like any other, which is how you translate a low-level failure into one your caller understands:

import json

class ConfigError < Error {

  @new(message) {
    parent(message)
    self.type = 'ConfigError'
  }
}

def load(text) {
  catch {
    return json.decode(text)
  } as e {
    raise ConfigError('config is not valid JSON: ${e.message}')
  }
}

catch {
  load('{ broken')
} as e {
  echo '${e.type}: ${e.message}'
}

The caller now gets an error in its own vocabulary. Include the original message, as above, so the detail is not lost on the way up.

Re-raising the same error, rather than a new one, keeps the original stack trace pointing at the original line:

def only_handle_missing(work) {
  catch {
    return work()
  } as e {
    if !instance_of(e, ModuleNotFoundError) {
      raise e
    }

    return 'defaulted'
  }
}

echo only_handle_missing(@() => 'fine')

catch {
  only_handle_missing(@() { raise ValueError('not mine') })
} as e {
  echo '${e.type}: ${e.message}'
}

fine
ValueError: not mine

That is the pattern for “handle one kind and let everything else through”, and it is worth reaching for whenever a handler would otherwise swallow a bug along with the failure it meant to catch.

A Worked Example

Here is the whole chapter in one function: a loader that validates its input, distinguishes the failures a caller can act on from the ones it cannot, and closes what it opened on every path.

import json

class StoreError < Error {

  @new(message) {
    parent(message)
    self.type = 'StoreError'
  }
}

def read_records(path) {
  var handle = file(path)

  if !handle.exists() {
    raise StoreError('no store at ${path}')
  }

  var records

  catch {
    records = json.decode(handle.read())
  } as e {
    handle.close()
    raise StoreError('${path} is corrupt: ${e.message}')
  }

  handle.close()

  if !is_list(records) {
    raise StoreError('${path} should hold a list, found ${typeof(records)}')
  }

  return records
}

file('records.json', 'w').write('[{"id": 1}]')
echo read_records('records.json').length()

file('records.json', 'w').write('{ not json')

catch {
  read_records('records.json')
} as e {
  echo e.type
}

file('records.json').delete()

catch {
  read_records('records.json')
} as e {
  echo '${e.type}: ${e.message}'
}

1
StoreError
StoreError: no store at records.json

Four things in there are worth naming.

Every failure the caller might reasonably handle arrives as one error type, StoreError, so catch on the calling side needs one branch rather than three.

The message always names the path. A log line saying “file is corrupt” with no filename costs someone an hour.

handle.close() appears on both paths — once in the handler before the re-raise, once after the block. There is no finally to do it for you, and forgetting the one in the handler is the most common resource leak in Zuri code.

And the shape check at the end is a raise, not an assert. A file on disk containing the wrong thing is the world being uncooperative, not a bug in this function.

The Module System

A module is a .zu file. It runs at most once per program, it gets its own global namespace, and nothing it declares is visible anywhere else until someone imports it.

That is the whole model. The rest of this chapter is the syntax and the resolution rules.

Importing

import math
import os

echo math.PI
echo os.cwd()

import name binds the module under that name. Reach into it with a dot.

Picking Out Members

import math { PI, E }

echo PI

The named members are bound directly, and the module name itself is not.

{ * } brings in everything public:

import math { * }

echo PI
echo ROOT_2

Renaming

import http.websocket as ws

Use this when the natural name is long, or when it would collide.

as renames the module, not a member. There is no way to rename an individual name in a member list — import math { PI as pi } does not parse. When you want a different name for one imported thing, bind it yourself:

import math { PI }

var pi = PI

echo pi

3.141592653589793

Relative Imports

A path starting with . or .. is resolved against the directory of the file doing the importing, and is never searched for anywhere else.

import .helpers             # next to this file
import .models.user         # models/ next to this file, then user
import ..shared.config      # up one directory, then shared/, then config
import .. ..shared.config   # up two directories, then shared/, then config

Each .. climbs one directory, so .. .. climbs two and .. .. .. three. The dots may also be written together, ....shared.config, and it is the same import: a run of dots counts two for each directory up. zuri fmt leaves whichever way the path is written as it is.

Each segment resolves the same way a bare name does: name.zu is tried first, then name/index.zu. So import .helpers finds either helpers.zu or helpers/index.zu, and import .models.user finds models/user.zu or models/user/index.zu, with models itself being a directory either way.

Which one it finds is invisible at the import site, and that is what lets a module grow into a package: split helpers.zu into helpers/index.zu plus some siblings, and every import .helpers keeps working untouched.

Inside a package, a sibling is always import .sibling, never the full path from the project root. Writing import myapp.models.user from inside myapp/models/ sends the resolver out to the library search path and it will not find anything.

Exporting

Imports are local by default. If a.zu imports b.zu, a third file that imports a does not see b’s contents through it.

Prefix the path with @ to re-export:

import @.util { * }

Now everything util.zu exposed is part of this module’s public surface too. All three forms take the prefix:

import @.module            # the module itself is re-exported
import @.module { item }   # just that item
import @.module { * }      # everything

This is how a package’s index.zu assembles a public API out of several private files:

Filename: pkg/index.zu

import @.util { * }
import .sub.deep { deep_slug }

def hello() {
  return 'hello from pkg ' + VERSION
}

util’s members are re-exported. deep_slug is imported for this file’s own use and stays private.

Privacy

A member whose name starts with _ is private to its module and cannot be imported by name:

import .pkg.util { _secret }

SyntaxError: Cannot import private items from module
  --> /path/to/bad.zu:1:20
  |
1 | import .pkg.util { _secret }
  |                    ^

{ * } skips private members too. Prefix anything that is an implementation detail and the module system will keep it that way.

Packages

A directory with an index.zu is a package, and importing the directory runs its index.zu:

pkg/
  index.zu
  util.zu
  sub/
    deep.zu

import .pkg            # runs pkg/index.zu
import .pkg.util       # runs pkg/util.zu
import .pkg.sub.deep   # runs pkg/sub/deep.zu

The same rule applies to zuri run pkg on the command line, which is what makes a package runnable as well as importable.

How a Bare Name Is Resolved

import http, with no leading dot, is searched for in this order:

1. .zuri/libs/http in the project
2. $ZURI_ROOT/libs/http, or libs/http beside the zuri executable: the standard library
3. a built-in native module named http
4. $ZURI_HOME/libs/http, the packages installed for your user, which is ~/.zuri/libs unless ZURI_HOME moves it

At each step, http.zu is tried first and then http/index.zu.

The project is the nearest directory holding a project.toml, looking upwards from the script zuri run was given, or from the working directory for a command or the REPL. A program run from anywhere inside a project imports that project’s packages, and a program in no project uses .zuri/libs in the working directory. The project is found once, when the program starts, so changing directory part way through does not change where imports come from.

zuri install fills .zuri/libs, and Packages and Nyssa covers it in full. Step one is also what makes vendoring work. Dropping a file into .zuri/libs/ shadows a standard library module of the same name:

$ cat .zuri/libs/mylib.zu
def hi() { return 'from user libs' }

$ cat uses.zu
import mylib
echo mylib.hi()

$ zuri run uses.zu
from user libs

Modules Run Once

A module’s top level executes the first time it is imported, and never again. Every later import of the same file gets the same module object:

import .once
import .once as again
import .once

side effect ran

One line of output, three imports. Identity is by canonical filesystem path, so two different relative paths to the same file are the same module.

This makes a module’s top level the natural place for setup that must happen exactly once: opening a connection pool, reading a config file, registering handlers.

Circular Imports

A circular import works. A module is registered before its body runs, so when b.zu imports a.zu while a.zu is still loading, it gets the partially built module rather than looping forever:

Filename: a.zu

import .b

def from_a() {
  return 'a'
}

echo 'a loaded'

Filename: b.zu

import .a

echo 'b loaded'

b loaded
a loaded
a

The catch is visible in that output: b finished loading before a did, so anything b reads from a at its top level is not there yet. Reading it from inside a function is fine, because by then a has finished.

If a module fails while loading, it is dropped from the cache rather than left behind half built, so a later import genuinely retries.

Module Variables

Every module gets two names for free:

echo __file__
echo __root__

__file__ is this module’s own canonical path. __root__ is the entry file the program was started from, and it is the same in every module. Use them to locate files relative to your source rather than relative to whatever directory the user happened to run from:

import os

var templates = os.join_paths(os.dir_name(__file__), 'templates')

In the REPL both are defined, with placeholder values standing in for the file that does not exist:

%> __file__
@.repl
%> __root__
@.repl.root

They differ from each other there, so the __root__ == __file__ check below is false at the prompt — a REPL session is never the entry point of a program.

Running as a Program, Importing as a Module

Because __root__ is the entry file and __file__ is this one, comparing them tells a module whether it is the program being run or something being imported:

Filename: tool.zu

def add(a, b) {
  return a + b
}

if __root__ == __file__ {
  echo 'running as a program: ' + add(2, 3)
}

$ zuri run tool.zu
running as a program: 5

import .tool
echo tool.add(10, 20)

30

The same file is a clean, side-effect-free library when imported and a runnable command-line program when launched directly. Put the argument parsing and the entry point behind that check, and everything else above it.

These two names describe which file this is, so they are not exports. A wildcard import copies every public name out of the module it names, and __file__ and __root__ are deliberately excluded from that:

import math { * }

echo __file__ == __root__

true

That guarantee is what makes the __root__ == __file__ check above reliable in every file, including one that wildcard-imports a sibling.

Structuring a Project

A small program is one file. Past that, the shape that works is a package per area of responsibility, each with an index.zu that re-exports what is public:

myapp/
  index.zu          # import @.routes, import @.models, then start
  config.zu
  models/
    index.zu        # import @.user { * }, import @.task { * }
    user.zu
    task.zu
  routes/
    index.zu
    api.zu
    pages.zu
  storage/
    index.zu
    _json_store.zu  # private: the leading underscore says so

Run it with zuri run myapp. The capstone in Chapter 25 is laid out exactly this way.

A Package, End to End

Here is the smallest complete version of that shape. Three files, one package, one public entry point.

Filename: greet/english.zu

def hello(name) {
  return 'Hello, ${name}'
}

def _shout(text) {
  return text.upper()
}

Filename: greet/french.zu

def hello(name) {
  return 'Bonjour, ${name}'
}

Filename: greet/index.zu

import @.english
import @.french

def greet(name, language) {
  return language == 'fr' ? french.hello(name) : english.hello(name)
}

Filename: index.zu

import .greet

echo greet.greet('Ada', 'en')
echo greet.greet('Ada', 'fr')
echo greet.english.hello('Grace')

$ zuri run
Hello, Ada
Bonjour, Ada
Hello, Grace

Four things to take from it.

greet/index.zu is what import .greet loads. A directory with an index.zu is a package, and importing the directory runs that file.

The @ on import @.english is what re-exports it. Without it, greet.english would not be reachable from outside greet/index.zu, even though greet() itself would still work — which is often exactly what you want.

Both submodules define hello, and they do not collide. Each lives in its own namespace, reached through its own module name. That is the whole reason to use import @.english rather than import @.english { * } here.

_shout is unreachable from outside. Writing greet.english._shout(x) anywhere else is a compile error, not a runtime one:

SyntaxError: '_shout' is private and can only be accessed via 'self' or 'parent'

The leading underscore is the only declaration of privacy there is, and it is checked before the program runs.

Files and the Filesystem

Two things do the work here. The built-in file() function gives you a handle to one file. The os module covers everything else: directories, paths, globs, temporary files and the environment.

Opening a File

var handle = file('notes.txt')
var writer = file('notes.txt', 'w')

file(path) defaults to read mode. The second argument is the mode:

Append b to any of them for binary mode: 'rb', 'wb', 'ab'.

x is the one to reach for when two programs might create the same file. The existence check and the creation happen in a single step, so exactly one of them succeeds and every other one fails, which is what a lock file needs.

Creating a handle does not touch the disk. Nothing happens until you read, write or call open().

Reading a Whole File

file('notes.txt', 'w').write('It works!')

echo file('notes.txt').read()

It works!

read() with no argument opens the file, reads all of it, and closes it again. That is the one-liner for “give me this file’s contents”, and it is what you want most of the time.

In text mode you get a string, decoded strictly as UTF-8. In binary mode you get bytes.

Reading in Chunks

read(length) reads at most that many bytes and leaves the handle open, so you can call it again. This is how you process a file too large to hold in memory at once:

file('notes.txt', 'w').write('alpha\nbeta\ngamma\n')

var handle = file('notes.txt')
handle.open()

var chunks = 0

while true {
  var chunk = handle.read(6)

  if chunk.is_empty() {
    break
  }

  chunks++
}

handle.close()

echo chunks

3

Six bytes at a time is a demonstration; in real code the chunk is tens of kilobytes. The shape is what matters: open once, read until you get an empty result, close once.

Note that chunks fall wherever the byte count lands, not on line boundaries. A chunked reader that needs whole lines has to keep the tail of each chunk and join it to the front of the next.

Reading Lines

For text you want line by line, the simplest form reads the file and splits it:

file('notes.txt', 'w').write('alpha\nbeta\ngamma\n')

for line in file('notes.txt').read().lines() {
  echo '[${line}]'
}

[alpha]
[beta]
[gamma]

lines() handles both \n and \r\n, and drops the trailing empty piece a final newline would otherwise produce.

Writing

file('notes.txt', 'w').write('It works!')

Like read(), write() opens the handle if it is closed, writes, flushes, and closes it again. One call, one complete file.

That auto-close has a consequence worth being precise about. Two consecutive write() calls on a closed handle in w mode each truncate the file, so only the last one survives. When you are writing more than once, open the handle yourself:

var handle = file('notes.txt', 'w')
handle.open()

handle.write('first line\n')
handle.write('second line\n')

handle.close()

echo file('notes.txt').read()

first line
second line

The explicit open() is what keeps the handle open across both writes. Without it, each write() would open, truncate, write and close, and only second line would survive.

An already-open handle is written to where it stands, so the sequence above does exactly what it reads like.

puts() writes without ever opening or closing. It requires an open handle, and it is the method to reach for inside a loop.

Reading and Writing at a Position

var handle = file('notes.txt')
handle.open()

handle.seek(6, 0)
echo handle.tell()
echo handle.read(4)

handle.close()

seek(offset, whence) takes 0 for the start of the file, 1 for the current position and 2 for the end. The io module names them:

import io

handle.seek(0, io.SEEK_SET)
handle.seek(-10, io.SEEK_END)

tell() reports the current offset.

Asking About a File

var handle = file('notes.txt')

echo handle.exists()
echo handle.path()
echo handle.abs_path()
echo handle.name()
echo handle.mode()
echo handle.is_open()
echo handle.is_closed()

stats() returns a dictionary of metadata about the file on disk:

file('notes.txt', 'w').write('alpha\nbeta\n')

var info = file('notes.txt').stats()

echo info.size
echo info.is_readable
echo info.keys()

11
true
[is_readable, is_writable, is_executable, is_symbolic, size, mode, dev, ino, nlink, uid, gid, mtime, atime, ctime, blocks, blksize]

size is in bytes. mtime, atime and ctime are epoch seconds, ready to hand to the date module. mode is the raw permission-and-type word, and the stat module is what turns it into an answer:

import stat

file('notes.txt').chmod(0c644)

var info = file('notes.txt').stats()

echo stat.S_ISREG(info.mode)
echo stat.S_ISDIR(info.mode)
echo stat.file_mode(info.mode)

true
false
-rw-r--r--

S_ISREG, S_ISDIR, S_ISLNK and the rest of the family each answer one question about the kind of entry. file_mode() renders the permission bits the way ls -l does.

Managing Files

file('notes.txt').copy('backup.txt')
file('backup.txt').rename('archive.txt')
file('archive.txt').delete()

There is also truncate(length), chmod(mode), set_times(access, modify) and symlink(target).

Always Close What You Opened

read() and write() clean up after themselves. Anything you opened with open() is yours to close, and the cleanest way to guarantee it is a catch that closes on the way out:

var handle = file(path, 'w')
handle.open()

catch {
  write_everything(handle)
} as e

handle.close()

if e {
  raise e
}

For something that has to be cleaned up however the program ends, rather than however one block ends, register it with os.at_exit():

import os

var scratch = file('scratch.txt', 'w')
scratch.open()

os.at_exit(@{
  scratch.close()
  scratch.delete()
})

scratch.write('working notes')
echo scratch.is_open()

true

Handlers run last registered first, and they run whether the program reached the end of its script, called os.exit(), or stopped on an uncaught error. A handler that raises is reported on standard error and the rest still run, so one failed cleanup cannot cancel the others.

Directories

import os

os.create_dir('sub/deep', nil, true)

The three arguments are the path, the permission bits, and whether to create intermediate directories. It returns false when the directory already existed.

echo os.dir_exists('sub')
echo os.is_dir('sub')
echo os.remove_dir('sub', true)

remove_dir’s second argument makes it recursive.

Listing and Globbing

Everything in this section works on a real tree, so build one first:

import os

os.create_dir('tree/sub', nil, true)

file('tree/top.txt', 'w').write('a')
file('tree/sub/nested.txt', 'w').write('b')
file('tree/sub/notes.md', 'w').write('c')

read_dir() lists one directory:

echo os.read_dir('tree')
echo os.read_dir('tree', true)

[., .., sub, top.txt]
[., .., sub, sub/nested.txt, sub/notes.md, top.txt]

Three things to notice. . and .. are included, so a loop over the result almost always wants to skip them. The recursive form returns nested entries as paths relative to the directory you asked about, not as bare names, which is what makes them usable directly. And entries come back sorted by name, with a directory’s contents following immediately after it, so the listing reads the same on every machine and filesystem.

glob() is usually what you actually want:

echo os.glob('*.txt', 'tree')
echo os.glob('**/*.txt', 'tree')

[top.txt]
[sub/nested.txt]

* matches within one path segment; ** matches across segments. The second argument is the base directory, and results come back relative to it.

Read those two results together, because the distinction catches people out. *.txt found the file at the top and not the nested one. **/*.txt found the nested one and not the top-level one, because **/ means “in a subdirectory”. Neither pattern finds both.

To match at every depth, glob ** and filter:

echo os.glob('**', 'tree')
echo os.glob('**', 'tree').filter(@(p) => p.ends_with('.txt'))

[sub, sub/nested.txt, sub/notes.md, top.txt]
[sub/nested.txt, top.txt]

** on its own matches every entry at every depth, directories included, which is why the filter is doing real work in the second line. glob() walks with read_dir() underneath, so matches arrive in that same sorted order.

Clean up when you are done:

echo os.remove_dir('tree', true)

true

Paths

Every path function is pure string manipulation except where noted:

echo os.join_paths('sub', 'a.txt')
echo os.base_name('sub/a.txt')
echo os.dir_name('sub/a.txt')
echo os.real_path('sub')
echo os.relative_path(os.cwd(), '/full/path/to/sub')

sub/a.txt
a.txt
sub
/home/you/project/sub
sub

real_path() resolves symlinks and requires the path to exist. abs_path() does not. expand_user() turns a leading ~ into the home directory. path_contains(base, candidate) answers whether one path is inside another, which is the check you need before serving a file a user named.

echo os.cwd()
echo os.home_dir()
os.change_dir('/some/where')

Temporary Files

echo os.temp_dir()

var path = os.create_temp_file('report-', '.csv')
var dir = os.create_temp_dir('build-')

Both create the thing and hand you its path. Clean them up yourself when you are done.

Environment Variables

echo os.get_env('HOME')
echo os.get_env('NOPE', 'fallback')

os.set_env('ZURI_BOOK', '1')
os.unset_env('ZURI_BOOK')

echo os.environ()
echo os.expand_vars('$HOME/projects')

get_env() takes a fallback. environ() gives the whole set as a dictionary.

Locating Files Relative to Your Code

The current working directory is wherever the user ran zuri from, which is not where your source lives. Use __file__:

import os

var HERE = os.dir_name(__file__)
var templates = os.join_paths(HERE, 'templates')

Doing this in every module that reads a file next to itself is the difference between a program that works and one that works only from the project root.

A Worked Example

Counting words across every text file in a directory tree, start to finish:

import os

def text_files(root) {
  return os.glob('**', root).filter(@(p) => p.ends_with('.txt'))
}

def word_count(root) {
  var counts = {}

  for path in text_files(root) {
    var text = file(os.join_paths(root, path)).read()

    for word in text.lower().split('/\W+/') {
      if word.is_empty() {
        continue
      }

      counts.set(word, counts.get(word, 0) + 1)
    }
  }

  return counts
}

os.create_dir('wc/sub', nil, true)

file('wc/a.txt', 'w').write('Hello world, hello!')
file('wc/sub/b.txt', 'w').write('World of Zuri.')
file('wc/sub/skip.md', 'w').write('not counted')

echo word_count('wc')

os.remove_dir('wc', true)

{hello: 2, world: 2, of: 1, zuri: 1}

Four things in that function are worth pointing at.

glob('**', root) returns paths relative to the root, so they have to be joined back onto it before they can be opened. Forgetting that join is the most common mistake in code that globs.

The .md file is absent from the result because text_files() filtered it out, which is the filter doing the job ** alone cannot.

split('/\W+/') is a regular expression, which is why punctuation does not end up in the keys — world, and hello! became world and hello. A plain split(' ') would have kept both.

And counts.get(word, 0) + 1 supplies the starting value for a key that does not exist yet. Without the fallback, the first sighting of every word would raise.

Where to Go Next

Binary files, byte streams and the io module’s in-memory files are Chapter 10. Reading a file over the network is Chapter 12. The complete list of methods a file handle carries is Appendix E.

Binary Data and Streams

Text is convenient. Protocols, file formats, images and checksums are not text, and this chapter is about the four tools Zuri gives you for them: the bytes type, the struct module, io.BytesIO, and compress.

The bytes Type

bytes is a mutable buffer of 8-bit values.

var b = bytes(3)
var c = bytes([1, 2, 3, 4, 5])
var d = 'Hi'.to_bytes()

echo b
echo c
echo d

(00 00 00)
(01 02 03 04 05)
(48 69)

bytes(n) allocates n zero bytes. bytes(list) builds one from numbers, each of which must be in 0..256. to_bytes() on a string gives you its UTF-8 encoding.

The hexadecimal-in-parentheses rendering is how bytes always prints, which makes it impossible to confuse one with a list at a glance.

Reading

var b = bytes([1, 2, 3, 4, 5])

echo b.length()
echo b[0]
echo b[1, 3]
echo b.first()
echo b.last()
echo b.get(2)
echo b.index_of(3)
echo b.last_index_of(3)
echo b.to_list()
echo 'Hi'.to_bytes().to_string()

5
1
(02 03)
1
5
3
2
2
[1, 2, 3, 4, 5]
Hi

Indexing gives a number. Slicing gives bytes. to_string() decodes as UTF-8, to_list() gives numbers.

index_of() and last_index_of() both return -1 when the byte is not there, and both take a second argument bounding where a match may sit, so they search the two halves either side of one index.

Slicing

b[a, b] takes the bytes from a up to but not including b, and returns a new byte stream:

var b = bytes([10, 20, 30, 40, 50])

echo b[1, 3]
echo b[, 3]
echo b[3, ]
echo b[-2, ]

(14 1e)
(0a 14 1e)
(28 32)
(28 32)

The rules are exactly the list’s. Either bound may be omitted: b[, n] starts at the beginning and b[n, ] runs to the end. Negative bounds count back from the end, so b[-2, ] is the last two bytes.

Note the difference between an index and a slice, because for bytes the two return different types:

var b = bytes([10, 20, 30])

echo b[0]
echo typeof(b[0])
echo b[0, 1]
echo typeof(b[0, 1])

10
number
(0a)
bytes

One index gives you the numeric value of that byte. A slice of length one gives you a byte stream containing it. Reaching for b[0] when you meant b[0, 1] is the most common slip here, and it shows up as a number where a bytes was expected rather than as an error at the slicing site.

Bounds Are Checked

A slice that runs past the end raises rather than returning what it can:

var b = bytes([10, 20, 30, 40, 50])

catch {
  echo b[1, 99]
} as e {
  echo '${e.type}: ${e.message}'
}

RangeError: slice bounds 1..99 out of range (length 5)

length() itself is always a legal upper bound, because the bound is exclusive, and an empty slice is legal rather than an error:

var b = bytes([10, 20, 30, 40, 50])

echo b[0, b.length()]
echo b[2, 2]
echo b[2, 2].is_empty()

(0a 14 1e 28 32)
()
true

An empty byte stream prints as ().

A Slice Is a Copy

Slicing allocates a new stream, so writing through one does not disturb the original:

var original = bytes([10, 20, 30])
var part = original[0, 2]

part[0] = 99

echo original
echo part

(0a 14 1e)
(63 14)

That matters when you are parsing a buffer. Pulling a header out with frame[0, 4] gives you something you can modify freely, and the frame you are still reading from is untouched. It also means slicing in a loop copies every time, so a parser that walks a large buffer should carry an offset and slice once per field rather than re-slicing the remainder each step.

Slice, Then Decode

The common shape when a buffer holds text with a known extent:

var b = bytes([72, 101, 108, 108, 111, 33])

echo b[0, 5].to_string()
echo b.to_string()

Hello
Hello!

to_string() decodes the whole stream it is called on, so the slice is what limits the extent. Slicing on a byte boundary in the middle of a multi-byte character produces a stream that is not valid UTF-8; decode whole units, or keep the tail for the next read.

There Is No Slice Assignment

A slice can be read but not written to:

var b = bytes([10, 20, 30])

b[0, 2] = bytes([1, 1])

SyntaxError: invalid assignment target

Assign to one index at a time, or rebuild the stream with extend(). A single index does accept assignment, and the value has to be a real byte:

var b = bytes([72, 101, 108, 108, 111, 33])

b[0] = 74

echo b.to_string()

catch {
  b[1] = 300
} as e {
  echo '${e.type}: ${e.message}'
}

Jello!
NumericError: bytes element must be an integer in 0..=255, got 300

Note the difference from bytes([300]), which wraps rather than raising. Construction is lenient; assignment is not.

Writing

var b = bytes([1, 2, 3])

b.append(4)
b.extend(bytes([9]))
echo b
echo b.pop()
echo b.reverse()

(01 02 03 04 09)
9
(04 03 02 01)

Unlike a list, bytes.reverse() mutates in place. So do append, extend, pop and remove.

dispose() releases the buffer’s memory immediately rather than waiting for the collector, which matters when you have just finished with something very large.

Splitting

split() takes a bytes delimiter, not a number:

echo bytes([1, 2, 3, 4, 5]).split(bytes([3]))

[(01 02), (04 05)]

Walking

A byte stream is iterable, and every form that works on a list works here. What you get out is always a number between 0 and 255, never a one-character string.

var b = bytes([72, 105])

for value in b {
  echo value
}

72
105

Two variables give you the index first and the value second:

var b = bytes([72, 105])

for index, value in b {
  echo '${index}: ${value}'
}

0: 72
1: 105

iter is the form to use when you are decoding a structure and the position drives the walk — reading a two-byte length, then skipping that many bytes, then reading the next field:

var b = bytes([72, 105, 33])

iter var i = 0; i < b.length(); i += 2 {
  echo '${i}: ${b[i]}'
}

0: 72
2: 33

And each() takes a function, with the value first and the index second as everywhere else:

bytes([72, 105]).each(@(value, index) {
  echo '${index}=${value}'
})

0=72
1=105

When you want the characters rather than the numbers, convert first: b.to_string() decodes the whole stream as UTF-8, and b.to_list() gives you the numbers as an ordinary list.

Binary Files

Append b to the file mode and reads give you bytes instead of a string, and writes accept bytes:

var out = file('data.bin', 'wb')
out.write(bytes([1, 2, 3]))
out.close()

echo file('data.bin', 'rb').read()

(01 02 03)

Reading a non-UTF-8 file without the b fails rather than silently producing replacement characters, which is the behaviour you want: a decoding failure is information.

struct: Packing and Unpacking

struct converts between Zuri values and a fixed binary layout. A format string is a sequence of /-separated fields, each CODE[COUNT][:NAME].

import struct

var header = struct.pack('N:magic/n:version/Z8:name/C:flags',
  0x5A555249, 1, 'task', 3)

echo header
echo header.length()
echo struct.unpack('N:magic/n:version/Z8:name/C:flags', header)

(5a 55 52 49 00 01 74 61 73 6b 00 00 00 00 03)
15
{magic: 1515541065, version: 1, name: task, flags: 3}

unpack() hands back a dictionary keyed by the :NAME you gave each field. Fields with no name get numbered:

echo struct.unpack('N/N', struct.pack('N2', 7, 8))

{1: 7, 2: 8}

A count greater than one under a single name numbers the keys:

echo struct.unpack('n3:vals', struct.pack('n3', 1, 2, 3))

{vals1: 1, vals2: 2, vals3: 3}

The Format Codes

Strings:

Integers. The letter tells you the width and the byte order:

Floats:

Padding:

n, N and J are the network-order codes, which is what you want for almost every wire protocol.

A count of * means “the rest”.

Precision

Zuri numbers are doubles, so they hold integers exactly only up to 2^53. Every 64-bit and 128-bit code (q, Q, J, P, u, U) automatically produces a bigint when the unpacked value falls outside that range, rather than quietly losing digits. Packing accepts either.

The Rest of the Module

calcsize(format) gives the fixed byte size of a format with no * in it. pack_into(buffer, offset, format, ...) and unpack_from(format, buffer, offset) work on an existing buffer at a position, which is how you build one large frame without allocating and concatenating per field.

io.BytesIO

BytesIO is a file-shaped object backed by memory. It implements the same interface file() handles do, which means anything that takes a file takes a BytesIO too:

import io

var buffer = io.BytesIO(bytes(0), 'w')

buffer.write('hello ')
buffer.write('world')

echo buffer.source.to_string()

hello world

The constructor takes a bytes source and a mode. It has read, gets, write, puts, seek, tell, flush, close and stats, so a function written against files needs no changes to work in memory.

That is the useful part: test a function that writes a file without touching the disk, and parse an in-memory buffer with code written for a stream.

Compression

The compress module has a submodule per format, each with compress() and decompress():

import compress

var raw = ('the quick brown fox ' * 20).to_bytes()

echo raw.length()
echo compress.gzip.compress(raw).length()
echo compress.deflate.compress(raw).length()
echo compress.zstd.compress(raw).length()
echo compress.brotli.compress(raw).length()
echo compress.bzip2.compress(raw).length()
echo compress.lz4.compress(raw).length()

400
47
29
41
31
75
37

The formats are deflate, zlib, gzip, zstd, lz4, bzip2 and brotli. zlib is re-exported at the top level, so compress.compress() and compress.decompress() are the zlib pair:

echo compress.decompress(compress.compress(raw)).to_string() == raw.to_string()

true

Which to reach for: gzip when something else has to read it, zstd when you want the best ratio-to-speed trade, lz4 when speed is the only thing that matters, brotli for text you will serve over HTTP.

Archives

compress.tar and compress.zip read and write archives, and compress.checksum has crc32() and adler32():

import compress

echo compress.checksum.crc32('hello'.to_bytes())

907060870

Hashing and Encoding

base64 moves binary through text channels:

import base64

var encoded = base64.encode('hello'.to_bytes())

echo encoded
echo base64.decode(encoded).to_string()

aGVsbG8=
hello

hash covers the digest algorithms:

import hash

echo hash.sha256('hello')
echo hash.hmac_sha256('key', 'hello')

2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
9307b3b915efb5171ff14d8cb55fbcc798c6c0ef1456d66ded1a6aa723a58b7b

Every function takes an optional final as_bytes argument; pass true to get raw bytes instead of a hex string.

The algorithms are md2, md4, md5, sha1, sha224, sha256, sha384, sha512, the sha3 family, shake128/256, blake2b512, blake2s256, ripemd160, whirlpool and gost, each with an hmac_ counterpart, plus pbkdf2() for key derivation. hash.hash(algorithm, data) selects by name at runtime.

For password storage, use bcrypt rather than any of these. A fast hash is the wrong tool for a password, and Chapter 13 covers the right one.

A Worked Example: A Length-Prefixed Frame

Most binary protocols are a header followed by a payload. Here is the whole round trip:

import struct
import compress

var HEADER = 'N:length/C:compressed'

def encode_frame(payload) {
  var body = payload.to_bytes()
  var compressed = 0

  if body.length() > 128 {
    body = compress.gzip.compress(body)
    compressed = 1
  }

  var frame = struct.pack(HEADER, body.length(), compressed)
  frame.extend(body)

  return frame
}

def decode_frame(frame) {
  var size = struct.calcsize('N/C')
  var header = struct.unpack(HEADER, frame[0, size])
  var body = frame[size, size + header.length]

  if header.compressed == 1 {
    body = compress.gzip.decompress(body)
  }

  return body.to_string()
}

var frame = encode_frame('ping')
echo frame
echo decode_frame(frame)

echo decode_frame(encode_frame('the quick brown fox ' * 20)).length()

(00 00 00 04 00 70 69 6e 67)
ping
400

calcsize() tells you where the header ends, slicing gives you the two halves, and the compressed flag is one byte because a protocol that has to guess is a protocol that breaks.

Concurrency with Isolates

Zuri’s concurrency model has one rule: nothing is shared.

An isolate is a real operating-system thread running a complete, private VM. It has its own heap, its own garbage collector, its own register stack and its own module namespace. Two isolates never hold a pointer to the same object, which means there are no data races to reason about, no locks to take, and no stop-the-world pause in one thread caused by allocation in another.

Values cross between isolates by being copied. The copy is a faithful one: cycles are preserved, shared identity inside one payload is preserved, and class instances arrive as instances of the same class.

Spawning

import isolate

def square(n) {
  return n * n
}

var task = isolate.spawn(square, 12)

echo task.join()

144

spawn(fn, ...args) queues the call and returns an Isolate handle immediately. join() waits for it and gives you the result. Calling join() again returns the same value; it is not a one-shot.

What Can Be Spawned

Any function: a top-level def, a helper declared inside another function, a lambda, a bound method. What it captures travels with it, including the modules it uses:

import isolate
import json

def encode_all(items) {
  return items.map(@(item) => json.encode(item)).length()
}

echo isolate.spawn(encode_all, [{ a: 1 }, { b: 2 }]).join()

2

A module is not copied the way a list is. The isolate loads the same module for itself and uses its own copy, which is why this works at all: module top levels are declarations, they run once, and the result is cached. A module built out of live per-process state is the case to think twice about, since the isolate gets a fresh one rather than yours.

Two things still cannot be spawned. A native function or a class as the spawn target itself; wrap it in a def. And a resource handle such as an open socket or file is moved rather than copied, so the side that handed it over no longer has it.

Putting the worker in its own module stays the better structure once it grows past a few lines:

Filename: work.zu

import net

def serve(channel) {
  var listener = net.TcpStream()
  # ...
}

Filename: main.zu

import isolate
import .work

isolate.spawn(work.serve, channel)

That is the shape the rest of this book uses. A worker reached by name is resolved in the isolate’s own namespace, so nothing about it has to be reconstructed.

An import written inside the function body works too, and runs in the isolate:

import isolate

def make_id() {
  import uuid

  return uuid.v4().to_string().length()
}

echo isolate.spawn(make_id).join()

36

The arguments are copied, not shared. An isolate that mutates a list it was handed is mutating its own copy:

import isolate

def append_to(items) {
  items.append('from the isolate')
  return items.length()
}

var original = ['a']

echo isolate.spawn(append_to, original).join()
echo original

2
[a]

The isolate saw two elements. The caller still has one. That is the whole concurrency model in one example: there is no way to write a data race, because there is nothing shared to race over.

Running Many at Once

Spawn a list, join a list:

import isolate

def square(n) {
  return n * n
}

var tasks = [1, 2, 3, 4].map(@(n) => isolate.spawn(square, n))

echo tasks.map(@(task) => task.join())

[1, 4, 9, 16]

isolate.map() does exactly that in one call:

import isolate

def square(n) {
  return n * n
}

echo isolate.map(square, [1, 2, 3, 4, 5])

[1, 4, 9, 16, 25]

wait_all(tasks, timeout) waits for every task; wait_any(tasks, timeout) returns as soon as one finishes.

The Lifecycle of a Task

A spawned task moves through exactly two states, and four methods let you ask about it without blocking.

import isolate
import .work

var task = isolate.spawn(work.slow, 3)

echo task.try_join()
echo task.is_done()
echo task.status()

echo task.join()
echo task.status()

nil
false
pending
finished
done

try_join() returning nil is ambiguous when the task’s own result could be nil; pair it with is_done() when that matters.

join() may be called more than once. It is not a one-shot: the second call returns the same value immediately.

Naming a Task

spawn() leaves a task anonymous. spawn_named() gives it a name that shows up in diagnostics:

var named = isolate.spawn_named('importer', work.quick, 5)
var plain = isolate.spawn(work.quick, 5)

echo named.name()
echo plain.name()

importer
nil

Name anything long-running. A stuck program is far easier to diagnose when the task can say what it is.

Timeouts Are in Seconds

Every timeout in the isolate module is measured in seconds, and it takes a fraction:

import isolate

var empty = isolate.channel(1)
var start = time()

catch {
  empty.recv(0.3)
} as e {
  echo '${e.type} after about ${((time() - start) * 10).round() * 100}ms'
}

IsolateTimeoutError after about 300ms

This applies to join(), send(), recv(), select(), wait_any(), wait_all() and shutdown() alike.

It is worth stating loudly because the net module uses milliseconds for its own timeouts. socket.set_read_timeout(5000) is five seconds; channel.recv(5000) is an hour and twenty minutes. The two modules are easy to use in one program, and the mistake is silent — a timeout that never fires simply looks like a hang.

Omitting the timeout means “wait forever”, which is the right default when the other side is code you control and the wrong one when it is not.

Cancellation Is Cooperative

cancel() requests that a task stop. It does not kill anything.

What happens next depends on what the task is doing:

Blocked in a channel operation, a join(), a wait_* or a select() — the call is interrupted within roughly 50ms and raises IsolateCancelledError.

Running ordinary code — nothing is interrupted. The task’s own function must notice and return:

import isolate

def slow(seconds) {
  var start = time()

  while time() - start < seconds {
    if isolate.is_cancelled() {
      return 'stopped early'
    }
  }

  return 'ran to completion'
}

isolate.is_cancelled() is the module-level function a worker calls about itself. task.is_cancelled() is the method the spawner calls to ask whether it requested cancellation — and it answers true from the moment cancel() was called, whether or not the task noticed:

var task = isolate.spawn(work.slow, 3)

task.cancel()

echo task.join()
echo task.is_cancelled()

ran to completion
true

That output is not a contradiction. The worker in this example does not poll, so it finished normally; is_cancelled() reports the request, not the outcome. A loop with no cancellation check is a loop that cannot be stopped.

Put the check where the loop turns over, and make it cheap. Checking once per iteration of an outer loop is usually enough; checking inside the innermost arithmetic is not worth it.

What Can Cross, and What It Costs

Arguments in, results out, and channel traffic all cross the same way: everything is copied. There is no sharing and no reference that survives the boundary.

The Copy Is Faithful

A copy is not a shallow snapshot. Cycles survive, shared identity inside one payload survives, and a class instance arrives as an instance of the same class with its methods intact:

import isolate

class Point {

  @new(x) {
    self.x = x
  }

  doubled() {
    return self.x * 2
  }
}

def identity(value) {
  return value
}

# A list that contains itself.
var cyclic = [1]
cyclic.append(cyclic)

# Two slots holding one list.
var shared = [1]
var pair = [shared, shared]

echo isolate.spawn(identity, Point(3)).join().doubled()
echo typeof(isolate.spawn(identity, cyclic).join())

var back = isolate.spawn(identity, pair).join()
back[0].append(2)

echo back[1].length()

6
list
2

The last line is the one to notice. pair held the same list twice, and on the other side it still does: appending through back[0] is visible through back[1]. The copy preserved the shape of the sharing, not just the values.

What Cannot Cross

A handful of things are tied to the isolate that made them, and sending one raises rather than silently producing something broken:

import isolate

def identity(value) {
  return value
}

catch {
  isolate.spawn(identity, file('notes.txt'))
} as e {
  echo e.message.lines()[0]
}

cannot send a file across isolates; only nil, bool, number, string, bytes, bigint, range, list, dict, instance, class, bound method, function, module, and native-pointer values can cross

The message lists what can cross, which is the more useful half. An open file is the one you will meet: it is a handle onto a position in a descriptor this process owns, and there is no copy of that to hand over. Send the path instead and let the worker open it.

The Cost Model

Spawning is cheap. A task is a small descriptor holding the callee and a snapshot of its arguments, pushed onto a queue the pool drains, so queueing a hundred thousand of them is reasonable.

What is not free is the copy. Handing an isolate a large list copies the whole list, once per spawn. When a worker needs a lot of data, give it a description of the work — a path, a range of indices, a query — and let it do its own reading:

# Copies the file's contents into every worker.
isolate.map(work.process, files.map(@(p) => file(p).read()))

# Copies a short path into every worker instead.
isolate.map(work.read_and_process, files)

Errors Cross the Boundary

An uncaught error inside an isolate surfaces at the join() as an IsolateError, carrying the original error’s message and the stack trace from inside the worker:

import isolate

def boom() {
  raise ValueError('worker failed')
}

catch {
  isolate.spawn(boom).join()
} as e {
  echo e.type
  echo e.message.lines()[0]
}

IsolateError
ValueError: worker failed

Nothing is lost. You get the failure where you can do something about it, with enough information to find it. Note the shape of the message: the IsolateError wraps the worker’s own error rather than replacing it, so e.message still names ValueError and the line it came from.

An error in a task nobody joins has nowhere to surface. That is what scope(), further down, exists to prevent.

Channels

A channel is a bounded queue that crosses isolate boundaries. One side sends, the other receives, and the values are copied on the way across like everything else:

import isolate

def producer(channel, count) {
  iter var i = 0; i < count; i++ {
    channel.send(i)
  }

  channel.close()
}

var channel = isolate.channel(4)
var task = isolate.spawn(producer, channel, 3)

while true {
  var value = channel.recv()

  if value == nil and channel.is_closed() {
    break
  }

  echo value
}

task.join()

0
1
2

Read the loop condition carefully, because it is the part that is easy to get wrong. recv() returns nil both for “a nil was sent” and for “the channel is closed and drained”, so the test for the end of the stream is nil and is_closed(). Checking only for nil would stop early on a legitimate nil; checking only is_closed() would stop before the queue had drained.

channel(capacity) bounds the queue, which gives you backpressure for free: a producer that outruns its consumer blocks on send() rather than growing the queue without limit.

Every one of those behaviours is observable from a single isolate, which makes a channel easy to reason about before you introduce a second one:

import isolate

var c = isolate.channel(2)

c.send('a')
c.send('b')

echo c.length()
echo c.try_recv()

c.close()

echo c.is_closed()
echo c.recv()
echo c.recv()

catch {
  c.send('z')
} as e {
  echo '${e.type}: ${e.message}'
}

2
a
true
b
nil
IsolateError: cannot send on a closed channel

Read the last four lines together. After close(), the queue still drains: recv() returned the buffered b before it started returning nil. A closed, drained channel returns nil forever rather than raising, and only send() raises.

Closing twice is harmless. try_recv() on an empty channel returns nil immediately and never blocks.

Selecting Across Channels

select() waits on several channels at once and tells you which one produced a value:

import isolate

var c1 = isolate.channel(1)
var c2 = isolate.channel(1)

c2.send('from c2')

var picked = isolate.select([c1, c2], 1000)

echo picked[1]

from c2

It returns [channel, value], so you can tell where the value came from by comparing the first element against the channels you passed in. The second argument is a timeout in seconds, like every other timeout in this module — see Timeouts Are in Seconds, because it is the opposite of what the net module does.

This is the shape for a consumer fed by more than one producer — work on one channel, shutdown signals on another — without polling either.

Broadcast

A channel delivers each value to exactly one receiver. A broadcast delivers each value to every subscriber:

import isolate

var bus = isolate.broadcast(4)

var a = bus.subscribe()
var b = bus.subscribe()

bus.send('tick')

echo a.recv()
echo b.recv()
echo bus.subscriber_count()

bus.close()

tick
tick
2

subscribe() hands back an ordinary Channel, so everything in the channel table applies to it: recv(), try_recv(), length(), and the same backpressure.

A Subscriber Only Sees What Comes After It

There is no replay. A subscriber that arrives late has missed everything sent before it subscribed:

import isolate

var bus = isolate.broadcast(4)
var early = bus.subscribe()

bus.send('first')

var late = bus.subscribe()

bus.send('second')

echo 'early: ${early.recv()}, ${early.recv()}'
echo 'late: ${late.try_recv()}'

early: first, second
late: second

This matters when subscribers are set up concurrently with the producer. Subscribe everything before anything is sent, or accept that a consumer starting later begins mid-stream.

Unsubscribing, and Sending Into the Void

unsubscribe(channel) drops one subscriber. Sending with none at all is not an error — the value is simply discarded:

import isolate

var bus = isolate.broadcast(4)
var sub = bus.subscribe()

bus.unsubscribe(sub)

echo bus.subscriber_count()
echo bus.send('nobody is listening')
echo sub.try_recv()

0
nil
nil

A dropped subscriber stops receiving new values immediately, and its channel keeps whatever was already queued in it:

import isolate

var bus = isolate.broadcast(4)
var sub = bus.subscribe()

bus.send('queued before unsubscribe')
bus.unsubscribe(sub)

echo sub.try_recv()

queued before unsubscribe

So unsubscribing is not a way to discard what a consumer has not read yet; it only stops the flow.

Closing

close() closes the bus and every channel it handed out. Subscribers drain what they have and then receive nil; send() raises:

import isolate

var bus = isolate.broadcast(4)
var sub = bus.subscribe()

bus.close()

echo bus.is_closed()
echo sub.try_recv()

catch {
  bus.send('too late')
} as e {
  echo e.type
}

true
nil
IsolateError

Backpressure Applies Per Subscriber

The capacity you give broadcast() is the capacity of each subscriber’s channel. A subscriber that stops reading fills its own buffer, and once it is full the bus blocks on send() — one slow consumer holds up the producer and therefore everyone.

When a slow consumer must not be allowed to do that, give the bus a larger capacity, or have that consumer read into its own queue and fall behind on its own time.

Channel or Broadcast?

Use a channel when the work should be done once, by whichever worker is free. Use a broadcast when every consumer needs to see every event. Shutdown signals, configuration changes and progress events are broadcasts; jobs are channels.

Scopes

A scope owns its children and does not return until all of them have finished:

import isolate

def square(n) {
  return n * n
}

var result = isolate.scope(@(s) {
  s.spawn(square, 3)
  s.spawn(square, 4)

  return s.children().map(@(child) => child.join())
})

echo result

[9, 16]

scope(body) calls body with a scope object, waits for everything spawned through it, and returns whatever the body returned.

It Waits Whether or Not You Join

Joining inside the body is how you collect results. It is not how the waiting happens — that is the scope’s job either way:

import isolate

def square(n) {
  return n * n
}

echo isolate.scope(@(s) {
  s.spawn(square, 3)
  s.spawn_named('four', square, 4)

  return s.children().length()
})

2

Neither child was joined, and the scope still did not return until both had finished. children() gives you the Isolate objects in spawn order, and s.spawn_named() works exactly like the module-level one.

A Failure Stops the Group

This is the real reason to use a scope. A bare spawn() whose result is never joined swallows its own error in silence; a scope raises:

import isolate

def ok(n) {
  return n
}

def boom() {
  raise ValueError('worker failed')
}

catch {
  isolate.scope(@(s) {
    s.spawn(ok, 1)
    s.spawn(boom)

    return 'never returned'
  })
} as e {
  echo '${e.type}: ${e.message.lines()[0]}'
}

IsolateError: ValueError: worker failed

The body’s return value is discarded when a child failed, and the failure comes out of scope() itself. Reach for a scope whenever a piece of work fans out and must be complete — and correct — before the next step begins.

Waiting on Several Tasks

Three helpers cover the shapes that come up, and they return different things:

import isolate

def square(n) {
  return n * n
}

var tasks = [1, 2, 3].map(@(n) => isolate.spawn(square, n))

echo isolate.wait_all(tasks)
echo typeof(isolate.wait_any([isolate.spawn(square, 9)]))
echo isolate.map(square, [4, 5])

[1, 4, 9]
Isolate
[16, 25]

wait_all(tasks, timeout) returns the results, in the order the tasks were given, not the order they finished.

wait_any(tasks, timeout) returns the Isolate that finished first, not its result — you still call join() on it. That is what lets you tell which one won.

map(fn, items, timeout) spawns one task per item and collects the results, which is wait_all with the spawning done for you.

All three raise IsolateTimeoutError if the timeout passes, and all three propagate a worker’s failure:

import isolate

def halve(n) {
  if n == 0 {
    raise ValueError('cannot halve zero')
  }

  return n / 2
}

echo isolate.map(halve, [2, 4, 6])

catch {
  isolate.map(halve, [2, 0, 6])
} as e {
  echo '${e.type}: ${e.message.lines()[0]}'
}

[1, 2, 3]
IsolateError: ValueError: cannot halve zero

The whole call fails on the first failing element. When individual failures are acceptable, spawn and join yourself with a catch around each join(), as the worked example below does.

Isolates Can Spawn Isolates

There is no restriction on nesting. A worker may spawn its own tasks and join them, and they run on the same pool:

Filename: work.zu

import isolate

def double(n) {
  return n * 2
}

def nested(n) {
  return isolate.spawn(double, n).join()
}

$ zuri run main.zu
6

This is worth knowing mostly as a warning, which the next section covers: nested tasks that block on each other are the fastest way to exhaust the pool.

The Pool

Isolates do not each get a thread of their own. They run on a fixed pool of OS threads, sized to the machine’s core count by default:

import isolate

echo isolate.cpu_count() > 0
echo isolate.pool_size() == isolate.cpu_count()

true
true

Sizing It

configure(threads) changes the size, and it only works before the pool exists — which is to say, before the first spawn. It reports whether it did anything:

import isolate

echo isolate.configure(7)
echo isolate.pool_size()

true
7

Call it after a spawn and it returns false and changes nothing. It does not raise, so a configure() buried below some initialisation that already spawned will silently do nothing — put it at the very top of the entry file.

The size is a ceiling, not a head count. A thread is started only when an isolate is waiting and every thread already started is busy, so sizing the pool generously for a burst costs nothing while the burst is not happening. started_count() says how many threads the pool has started so far:

import isolate

isolate.configure(8)

echo isolate.started_count()
echo isolate.spawn(@() => 21 * 2).join()
echo isolate.started_count()

0
42
1

Why the Size Matters More Than It Looks

A pool sized to your core count can deadlock, and the failure looks like a hang rather than an error.

The mechanism: a task that blocks — on join(), on recv(), on a socket read — occupies its thread while it waits. If every thread is occupied by a task waiting for work that has no free thread to run on, nothing can ever progress.

That happens most easily with three patterns:

• a server and a client that talk to each other in one process;
• nested spawns where the parent joins the child;
• a pipeline with more stages than threads.

Size the pool for the number of tasks that will be blocked at once, not for the number of cores. Threads that are blocked are not competing for CPU, so over-provisioning costs little; under-provisioning costs everything.

Watching It

import isolate

echo isolate.active_count() >= 0
echo isolate.queued_count() >= 0
echo isolate.is_shutdown()

true
true
false

active_count() is how many tasks are running; queued_count() is how many are waiting for a thread. A queued count that only grows is the signature of a starved pool.

shutdown(timeout) drains the pool and stops it. Most programs never call it; it is there for a long-lived process that wants to release its threads without exiting.

Memory While Waiting

A pool thread keeps its isolate’s heap from one task to the next, and the collector runs as a program allocates. A thread that waits allocates nothing, so a waiting thread collects on its own: once it has waited a second, for its next task or inside recv(), select(), join(), wait_any() or wait_all(), it collects its garbage and the memory that garbage held goes back to the system. The main thread does the same in those calls. A task that built and dropped a large structure leaves the process at its working size rather than its peak.

A wait of a second or less returns before that point, and a heap that has grown by less than 4 MB since its last such collection is left as it is, so a loop of short waits pays nothing for it.

The Errors

Three error types come out of this module, and they mean different things:

All three inherit from Error, so catch on its own catches every one and instance_of() sorts them.

The distinction matters because they call for different responses. A timeout usually means retry or give up. A cancellation means shut down quietly. An IsolateError carrying a worker’s failure means something in your own code went wrong, and the message names it.

A Worked Example

Fan out a computation, collect the results, and report a failure without losing the rest:

import isolate

def classify(n) {
  if n < 0 {
    raise ValueError('negative input: ${n}')
  }

  if n < 2 {
    return 'small'
  }

  var divisor = 2

  while divisor * divisor <= n {
    if n % divisor == 0 {
      return 'composite'
    }

    divisor++
  }

  return 'prime'
}

def classify_all(numbers) {
  var tasks = numbers.map(@(n) => [n, isolate.spawn(classify, n)])
  var results = {}

  for pair in tasks {
    catch {
      results[pair[0]] = pair[1].join()
    } as e {
      results[pair[0]] = 'failed'
    }
  }

  return results
}

echo classify_all([1, 7, 9, -3, 97])

{1: small, 7: prime, 9: composite, -3: failed, 97: prime}

Three things are doing the work there.

Every task is spawned before any is joined. Spawning in one pass and joining in another is what makes the work overlap; joining inside the first loop would run them one after another and buy nothing.

The number is carried alongside its task, because the results come back in whatever order the pool produces them and a bare list of results would lose which input each belonged to.

And the catch is around one join(), so the one bad input becomes one failed entry rather than ending the batch. Move it outside the loop and the first failure takes the other four with it.

Choosing a Shape

Fan out, collect results. isolate.map(), or scope() when a failure must stop the group.

A pipeline. Channels between stages, each stage an isolate, each channel bounded so backpressure propagates all the way back to the source.

An event fan-out. A broadcast, one subscriber per consumer.

A server. http.serve() builds the whole pattern for you: one isolate per worker, a bounded backlog, connections handed out as they arrive. Chapter 15 covers it.

Nothing at all. Concurrency costs a copy at every boundary and a great deal of care at every join. A single-threaded loop that finishes in time is the better program.

Networking

The net module is the socket layer: TCP, UDP, unix domain sockets, TLS, DTLS, address parsing and polling. The http module sits on top of it and gives you a client and a server that speak HTTP/1.1 and HTTP/2.

Every example in this chapter runs a server in an isolate and a client in the main program, which is how you test network code without two terminals. Chapter 11 is the background.

TCP

A TcpStream is both ends. bind() and accept() make it a listener; connect() makes it a client. accept() blocks until someone connects, unless the listener was put in non-blocking mode, in which case it answers nil when nobody is waiting.

Filename: server.zu

import net

def echo_server(port_channel) {
  var listener = net.TcpStream()
  listener.bind('127.0.0.1:0')

  port_channel.send(listener.local_address())

  var client = listener.accept()
  var received = client.read_as_string()

  client.write_all('echo: ' + received)
  client.close()
  listener.close()
}

Filename: main.zu

import net
import isolate
import .server

var channel = isolate.channel(1)
var task = isolate.spawn(server.echo_server, channel)
var address = channel.recv()

var client = net.TcpStream()
client.connect(address)

client.write_all('hello')
client.shutdown(net.Shutdown.WRITE)

echo client.read_as_string()

client.close()
task.join()

echo: hello