Reference

The Standard Library

The library is built into qoqi. There is nothing to install and no project file is needed: any program can import its modules.

import std.dict;

fn main() -> Int {
    let counts = dict.empty<Int>();
    for word in "to be or not to be".words() {
        counts.set(word, (counts.get(word) ?? 0) + 1);
    }
    println(counts.keys(), counts.values());      // ["to", "be", "or", "not"] [2, 2, 1, 1]
    return 0;
}

Whole programs built on it: a report on a web server's log, a sales report from a CSV file, invoices from packages, and the flows of a shop and of subscriptions.

The modules are imported and used like any other (modules.md): import std.path; then path.dir(file), or import std.path.{dir}; then dir(file). The methods of arrays, texts and numbers need no import (see below).

print, println, toString, push and panic are not part of the library: they are builtins, available without an import.

Conventions

Methods, not functions. What the library does to an array, a text or a number is a method of it: items.filter(wanted), name.trim(), x.sqrt(). The tables of std.arrays and std.strings below list them as name(receiver, arguments), and that of std.math as the methods they are: the receiver is what stands before the dot, so take(items, count) is called as items.take(count). Nothing is imported for a method: these three modules are part of any program that calls one of their methods. An import is only for the few functions that have nothing to stand on: arrays.range, arrays.fill, arrays.flatten, arrays.unzip, strings.fromCode, and the constants math.pi and math.e. A method is handed to another function as any function is, by its name: texts.map(String.parseInt) calls parseInt on each text, and keys.map(users.get) calls get of that dictionary.

Nothing instead of failure. A function that may have no answer returns an optional, and null means "none": the position of something not found, the first item of an empty array, a text that is not a number. Where there is a reason worth knowing, as for a file that cannot be read, it returns a Result with the reason in it. The type checker then makes sure the program deals with it:

let n = line.parseInt();      // Int?
if n != null { total += n; }         // an Int in here
let port = text.parseInt() ?? 8080;

A failure is for a mistake in the program. Asking for characters 2 to 9 of a three-letter text, the square root of a negative number, or a random number below zero stops the program, like an index out of bounds does. The message names the function as the program called it and the line that called it:

[ERROR] R0007: std.strings.substring: range 0..5 is outside a text of 3 characters
  --> main.qi:8:19 in function 'shorten'
     |
 8 |     return name.substring(0, 5) + "...";
     |                   ^^^^^^^^^^
  called from main.qi:13:13 in function 'main'

That holds however deep in the library the failure happened: the lines of the library are left out, and what is named is the function the program called, std.csv.parseWith for a separator it cannot use, not the private one that found out.

Arrays are not changed by the functions of std.arrays; they return new ones. The exceptions say so (pop, removeAt, insertAt, clear, swap, random.shuffle). A List is the reverse: its methods change it, unless they return a new list.

Ranges are given as from, to: from is included, to is not. Positions count from 0. In texts they count characters, not bytes, like text[i] and text.len().

std.math

An Int is taken for a Float where one is expected, and the two work together as Floats (1 + 2.5 is 3.5), so toFloat is rarely needed: it is there for when the conversion should be seen. Going to an Int is never implicit, and there are four ways to lose the fraction.

What there is to do with a number is a method of it: n.abs(), x.sqrt(), price.round(). Only the constants math.pi and math.e need import std.math;.

The four fail if the number does not fit in an Int.

Whole numbers

Numbers with a fraction

// The length of the diagonal of a 3 by 4 rectangle
let a = 3;
let b = 4;
let diagonal = (a * a + b * b).sqrt();    // 5.0

std.strings

Taking apart

Putting together

Building a long text piece by piece with += copies everything so far at each step. Collect the pieces in an array and join them once.

Searching

Changing

Asking

What a lexer asks of the character it is at: if c.isLetters() || c == "_" { ... }.

Numbers and characters

Going the other way, any value becomes text with the builtin toString.

let line = "name = Ada Lovelace";
let at = line.indexOf("=");
if at != null {
    let key = line.first(at).trim();          // "name"
    let value = line.from(at + 1).trim();     // "Ada Lovelace"
}

std.arrays

Generic functions on plain arrays. Type arguments are inferred: [1, 2, 3].reversed(). Where there is nothing to infer from, write them: [].first().

