A tour of Xo on Xo Language

Basics

Mon, 01 Jan 0001 00:00:00 +0000

basics/main.xo

const GREETING = "hello"

fn greet(name: Str) -> Str {
 "${GREETING}, ${name}"
}

fn sign(n: Int) -> Str {
 if n < 0 { "negative" } else if n == 0 { "zero" } else { "positive" }
}

fn main(os: Os) {
 let who = "Ada"
 var count = 0
 for i in 0..3 {
 count += i
 }
 os.stdio.println(greet(who))
 os.stdio.println("count = ${count}, sign = ${sign(count - 5)}")
}

Output:

Structs, enums, and newtypes

Mon, 01 Jan 0001 00:00:00 +0000

types/main.xo

struct User {
 id: Int
 name: Str
 email: Str?
} derive Display

enum Shape {
 Circle(radius: Float)
 Rect(w: Float, h: Float)
 Point
}

fn area(s: Shape) -> Float {
 match s {
 Circle(radius) => 3.14159 * radius * radius
 Rect(w, h) => w * h
 Point => 0.0
 }
}

type UserId = Int
type Email struct(Str)

fn domain(e: Email) -> Str {
 e.0.split("@").last() ?? ""
}

fn main(os: Os) {
 let ada = User{id: 1, name: "Ada", email: None}
 let renamed = ada with {name: "Ada L."}
 os.stdio.println("${ada}")
 os.stdio.println("${renamed.name}")
 let id: UserId = 7
 os.stdio.println("user ${id}, area ${area(Shape.Rect(w: 2.0, h: 3.0))}")
 os.stdio.println(domain(Email("ada@example.com")))
}

Output:

Lists, maps, and sets

Mon, 01 Jan 0001 00:00:00 +0000

collections/main.xo

fn show(xs: List[Int]) -> Str {
 xs.map(fn(x) { "${x}" }).join(" ")
}

fn main(os: Os) {
 var xs = [3, 1, 2]
 xs.push(5)
 let doubled = xs.map(fn(x) { x * 2 })
 let small = xs.filter(fn(x) { x < 3 })
 let total = xs.fold(0, fn(acc, x) { acc + x })
 os.stdio.println("sorted: ${show(xs.sort())}")
 os.stdio.println("doubled: ${show(doubled)}, small: ${show(small)}, total: ${total}")

 var ages: Map[Str, Int] = {"ada": 36}
 ages.put("grace", 85)
 ages["linus"] = 28
 let age = ages.get("ada") ?? 0
 os.stdio.println("ada is ${age}, ${ages.len()} people")
 for (name, a) in ages {
 os.stdio.println("${name}: ${a}")
 }

 var seen = ["x"].to_set()
 seen.add("x")
 seen.add("y")
 os.stdio.println("${seen.len()} unique")
}

Output:

No nil: optionals

Mon, 01 Jan 0001 00:00:00 +0000

There is no nil in Xo. A value that may be missing has type T? (an Option[T]): either Some(v) or None, and the compiler makes you look before you use it.

optionals/main.xo

struct User { name: Str, email: Str? }

fn contact(u: User) -> Str {
 if let Some(e) = u.email { "mail ${e}" } else { "no email for ${u.name}" }
}

fn port(s: Str) -> Int? {
 let n = Int.parse(s.trim())?
 if n > 0 && n < 65536 { n } else { None }
}

fn main(os: Os) {
 let a = User{name: "Ada", email: Some("ada@example.com")}
 let b = User{name: "Bob", email: None}
 os.stdio.println(contact(a))
 os.stdio.println(contact(b))
 os.stdio.println(b.email ?? "unknown")
 for s in [" 8080 ", "http", "70000"] {
 os.stdio.println("port(\"${s}\") = ${port(s) ?? -1}")
 }
}

Output:

Errors you have to handle

Mon, 01 Jan 0001 00:00:00 +0000

A function that can fail says so after !, and its caller gets a Result. Errors are ordinary values, usually an enum.

errors/main.xo