Making

Changing the array itself

With push, these make an array a stack (push, pop) or a queue (push, removeAt(items, 0)). They change the array they are given, so everything that holds it sees the change, and they make no new array: one made shorter keeps the room it had, to grow into again.

let stack = [1, 2];
stack.push(3);
let top = stack.pop();          // 3, an Int?; stack is [1, 2]
stack.insertAt(0, 0);         // [0, 1, 2]
let first = stack.removeAt(0);

while !stack.isEmpty() {        // until nothing is left
    let item = stack.pop();
}

Two things to know:

• null from an array of optionals. In a [Int?] an item can itself be null, and pop then gives null for that item as it does for an empty array. Ask isEmpty (or len) before, as the loop above does, instead of waiting for null.
• Not inside for ... in over the same array. That loop counts the items once, before it starts; an array made shorter under it is read past its end, which stops the program (index out of bounds). Use while with an index that only moves on when nothing was removed, go down from the end, or loop over items.copy():

let i = 0;
while i < tasks.len() {
    if tasks[i].done { tasks.removeAt(i); } else { i++; }
}

One item

Asking

Every item

Order

Numbers and texts

These are methods of [Int], and all but sortedTexts of [Float] as well, giving a Float: prices.sum(), areas.largest(). [Int], [Float] and [String] also take sorted() without a function, smallest first or alphabetical, and with one like any array: scores.sorted((a, b) -> a > b) for the largest first.

Pieces and groups

Equal, for indexOf and contains, means what == means: numbers, texts and booleans are equal when they have the same value, arrays and structs when what they hold is, and a type that implements Equal when its equals says so.

let people = [Person { name: "Ada", age: 36 }, Person { name: "Linus", age: 21 }];

let adults = people.filter(p -> p.age >= 18);
let names = adults.map(p -> p.name);
let oldestFirst = people.sorted((a, b) -> a.age > b.age);
let totalAge = people.fold(0, (sum, p) -> sum + p.age);

std.list

List<T> is an array in a struct, with the functions of std.arrays as methods. Calls read left to right and can be chained.

import std.list;

let names = list.of(["ada", "linus"]);
names.add("grace");
let long = names.filter(n -> n.len() > 3).sorted((a, b) -> a < b);
println(long);                          // ["grace", "linus"]: a list prints as an array does

for name in names { println(name); }    // a list goes where an array does
names[0] = "Ada";                       // as with an array, a position that is not there stops the program
println(names[0]);

Methods that change the list

They change the array the list holds, as the functions of std.arrays that change an array do. As there, do not take items out of a list inside a for ... in over that same list: the loop counted them before it started. Loop over names.toArray(), or use while with names.len().

Methods that read

Methods that return a new list

map<U>(convert), filter(wanted), sorted(before), sortedBy(rank), reversed(), slice(from, to), take(count), drop(count), flatMap<U>(convert), uniqueBy(name), concat(other: List<T>), copy(). They do what the methods of arrays of the same names do, and return a List; so do those that give several: chunks(size) -> List<List<T>>, partition(wanted) -> (List<T>, List<T>), groupBy(name) -> Dict<List<T>>.

map and fold have a type parameter of their own, for what they produce. It is worked out from the function passed, or can be written: names.map<Int>(n -> n.len()).

A list prints as an array does, [1, 2, 3], alone, inside another value and in "${...}".

std.dict

Dict<V> (a dictionary) finds values by a text key: finding a key takes about the same time however many there are.

Its keys and values are two arrays, in the order the keys were set. Up to eight keys are simply looked through, so a small dictionary is three objects and costs next to nothing to make; a program can have one per record, per scope, per request. Past eight the machine keeps an index of where each key is.

let ages = {"ada": 36, "linus": 21};     // a literal, or:
let more = dict.empty<Int>();
more.set("grace", 85);

let age = ages.get("ada");          // Int?
if age != null { println(age + 1); }
println(ages.get("nobody") ?? 0);

A dictionary takes brackets and loops: ages["ada"] is what get gives, a value or null; ages["ada"] = 36; is set; and for name in ages { ... } goes through the keys. Counting reads counts[word] = (counts[word] ?? 0) + 1;. Two dictionaries are == when they have the same keys with equal values, and one prints as its literal: {"ada": 36}.

Keys are compared exactly: "a" and "A" are two keys, and "" is a key.

The values can be of any type, including arrays, structs and other dictionaries (dict.empty<Dict<Int>>()). For keys that are not texts, there is Map.

// Group words by their first letter
let groups = dict.empty<[String]>();
for word in words {
    groups.getOrSet(word.first(1), () -> []).push(word);
}

std.map

Map<K, V> finds values by a key of any type: a number, a value of an enum, a struct, a tuple. Two keys are the same key when they are written the same, as toString writes them, and are ==: so 1 and "1" are two keys of a Map<Int | String, V>. It takes brackets and loops as a Dict does, and prints as its literal: {(1, 1): "ada"}.

let seats = {(1, 1): "ada", (1, 2): "alan"};   // keys that are not texts: a Map
seats[(2, 1)] = "grace";
let counts = map.empty<Fruit, Int>();
for fruit in basket { counts.update(fruit, 0, n -> n + 1); }
let scores: Map<Player, Int> = {};

A Map has no sortedKeys, which is a Dict's: keys of any type have no alphabetical order. keys().sortedBy(...) puts them in one.

A key is found by how it is written, then by == among the keys written the same way: finding one takes about the same time however many there are.

std.option

Functions on optionals: T?, a value or null. They carry "or nothing" through a series of steps, so that each step does not need its own null test.

import std.option;

// Without: one test per step
let line = io.readLine();
if line != null {
    let n = line.parseInt();
    if n != null {
        println(n * 2);
    }
}

// With: each step runs only if the one before gave a value
let doubled = option.map(option.then(io.readLine(), text -> text.parseInt()), n -> n * 2);

All of them but values are also methods of every optional, with no import: users.get(key).map(u -> u.name), io.env("HOME").expect("HOME is not set"). They are written impl<T> T? { ... }, which a program can use for methods of its own.

map is for a step that always has an answer (fn(Int) -> String), then for one that may not (fn(String) -> Int?). Using map with the second kind would give an optional of an optional; then keeps it flat.

What comes out is an ordinary optional: ?? gives it a fallback, and a test against null makes it a plain value inside the test.

// The name of a user's manager, through two lookups and a field that may be null
let manager = option.then(users.get(key), u -> u.manager);
let found = option.then(manager, users.get);
println(option.mapOr(found, "no manager", u -> u.name));

Type arguments are worked out from the values and functions passed. A function is passed by its name, toString, and so is a method: of a type, String.parseInt or String.trim, which takes the text as its argument, or of a value, users.get, which looks in that dictionary. option.then(io.readLine(), String.parseInt) reads as the steps it takes.

There is no separate Option type with Some and None: T? is that type, and the type checker already refuses to use one as a plain value. These functions add the chaining.

std.result

For failures: returning one with its reason, and surviving one that would stop the program. The whole subject is in errors.md; this is the reference.

Result<T, E>: enum Result<T, E> { Ok(T), Err(E) }, the value a function produced or the reason there is none. A Result<Void, E> is for an action that has nothing to give back: Ok() is its success. The name Result needs no import: every file has it, unless it declares a Result of its own. The rest of the module (attempt, Failure, Kind) is imported as usual.

or and orElse are named as those of an optional are: or takes the fallback itself, orElse a function that makes it.

Failures that stop the program

The builtin panic(values...), which stops the program, needs no import.

std.io

Output goes through the builtins print and println. Reading and writing a file can fail for reasons outside the program; those functions return a Result and never stop the program.

An io.Error says what kind of failure it was, for the program to act on, and the rest for telling a person:

describe() gives one sentence (cannot read notes.txt: no such file or directory), trace() adds where. An Error is Show: println(error) and "${error}" write the sentence, and so does expect when it stops.

Input is what the user types, or what is piped in: qoqi run sum.qi < numbers.txt.

import std.io;
import std.io.{ErrorKind};
import std.strings;

fn main() -> Int {
    match io.readFile("notes.txt") {
        case Ok(content): {
            for i, line in content.lines() {
                println(toString(i + 1).padLeft(4), line);
            }
        }
        case Err(error): {
            match error.kind {
                case ErrorKind.NotFound: { println("no notes yet"); }
                default: { io.printError(error.describe() + "\n"); return 1; }
            }
        }
    }
    return 0;
}