enum ConfigErr {
 NotANumber(s: Str)
 OutOfRange(n: Int)
}

fn (e: ConfigErr) display() -> Str {
 match e {
 NotANumber(s) => "not a number: ${s}"
 OutOfRange(n) => "out of range: ${n}"
 }
}

fn parse_port(s: Str) -> Int ! ConfigErr {
 let n = Int.parse(s).or_err(ConfigErr.NotANumber(s))?
 if n < 1 || n > 65535 {
 return Err(ConfigErr.OutOfRange(n))
 }
 n
}

enum StartErr {
 Config(from ConfigErr)
}

fn start(port: Str) -> Str ! StartErr {
 let p = parse_port(port)?
 "listening on ${p}"
}

fn main(os: Os) {
 for input in ["8080", "abc", "99999"] {
 match start(input) {
 Ok(msg) => os.stdio.println(msg)
 Err(Config(e)) => os.stdio.println("error: ${e.display()}")
 }
 }
 let fallback = parse_port("x").ignore_err("the default port is fine") ?? 8080
 os.stdio.println("fallback ${fallback}")
}

Output:

Pattern matching

Mon, 01 Jan 0001 00:00:00 +0000

matching/main.xo

fn status_text(code: Int) -> Str {
 match code {
 200..=299 => "ok"
 429 | 503 => "retry later"
 404 => "not found"
 _ => "error"
 }
}

fn describe(xs: List[Int]) -> Str {
 match xs {
 [] => "empty"
 [x] => "one: ${x}"
 [first, .., last] => "from ${first} to ${last}"
 }
}

fn main(os: Os) {
 for c in [200, 503, 404, 500] {
 os.stdio.println("${c} ${status_text(c)}")
 }
 os.stdio.println(describe([]))
 os.stdio.println(describe([7]))
 os.stdio.println(describe([1, 2, 3]))
 let pair = (3, "three")
 let (n, word) = pair
 os.stdio.println("${n} ${word} ${pair is (3, _)}")
}

Output:

Values and mutation

Mon, 01 Jan 0001 00:00:00 +0000

Everything in Xo is a value: assigning or passing a struct copies it (cheaply, because collections share structure). There are no pointers, so two parts of a program can never change the same value without synchronization, and data races cannot happen.

mutation/main.xo

struct Account { owner: Str, balance: Int }

fn (var a: Account) deposit(amount: Int) requires amount > 0 {
 a.balance += amount
}

fn main(os: Os) {
 var acct = Account{owner: "ada", balance: 10}
 let snapshot = acct
 acct.deposit(5)
 os.stdio.println("now ${acct.balance}, snapshot ${snapshot.balance}")

 var accounts: Map[Str, Account] = {"ada": acct}
 accounts.update("ada", Account{owner: "ada", balance: 0}, fn(var a) { a.deposit(100) })
 let stored = accounts.get("ada").map(fn(a) { a.balance }) ?? 0
 os.stdio.println("stored ${stored}")

 let hits = Atomic[Int].new(0)
 let cache = Mutex[Map[Str, Int]].new({})
 cache.with(fn(var m) { m.put("k", hits.add(1)) })
 let size = cache.with_read(fn(m) { m.len() })
 os.stdio.println("hits ${hits.get()}, cache ${size}")
}

Output:

Effects and capabilities

Mon, 01 Jan 0001 00:00:00 +0000

In Xo, a function’s signature says what it can touch. The effects are net, fs, clock, rand, env, proc, and stdio. A pub function declares the ones it uses; one without a uses clause is pure.

effects/main.xo

pub fn banner(out: Stdio, name: Str) uses stdio {
 out.println("== ${name} ==")
}

pub fn slugify(s: Str) -> Str {
 s.trim().to_lower().replace(" ", "-")
}

fn main(os: Os) {
 banner(os.stdio, slugify(" Hello World "))
}

test "banner prints the name" {
 banner(os.stdio, "x")
 expect(os.stdio.output()) == "== x ==\n"
}

Output:

Structured concurrency

Mon, 01 Jan 0001 00:00:00 +0000