When the reason does not matter: io.readFile(path).or("").

Paths are relative to the directory the program is run from, not to the program's file. For a file that comes with the program, start from os.program().

std.time

A Stopwatch has microseconds(), milliseconds() and restart().

let watch = time.stopwatch();
work();
println("took", watch.milliseconds(), "ms");

Lengths of time

A length of time is a Duration, written as what it is: a number and its unit. A number alone is not one, so that seconds are never taken for milliseconds: time.after(500) does not compile, and says to write 500.milliseconds().

wait time.after(2.days());
let renewal = 30.days().fromNow();
wait time.until(renewal);
println(90.minutes(), 1.5.hours() > 80.minutes());      // 1 h 30 min true

A moment and a length are not added with +: + adds two values of one type. 30.days().fromNow() and 3.days().after(started) say which is which.

In a flow's fields, from the command line or the pages, a Duration is a text with its unit: "90s", "1h30m", "2d", "250ms".

Dates

A moment is a number, which is what now gives. A Date is that moment told the way people do, in some time zone.

A Date has the fields year, month (1 for January), day, hour, minute, second, millisecond, weekday (an enum, Weekday.Monday to Weekday.Sunday, with name() and isWeekend()), dayOfYear and offset (minutes ahead of UTC).

In a pattern for format:

let today = time.today();
println(today.format("dddd D MMMM YYYY"));       // Tuesday 13 October 2026
println(today.plusDays(30).iso(), today.daysUntil(time.date(2027, 1, 1)));

std.random

Without seed the numbers differ on every run. With it they repeat, which is what a test or a replay needs.

These numbers are for games and simulations. They are not fit for passwords or keys: uuid and token are, coming from the secure generator of the system.

std.path

Paths taken apart and put together. Nothing here touches the disk. The separator is that of the system the program runs on.

std.fs

Folders and the files in them. Reading and writing the content of a file is in std.io. Like there, what can fail returns a Result whose reason is an io.Error.

An Entry has name, path, kind (Kind.File or Kind.Dir), size in bytes (0 for a folder), modified (a moment, as time.now), and isFile(), isDir().

match fs.list("notes") {
    case Ok(entries): {
        for entry in entries { println(entry.name, format.bytes(entry.size)); }
    }
    case Err(error): { println(error.describe()); }     // cannot list notes: no such file or directory
}

std.os

An Output has status, out, err, and succeeded(), lines(). A program that ran and reports a failure is not an error: look at output.status. The error is for a program that could not be started.

let status = os.command("git", ["status", "--short"])
    .inDir("checkout")
    .env("GIT_TERMINAL_PROMPT", "0")       // added to the environment it inherits
    .run()?;

Arguments on the command line. What follows the file is for the program, except the options of qoqi itself (--heap-mb, --max-depth). After a lone -- everything is for the program:

qoqi run todo.qi add "Buy milk" --due=2026-10-20
qoqi run --heap-mb=64 report.qi -- --heap-mb=this-one-is-mine
qoqi run . list                 # a project: name its folder, then the arguments

Being asked to stop. os.signals() -> Channel<String> gives the signals the program is sent, as they come: "interrupt" for Ctrl-C, "terminate" for kill or a service manager stopping it. Once a program listens, they no longer stop it: it stops its own way, and a second Ctrl-C stops it at once. Waiting for a signal does not keep a program alive whose other tasks are done.

let stop = os.signals();
task.run(fn() {
    let name = wait stop.receive();
    log.info("stopping", {"signal": name});
    server.close();                       // what is being answered is answered first
});

std.log

import std.log;

log.info("list saved", {"items": 12, "file": path});
log.warn("slow answer", {"ms": 950});
log.error("cannot reach the database", {"reason": error.describe()});

2026-10-16T09:41:07.120Z INFO list saved items=12 file=todo.json

The messages go to the error output, so that what the program prints stays its result. A value with a space, a quote or an = in it is written in quotes, so the line reads back.

A Logger has debug, info, warn, error, with and write(level, message, fields); the level, the form and where the lines go are those of the module, shared by every logger.

std.format

Numbers and tables written for people.

Every function rounds the same way, to the nearest with a half going away from zero, as Float.round() does: fixed(2.5, 0) is 3, fixed(-2.5, 0) is -3, money(0.125) is 0.13. The number is rounded as it is written, so fixed(1.005, 2) is 1.01, though the Float nearest 1.005 is a little below it. A number that rounds to zero has no minus sign. The rounding comes before the unit is chosen: duration(59999) is 1m 00s, not 60.0s, and bytes(1048575) is 1.0 MB, not 1024.0 KB.

print(format.table(["name", "age"], [["ada", "36"], ["grace", "45"]]));

name   age
-----  ---
ada     36
grace   45

std.json

A document is a value of an enum, so a match takes it apart and the compiler checks every kind is handled:

pub enum Json { Null, Bool(Bool), Number(Float), String(String), Array([Json]), Object(Dict<Json>) }

let document = json.parse(text).expect("a document");
let name = document.get("name")?.text() ?? "nobody";
let firstTag = document.find("user.tags.0")?.text();

let reply = json.object().text("name", name).int("visits", 3).set("tags", json.texts(tags)).done();
println(reply.stringify());         // {"name":"ada","visits":3,"tags":["a","b"]}

The keys of an object stay in the order they were written. Numbers are Floats; int() gives one that is whole and that an Int holds, up to 140737488355327 either side of 0, and null for 1e15.

std.regex

Regular expressions, in the syntax of RE2: no look-behind and no back-references, and a search that always takes time proportional to the text. \w, \d and \b know the letters and digits of English only.

A Match has text, start, end (positions in characters), groups (what each group took, the first at 0), and group(n), which counts as $n does in a replacement: group(0) is the whole match, group(1) the first group; named(name) is for a group written (?P<name>...).