concurrency/main.xo

fn square(n: Int) -> Int { n * n }

fn main(os: Os) {
 let sum = scope s {
 let a = s.spawn(fn() { square(3) })
 let b = s.spawn(fn() { square(4) })
 a.await + b.await
 }
 os.stdio.println("sum ${sum}")

 let ch = Chan[Int].new(cap: 8)
 let total = scope s {
 s.spawn(fn() {
 for i in 1..=5 { ch.send(i) }
 ch.close()
 })
 var t = 0
 for x in ch { t += x }
 t
 }
 os.stdio.println("total ${total}")
}

Output:

Contracts and tests

Mon, 01 Jan 0001 00:00:00 +0000

contracts/main.xo

struct Account { id: Int, balance: Int } invariant balance >= 0

enum TxErr { Insufficient } derive Display

fn withdraw(a: Account, amount: Int) -> Account ! TxErr
 requires amount > 0
 requires a.balance >= amount else TxErr.Insufficient
 ensures result.balance == a.balance - amount
{
 a with {balance: a.balance - amount}
}

fn main(os: Os) {
 let a = Account{id: 1, balance: 50}
 match withdraw(a, 80) {
 Ok(b) => os.stdio.println("left ${b.balance}")
 Err(Insufficient) => os.stdio.println("insufficient funds")
 }
}

test "withdraw lowers the balance" {
 let b = withdraw(Account{id: 1, balance: 50}, 20)?
 expect(b.balance) == 30
}

test "reverse twice" for xs: List[Int] {
 expect(xs.reverse().reverse()) == xs
}

Output:

A small web service

Mon, 01 Jan 0001 00:00:00 +0000

webservice/main.xo

use std/http

pub struct Todo {
 pub id: Int
 pub title: Str
 pub done: Bool
} derive Json

pub enum ApiErr {
 NotFound(id: Int)
}

fn (e: ApiErr) status() -> Int {
 match e {
 NotFound(_) => 404
 }
}

fn (e: ApiErr) display() -> Str {
 match e {
 NotFound(id) => "todo ${id} not found"
 }
}

fn find(todos: List[Todo], id: Int) -> Todo ! ApiErr {
 todos.find(fn(t) { t.id == id }).or_err(ApiErr.NotFound(id: id))
}

fn routes(todos: List[Todo]) -> http.Router {
 var r = http.router()
 r.handle("GET /todos", fn(_req) { http.json(200, todos) })
 r.handle("GET /todos/{id:Int}", fn(req) -> http.Response ! ApiErr {
 http.json(200, find(todos, req.param_int("id"))?)
 })
 r
}

fn main(os: Os) ! {
 let todos = [Todo{id: 1, title: "write the tour", done: false}]
 http.server(os.net.listen(":8080")?, routes(todos)).serve()?
}

test "missing todo is a 404" {
 let r = routes([])
 let resp = r.call(http.new_request("GET", "/todos/7"))
 expect(resp.status) == 404
 expect(resp.text() ?? "") == "{\"error\":\"todo 7 not found\"}"
}

Output:

Using Go packages

Mon, 01 Jan 0001 00:00:00 +0000

Until Xo has its own ecosystem, any Go package is one line away:

gointerop/main.xo

use go "strings"
use go "net/url"

fn main(os: Os) ! {
 os.stdio.println(strings.to_upper("hello from go"))
 let u = url.parse("https://xolang.dev/docs?tab=tour")?
 os.stdio.println("${u.hostname()} ${u.query().get("tab")}")
}

Output:

HELLO FROM GO
xolang.dev tour

xo check, build, run, and test generate the bindings themselves.
Names follow Xo’s style: ToUpper is to_upper.
Go’s (T, error) becomes T ! go.Error, so url.parse(...)? works like any Xo call, and a pointer that may be nil becomes T?.
Every call into Go performs the go effect. Go code can reach files and the network without a capability, so a pub function that calls Go must say uses go, and that escape stays visible in signatures.

Native builds can call C the same way with use c "header.h"; see section 4.5 of the specification.