In a text of a program a backslash is written twice, and ${ would start a value to insert: write "\\d+" and "\${name}". In a replacement a name runs on as far as letters, digits and _ go, so $1_x is the group named 1_x, which there is none of: the first group followed by _x is written "\${1}_x".

let date = regex.must("(\\d{4})-(\\d{2})-(\\d{2})");
date.replace("on 2026-10-13", "$3/$2/$1")           // on 13/10/2026

std.csv

A ParseError has message, line and column, the line being the one the row starts on in the text, whatever values over several lines or blank lines come before it, and describe(), which is also how it prints. A byte-order mark in front of the text, which some programs write, is passed over.

std.set

Values without repeats, of any type. A set is the keys of a Map, and tells its items apart as a Map tells its keys: two items are the same when they are written the same and are ==. One made with set.by tells them apart by the text its function gives alone. It prints as its items in braces: {"a", "b"}.

std.semver

Versions numbered the semantic way, major.minor.patch, and the constraints written on them in the syntax of Composer and npm. The package manager chooses versions with it.

import std.semver;

let installed = semver.parse("v1.4.2").expect("a version");
let wanted = semver.constraint("^1.2 || ^2.0").expect("a constraint");

wanted.allows(installed)                       // true
semver.highest(available, wanted)              // the newest that fits, or null
installed < semver.parse("1.10.0").expect("")  // true: by the numbers, not the letters

A pre-release is accepted only by a range that names a pre-release of the same version, so that ^1.0 never takes 2.0.0-beta.1, nor 1.3.0-rc.1.

A number is written without zeros in front, as semver.org has it: 01.2.3 and 1.0.0-alpha.01 are not versions, 0.1.0 and 1.0.0-0a are. A ParseError says why, with describe(), which is also how it prints.

std.encoding and std.hash

These hashes are made to be fast: they are for telling contents apart and for signing, not for storing passwords.

std.url

import std.url;

let page = url.parse("https://shop.example:8443/search?q=red+shoes&page=2#top").expect("an address");
page.host                       // "shop.example"
page.port                       // 8443, an Int?
page.param("q")                 // "red shoes": decoded
page.withParam("page", "3")     // a new Url; println writes it out encoded
page.resolve("../help")         // a link found on that page, made whole: Result<Url, ParseError>

A Url is a struct with every part: scheme, user: String?, host, port: Int?, path (decoded), query: [(String, String)] in the order written, fragment: String?. One can be written as a literal, url.Url { scheme: "https", host: "api.example", path: "/v1/users" }, and the parts that need it are encoded when it is written out.

std.http

Asking a server.

match http.get("https://example.com/api/users/1") {
    case Ok(response): { println(response.status, response.body); }
    case Err(error): { println(error.describe()); }
}

let created = http.to(Method.Post, url).header("Authorization", token).json(document).timeout(5000).send();

A server that answers "not found" has answered: that is a Response with status 404. An Error is for when there was no answer at all, and its kind says why: Timeout, Refused, UnknownHost, BadUrl, Other, and for a server of your own that cannot listen, InUse when the port is taken. error.describe() says it in a sentence, which is also how an Error prints: no answer from https://example.com/x: ..., or for a server cannot listen on port 8080: the port is taken.

Being one. A handler is a function from a Request to a Response. A Router chooses one from the method and the path:

let app = http.router();
app.get("/hello/:name", fn(request: Request) -> Response {
    return http.text("hello, ${request.params.get("name") ?? "you"}");
});
app.post("/notes", createNote);
http.serve(8080, app.handler()).expect("a free port");

A path nobody takes is answered with 404, one taken only for other methods with 405. A HEAD request that no route takes for HEAD is answered by the GET route of its path, with that route's status and headers and no body. A handler that stops, by a panic or any other failure, does not stop the server: its request is answered with 500 and the failure goes to the error output.

request.query holds one value for a name: in ?a=1&a=2, the last, "2". For all of them, read the address with std.url: url.queryOf(text) keeps every pair in order, and u.params("a") gives ["1", "2"].

Stopping a server. serve answers for as long as the program runs. A server that is to stop is listened on, answered with handleAll in a task, and closed:

let server = http.listen(8080).expect("a free port");
let serving = task.run(fn() { server.handleAll(app.handler()); });
// ... until it is time to stop
server.close();     // the requests in progress are answered first
wait serving;       // handleAll has returned

While it closes, a request that comes in, or one still unanswered after ten seconds, is answered 503, the server is closing. Once close returns, the port is free.

With serve and handleAll a handler that waits, for another server or for the clock, does not keep the other requests waiting; handlers still run one at a time between their waits (tasks.md). handle answers one request after the other. The server listens on this machine only (127.0.0.1).

std.sql

import std.sql;
import std.sql.{Value};

let db = sql.open("shop.db").expect("the database");
defer db.close();

db.exec("CREATE TABLE IF NOT EXISTS parcels (id TEXT PRIMARY KEY, city TEXT, grams INTEGER)")?;
db.exec("INSERT INTO parcels VALUES (?, ?, ?)", [Value.Text("p-1"), Value.Text("Lyon"), Value.Int(1200)])?;

for row in db.query("SELECT id, grams FROM parcels WHERE city = ?", [Value.Text("Lyon")])? {
    println(row.text("id"), row.int("grams"));        // p-1 1200
}

A database is a file of SQLite (a path, or :memory:), or a server, by its address: postgres://user:secret@host:5432/shop, mysql://user:secret@host:3306/shop, what follows ? passed to the server (?sslmode=require, ?tls=true). A program is the same on all three: a parameter is written ? everywhere, and Postgres is given $1, $2. Waiting for the database lets the other tasks go on.

A Value is Null, Int(Int), Float(Float), Text(String) or Bool(Bool), given as parameters and found in rows. A decimal comes as an Int when it is whole (SUM, COUNT on Postgres and MySQL), a Float otherwise; a number beyond an Int as its digits, a Text; a moment as a text of ISO 8601; bytes that are not text as \x and their hex.

In a transaction, a statement that fails leaves the transaction as it was, on every database (Postgres is given a savepoint around each). A table made, changed or dropped in a transaction is so in it on SQLite and Postgres; MySQL, which would commit the transaction for it, has it done beside, at once. Error has a kind: Unreachable, Query (the words, a table or a column), Constraint (a key taken, a NULL, a reference), Conflict, Closed or Other, and a message. Conflict is the database ending a transaction for another that ran at the same time: nothing more runs in it, its commit fails, and the work is to be done again in a new one.

In a flow, a database is the world: it is reached from a step. A step that writes only to the database the flows are kept in asks for it with flow.store(), and what it writes is kept with what it returns, in one transaction (flow.md).

A depot's parcels, run on each of the three: test/e2e/cases/sql_depot.qi.

std.ops

The traits that give a struct or an enum the syntax of the builtin types, and what a generic function asks of its type parameters. They are explained, with how to implement them, in traits.md.

Int, Float, String and Bool implement Equal and Show; all but Bool implement Ordered.

Range

What 0..10 is when it is kept instead of looped over: let teens = 13..20;. A struct, made by writing a range (no import is needed for that; import std.ops.{Range}; to name the type). It knows its numbers without holding them, and a loop over one counts.

It is written as its range: 0..10, (0..=10).step(5).

For any type that implements the trait named:

import std.ops;
import std.ops.{Ordered};

struct Version { major: Int; minor: Int; }
impl Ordered for Version {
    fn compare(other: Version) -> Int {
        if self.major != other.major { return self.major - other.major; }
        return self.minor - other.minor;
    }
}

let newest = ops.largest(versions);
if newest != null && newest > installed { ... }

Templates

A Template is a text written with ${...} in it, kept in its pieces: parts, what was written around the values (one more than there are values), and values, what each ${...} gave, as text. text() puts them together. A function whose parameter is a Template gets those, where one taking a String would get the text:

fn shout(t: Template) -> String { ... }
shout("hello ${name}, ${count} times");   // parts ["hello ", ", ", " times"], values [name, count]

The function can then tell what the program wrote from what was put in it, which is how a query or a page can escape what is put in them.

A text written in the program becomes a Template wherever that is the type it must have: an argument, a variable or a field declared Template, a return from a function that returns one, an item of a [Template]. So a command can be kept, built by a function or carried in a struct:

struct Job { name: String; command: Template; }

fn deploy(target: String) -> Template { return "make deploy ENV=${target}"; }

let jobs = [Job { name: "lint", command: "composer pint-test" }, Job { name: "deploy", command: deploy(env) }];
for job in jobs { sh.run(job.command); }

Like Result, the name Template needs no import. A String made elsewhere is refused where a Template is expected, since nothing would then say which of it was written and which was put in. Everywhere else, "${...}" is a String as always, and t.text() turns a Template into one.

std.task

Functions running at the same time, and channels between them. All of it, with how a program of several tasks ends, is in tasks.md.

let pages = wait task.map(urls, url -> http.get(url));     // all asked at once

let lines = task.channel<String>(16);
task.run(fn() {
    for name in files { wait lines.send(io.readFile(name).or("")); }
    lines.close();
});
lines.each(fn(text: String) { println(text.len()); });

One task runs at a time, until it waits: for a task, a channel, the clock, the network, a line of input, another program. What a task waits for in the program is written wait: wait job, wait lines.receive(), wait time.after(500.milliseconds()), and wait match { ... } for the first of several. Tasks share everything and need no locks, as long as a change does not have a wait in its middle.

A task that stops does not stop the program: whoever waits for it gets the failure. If nobody ever does, the failure ends the program once the other tasks are done. Tasks that all wait for each other end it with error R0009.

std.compiler

The front of the compiler, asked about a program instead of told to run it. Every function takes the path of a file and its text: the text is what is looked at, the path says where its modules are and how places are named.

let source = io.readFile("main.qi").expect("a file");
for problem in compiler.check("main.qi", source) {
    println(problem.describe());        // main.qi:4:9: error E1001: undefined identifier 'totl'
}

Lines and columns count from 1, columns in characters. describe answers null for a program with errors that keep it from being understood; complete then works from the file without the line being typed.

It is what the language server is written with, and serves as well for a linter or a documentation generator: internal/lsp/server.qi is the longest example.

std.test

import std.test;

fn main() -> Int {
    return test.suite("prices")
        .test("a total adds up", fn() { test.equal(total([1, 2, 3]), 6); })
        .test("an empty basket costs nothing", fn() { test.equal(total([]), 0); })
        .run().exitCode();
}

prices
  ok    a total adds up
  FAIL  an empty basket costs nothing
        expected 0, got 1
        at prices.qi:6
1 passed, 1 failed

A check that does not hold stops its test; the suite goes on with the next and reports at the end. So does any other failure in a test: an index out of bounds is a failed test, not the end of the run.

Test files: qoqi test

A suite needs a main that builds it. qoqi test writes that main for you: put the tests in a file whose name ends in _test.qi, one function each, named test....

// prices_test.qi
import std.test;
import shop.prices;

fn testATotalAddsUp() {
    test.equal(prices.total([1, 2, 3]), 6);
}

fn testAnEmptyBasketCostsNothing() {
    test.equal(prices.total([]), 0);
}

$ qoqi test
shop/prices_test.qi
  ok    a total adds up
  ok    an empty basket costs nothing
2 passed

A test is a function at the top of a test file whose name starts with test, that takes nothing and gives nothing back. It is reported by the words of its name: testReadsJSONText is "reads JSON text". The other functions of the file are helpers, and so is a testData() that returns something.

Each test file is a program of its own, with the modules of its project in reach, and no main. Without a project file, module paths start at the folder qoqi test runs in: from the folder that holds shop, shop/prices_test.qi imports shop.prices. The tests of a file run in the order they are written; one that fails does not stop the next. The status of qoqi test is 0 when every test passed, and 1 when one failed or a file could not be run: it does not compile, or a test ended the program with os.exit.

The example flows have test files: qoqi test examples/flows.

std.layout

Text laid out to fit a width. What is to be written is described once, as a document: pieces of text, and the places where a line may end. Writing it out decides which of those places are used.

import std.layout;
import std.layout.{Doc};

fn list(items: [Doc]) -> Doc {
    return layout.group(layout.concat([
        layout.text("["),
        layout.indent(layout.concat([Doc.Soft, layout.join(items, layout.concat([layout.text(","), Doc.Line]))])),
        Doc.Soft,
        layout.text("]"),
    ]));
}

print(layout.render(list(words), 80, 4));     // [one, two, three], or an item to a line

A group is written on one line if it fits, and otherwise every line end directly in it is taken: all or none. Groups inside it decide for themselves.

It is what the formatter is written with, and serves as well for printing JSON, a query, or a program in another language.

std.formatter

The formatter of Qoqi as a function: the one qoqi fmt and the language server run.

import std.formatter;

match formatter.format(source) {
    case Ok(tidy): { io.writeFile("main.qi", tidy); }
    case Err(problem): { println(problem.describe()); }      // 12:5: expected ';', found 'let'
}

What it decides is in formatting.md. It needs a text whose brackets close and whose statements end; names and types it does not look at.

How It Is Built

The library has two halves.

Qoqi source. Each module is a .qi file in internal/stdlib/lib/, compiled into the qoqi binary. Most of the library is written here, in the language itself: gcd, sorted, all of List and Dict. These are ordinary modules; a program importing one gets its functions compiled along with its own.

Native functions. What cannot be written in Qoqi, because it needs the machine (files, the clock) or would be too slow (searching a text), is declared in the module without a body:

pub extern fn sqrt(x: Float) -> Float;

and provided by a Go function in the virtual machine (internal/vm/native_*.go) registered under the function's full name, std.math.sqrt. See extern fn.

The package std is found like any package; the only difference is that its folder is inside the binary. In messages its files appear as <std>/strings.qi. A project that lists a package named std in its qoqi.json gets that one instead, whole.

Natives hand back simple things. A native function cannot make a struct or a value of an enum: those are made by compiled code, which knows what each must hold. So a native returns a number, a text, or arrays of them, and the Qoqi half of the module builds the types the program sees. json.parse is the clearest case: Go checks the text and lists its tokens, and thirty lines of Qoqi build the tree of Json values from them. An operation that fails gives null and keeps the reason, which the Qoqi half fetches to build its error value.

The web server is split the same way, for another reason: only one task of a program runs at a time. Go accepts connections and reads requests, each in its own goroutine, and queues them; the program takes them one at a time, works out each answer in Qoqi, in a task of its own if it wants several in progress, and hands it back under the number of its request.

Tasks are mostly Qoqi as well. The machine provides tasks by number and three things to do with them: suspend the one that asks, resume another, wait for one to end. Task<T> and Channel<T> are written on those, which is how they come to be typed and collected like any other struct (tasks.md).

A folder called std among a program's own modules is not reachable as std.something: the name belongs to the library.