Nomi cheat sheet
Nomi is a statically typed language where every value is immutable. This page holds the rules most often written wrong by someone coming from Rust, Go, Elixir, TypeScript or Python. Every example is a test that the compiler checks. The full rules are in the specification, and the idiom is in Writing Nomi.
Bindings and functions
Section titled “Bindings and functions”- Code is never in braces. A function, an
ifbranch, acase, a lambda, a struct or a test is a header line, the body on the lines below, andend. An empty body is one line:fn noop() end,impl Marker for P end. Braces and brackets hold data only:{x: 1},Point{x: 1},[1, 2]. - A header ends with its line. Brackets carry it on, and a line that starts
with
whereor|>continues it. begin, statements andendis a block expression.end,beginandthenare reserved words.- There is no
let,var,constor:=. A binding isname = expr, with an optional type:total: Int = 0. A latername = ...binds the name again. - Values are immutable. A struct or collection is “changed” by building a new one. Closures capture values when they are created.
- A named function writes its parameter types and any return type other than
Unit. Its body’s last expression is its result.returnis there for an early exit. - A parameter may have a default, and an argument may name its parameter.
A parameter with a default may leave out its type when the default tells
it:
fn search(query: String, limit = 10). - A parameter the body never reads may be written as its type alone:
fn health(Request) -> Responsetakes aRequestand binds nothing. - A lambda is
fn x -> expron one line, orfn x, y ->with the body on the lines below andend. Its parameters are inferred from where it is passed. A lambda bound to a name needs annotated parameters:fn n: Int -> n * 2. In a collection literal, one element’s annotation types the same parameter in the others:[("a", fn n: Int -> n), ("b", fn n -> n * 2)]. once name = expris the only file-level value computed by code, once, on first use, even when several tasks read it together.embed site `static`is a file-levelembed.Filesholding the files understatic/at compile time, so a built executable carries them.Files.read_text(site, "static/index.html")reads a file’s bytes when it is called, not at startup.
fn area(width: Int, height: Int = 1) -> Int
width * height
end
once limit = 3
test "bindings and functions"
x = 2
x = x + 1
double = fn n: Int -> n * 2
assert area(x, height: 4) == 12
assert area(5) == 5
assert double(limit) == 6
endok bindings and functions
test result: ok. 1 passed, 0 failed
Literals
Section titled “Literals”- A named struct is its name and its fields:
Point{x: 1},Shape.Circle{radius: 1.0},.Circle{radius: 1.0}, in aniforcasehead as anywhere else. A named tuple is its name and its elements:Pair(1, "x"). - A tuple’s items are read by ordinal, counting from one as
&1does:t.first,t.second, …t.twentieth, nevert.0. A named tuple reads them the same way, and so do accessors and captures:Iter.map(.second),&(&1.first * 2). - A tuple is its parentheses with a comma inside:
(a, b);(x)only groups. Passed as a call’s one argument it keeps its own parentheses,f((a, b)), and a function type taking one tuple is((A, B)) -> C. - A struct with no name is its brace alone,
{x: 1}: it builds the struct its position expects, or an anonymous one, as.Circle{radius: 1.0}drops the enum’s name. - Collection literals have no symbol.
[1, 2]is the List, Vector or Set its position expects, and a List where nothing fixes it: withv: Vector<Int>,v = [1, 2]is a vector.Vector[1, 2]andSet[1, 2]name the collection where nothing expects one. Write a list and a map bare, neverList[...]orMap{...}. - A
{always opens data, never code. Its first entry decides:name:is a struct,key =>a map.{}is the empty map, since an anonymous struct has at least one field. - An update copies a struct with fields changed:
{..p, y: 5}. In a field’s new value,..is the value already there:{..user, address: {.., city: "NYC"}}changes only the city, and{..user, visits: .. + 1}counts one more. Write.., not the path again (user.visits). - A field or a named argument whose value is a binding of its own name is
punned with its colon:
Point{x:, y:},{name:},Response.json(body, status:). The name alone is no field:Point{x}is an error. - Patterns use the same forms as literals.
[first, ..rest]takes apart the list, vector or set its subject is; over a set its elements are constants the set must hold:["admin", ..rest]. - Types are written without a symbol, except anonymous structs:
List<Int>,Vector<T>,Map<K, V>,Set<T>,(Int, String),{x: Int}. - Strings interpolate with
${...}; a backtick string is raw. A type name before a string is a typed literal. Without a slot it is checked at compile time and is the value:Date"2026-05-04"is aDate,Regex`\d+`aRegex(backticks only for backslashes). With a slot it is built at run time:Date"2026-${m}-04"is aResult. AUrl(aCheckedLiteral) is checked with slots too, each escaped:Url"https://x.org/${id}"is aUrl. Where one is expected the tag can be left out:u: Url = "https://x.org/". - std::html’s
Html"..."is an HTML template the compiler checks. Each${...}is escaped for where it stands. A one-line fragment quotes its attributes with', since"ends the literal:Html"<b class='x'>${n}</b>". Several lines go inHtml"""...""". - A
Decimalliteral ends ind:1.50d.+,-and*are exact, and/rounds to 34 significant digits, half-even, keeping an exact quotient exact:10.00d / 4d == 2.5d.Decimal.divide(a, b, 2, .HalfEven)names the scale instead.%is the remainder with the left operand’s sign onInt,FloatandDecimalalike (-7 % 3 == -1;Int.modulois the floored form). AnIntand aDecimalnever mix in one operator: writeInt.to_decimal(n) / 100d. - The constants are
True,False,NoneandUnit. There is nonull. Each is a pattern as well:Ok(Unit) -> ...matches aResult<Unit, E>.
| Shape | Literal | Named form |
|---|---|---|
| list | [1, 2] | Ids[1, 2] |
| vector | [1, 2] where expected, Vector[1, 2] | Path[1, 2] |
| tuple | (1, "x") | Pair(1, "x") |
| struct | Point{x: 1}, {x: 1} | Shape.Circle{radius: 1.0}, .Circle{radius: 1.0} |
| map | {"a" => 1} | Kvs{"a" => 1} |
| set | [1, 2] where expected, Set[1, 2] | Tags["a"] |
struct Point
x: Int
y: Int = 0
end
test "literals"
point = Point{x: 1}
moved = {..point, y: 5}
(count, name) = (2, "Ada")
pair = (2, "Ada")
assert moved == Point{x: 1, y: 5}
assert {..moved, y: .. + 1} == Point{x: 1, y: 6}
assert {"a" => 1, "b" => 2} == {"b" => 2, "a" => 1}
assert "${name} has ${count}" == "Ada has 2"
assert pair.second == name
assert Int.to_decimal(1999) / 100d == 19.99d
assert -7.5d % 2d == -1.5d
assert `a\n` == "a\\n"
assert [first, ..rest] = [1, 2, 3]
assert first == 1 and rest == [2, 3]
tags: Set<String> = ["a", "b"]
assert tags == Set["b", "a"]
assert ["a", ..others] = tags
assert others == Set["b"]
endok literals
test result: ok. 1 passed, 0 failed
Types and calls
Section titled “Types and calls”- A struct’s fields, an enum’s variants and an interface’s functions are one
per line, with no commas,
|orfieldkeyword. An interface declares only functions. A value every implementor supplies is a function, such asfn name(value: self) -> String. - A field with a default may leave out its type when the default tells it:
misses = 0is anIntfield. An empty collection,Noneor a.Variantneeds the type written:guessed: Set<String> = []. value as Typechecks the value against the type where no annotation can stand:[] as List<String>in a record literal. It converts nothing: withx: Int,x as Floatis an error; writeInt.to_float(x).- A type parameter may have a default,
Route<P = Unit>:route: Routetakes only aRoute<Unit>, never a type to infer. - Behavior goes in top-level
impl Type,impl Interface for Typeandderive Interface for Typedeclarations. type UserId Intis a distinct type:UserId(5)builds one, and the patternUserId(n)opens it.subtype Port Int when fn p -> p >= 1is an Int. A literal Port is checked when compiling; another Int needsPort.try_from(n), a Maybe.type Email String when ...converts to nothing, built the same way.PositiveIntisNonNegativeInt and NonZeroInt.Int.clamp(n, 0..=10)takes a range subtype.- With
naNonNegativeInt,n + 1is aPositiveInt,n - 1an Int. Afterif d == 0 then return,dis aNonZeroInt, as/needs. In1..=n |> Iter.filter(fn d -> n % d == 0),dis 1 or more, so%takes it too. - A value converts to wider type arguments through every position that
only holds them: a
List<Maybe<Int>>passes where aList<Display>is expected, and aBox<Int>where aBox<Display>is when Box’s fields only hold itsT. A function’s parameter converts the other way, and a parameter a type both holds and takes compares exactly. Where nothing says which way values flow (a + b, two branches, two list elements), their types must be one, or a subtype and its ancestor, which join as it. - There are no method calls.
x.nameonly reads a field. A function is called through its owner:- a type:
String.trim(s),Map.get(m, k),Shape.area(shape); - an interface:
Display.to_string(x), orT.to_string(x)for a bounded type parameter; - a file, for its file-level functions:
io.print(x).
- a type:
to_string(n)with no owner,int.to_string(n)andx.to_string()are errors. A file’s name reaches only its file-level functions, never one declared in animpl:duration.seconds(1)is an error, andDuration.seconds(1)is the call.- An owner is a name, never a type with arguments:
List<String>.from_json(json)reads as comparisons, and is an error. The type argument goes on the call,FromJson.from_json<List<String>>(json), or the result is annotated. - A parameter used only through one interface, whose type appears nowhere
else in the signature, takes the interface:
fn label(value: Named). A type parameter is for a type that comes back, in another parameter, the result or another type:fn larger<T>(a: T, b: T) -> T where T: Comparable.
import std::json.{FromJson, Json}
enum Shape
Circle {radius: Float}
Square {side: Float}
end
impl Shape
fn area(shape: Shape) -> Float
case shape
.Circle{radius:} -> 3.0 * radius * radius
.Square{side:} -> side * side
end
end
end
derive Equatable for Shape
interface Named
fn name(value: self) -> String
end
impl Named for Shape
fn name(shape: Shape) -> String
case shape
.Circle{} -> "circle"
.Square{} -> "square"
end
end
end
type UserId Int
fn label(value: Named) -> String
"a ${Named.name(value)}"
end
test "types and calls"
shape = Shape.Square{side: 2.0}
UserId(id) = UserId(7)
assert Shape.area(shape) == 4.0
assert Named.name(shape) == "square"
assert label(shape) == "a square"
assert shape == .Square{side: 2.0}
assert id == 7
assert Int.to_string(42) == "42"
assert Ok(json) = Json.decode("[\"a\", \"b\"]")
assert FromJson.from_json<List<String>>(json) == Ok(["a", "b"])
endok types and calls
test result: ok. 1 passed, 0 failed
Branching and errors
Section titled “Branching and errors”ifandcaseare expressions.if c thenat a line’s end takes the lines below toelseorend, and anelse if c thenchain shares oneend. Anything afterthenon its line makes an inlineifwith noend:sign = if n < 0 then "-" else "+". Itselsebranch runs as far right as it can, so(if c then a else b) |> fpipes the wholeif.case x, one arm per line, thenend. An arm ispattern -> expr, orpattern ->at the line’s end with its statements below, up to the next arm orend.casemust cover every shape the value can take. A guard is writtenwhen:Some(n) when n > 0 -> ....- A name in a pattern binds a new variable; it never compares. A pattern
name that names a
onceis an error, so write the comparison as a guard:c when c == not_found -> .... - The branches of an
iforcasehave one type. Branches of different types that implement one interface join as it only where an annotation, a parameter or a declared result names that interface:shape: Shape = if round then Circle{r: 1.0} else Square{side: 2.0}. - An
ifwithoutelseis a statement, as in Rust: its branch isUnit, leaves (return,?) or ends inassertordbg, and so is anelse ifchain with no finalelse. Any other branch is an error, aMaybeincluded: writeif n > 0 then Some("positive") else None, or_ = ...in a statement’s branch that drops a value. In anHtmlliteral,${if c then Some(Html"...") else None}shows the part or nothing, as doesclass='badge ${if c then Some("on") else None}'in a quoted value; unquoted,class=${if c then Some("on") else None}writes the attribute or leaves it out. - There are no exceptions. A function that can fail returns
Maybe<T>(Some(v)orNone) orResult<T, E>(Ok(v)orErr(e)). - A postfix
?returns anErrorNonefrom the enclosing function, lambda or test. A postfix!traps on one. A program’smainmay return aResult. - When the
Err’s type is not the function’s declared error type,?applies the declared type’sFromimpl: withimpl From<DbError> for ApiError,count()?in a function returningResult<_, ApiError>returnsErr(ApiError.from(e)). The impl is written on the target type, one per wrapped error; there is noIntoand no chaining. A lambda with no declared result does not convert. Without an impl, convert at the site with|> Result.map_err(...)?. - A field that must tell a JSON key left out from one set to
null, as in a PATCH body, is std::presence’sPresence<Maybe<T>>:Absent,Present(None)orPresent(Some(v)). AMaybe<T>field reads both asNone.Presence.with_default(p, current)merges it, and?and!do not take aPresence. - Inside a lambda,
returnand?leave the lambda. - In a pipe,
text |> parse()?passes up a failure of that stage, and|> then? fn v -> ...does the same for a lambda’s result. x is Patternis aBool.- A resource is closed by a
deferon the line after it is acquired; std has nowith_*function taking a lambda. A deferred call returnsUnit, so a writer’s success path ends withWriter.close(w)?, which commits and reports a failed close, afterdefer Writer.discard(w), which drops the output on anError a trap. Compile errors: an opened resource with no deferred release, one dropped with_ = fs.open(p)?, and a deferred discard on a path that returnsOkwithout the close. - A function that opens a resource and returns it releases it with
defer on error sql.close_quietly(conn)on the line after opening it, which runs only if the function then fails (a?, areturnofErrorNone, or a trap). A?before the value is handed on with no such release is a compile error, and so is a normal return without the value (return Ok(None)) that does not call the release first.
import
std::json.Json
std::presence.Presence
end
fn parse_age(text: String) -> Result<Int, String>
age = String.to_int(text) |> Maybe.to_result("not a number: ${text}")?
if age < 0 then
Err("negative: ${age}")
else
Ok(age)
end
end
enum DbError
Closed
end
enum ApiError
Database DbError
end
impl From<DbError> for ApiError
fn from(e: DbError) -> ApiError
ApiError.Database(e)
end
end
fn count() -> Result<Int, DbError>
Err(.Closed)
end
fn handler() -> Result<Int, ApiError>
n = count()?
Ok(n)
end
fn describe(age: Maybe<Int>) -> String
case age
Some(n) when n >= 18 -> "adult"
Some(_) -> "minor"
None -> "unknown"
end
end
test "branching and errors"
assert parse_age("41") == Ok(41)
assert parse_age("x") == Err("not a number: x")
assert handler() == Err(ApiError.Database(.Closed))
assert describe(Some(12)) == "minor"
assert (if 12 > 18 then Some("adult") else None) == None
assert String.to_int("7")! == 7
assert Some(1) is Some(_)
patch = Json.decode_as<{due: Presence<Maybe<Int>>}>(`{"due": null}`)!
assert patch.due == Presence.Present(None)
assert Presence.with_default(patch.due, Some(5)) == None
endok branching and errors
test result: ok. 1 passed, 0 failed
Iteration and pipes
Section titled “Iteration and pipes”x |> f(a)isf(x, a). A call whose result feeds another call is written as a pipe.- Every collection is an
Iter, and the algorithms areIter’s functions:Iter.map,Iter.filter,Iter.reduce,Iter.count,Iter.sort. There is noList.map. Operations particular to one container stay on its type:List.first,List.length,Map.get,Set.insert,Set.union. - Adapters are lazy.
Iter.to_list,to_vector,to_setandto_mapcollect, andString.joinjoins strings. - A fold’s starting value comes before its callback:
Iter.reduce(xs, 0, fn acc, x -> acc + x). So doIter.scan,Iter.map_reduceandIter.loop. - A capture is a short lambda:
&(&1 * 10),&Map.get(m, &1),&"id ${&1}". - There are no
fororwhileloops. UseIterfunctions, recursion (tail calls run in constant stack), orIter.loop(start, fn state -> ...)withbreak. Iteris a push protocol: a type is iterable through animpl Iterwhoseeach_whilehands out its elements.
test "iteration and pipes"
evens =
1..=10
|> Iter.filter(fn n -> n % 2 == 0)
|> Iter.map(&(&1 * 10))
|> Iter.to_list()
assert evens == [20, 40, 60, 80, 100]
assert Iter.reduce(evens, 0, fn acc, n -> acc + n) == 300
assert List.first(evens) == Some(20)
assert ["b", "a"] |> Iter.sort() |> String.join(", ") == "a, b"
assert Iter.map_reduce([1, 2], 0, fn total, n -> (total + n, total)) == (3, [0, 1])
endok iteration and pipes
test result: ok. 1 passed, 0 failed
Modules and imports
Section titled “Modules and imports”- A
.nomifile is the unit of import and of visibility. Its top-level declarations are private unless markedpub. Its partner test,shapes_test.nomiforshapes.nomi, reads its private ones too. - A module is the directory tree under a
nomi.toml.entry_pointslists the files with afn main. Animpl Interface for Typeneeds the interface, the type or both to be the module’s own. - Imports name files by path, segments joined by
::(never/):import std::io, thenio.print(x). Braces bring in names:import std::io.{self, Writer}. Several imports group underimportalone on its line, one per line below, thenend. Unused imports are errors. - A file import binds the file’s short name, the path’s last segment (
io,posts), and nothing else:db::posts.find(1)afterimport db::postsis an error. Importing a directory (import db) binds its name, and a path below it reaches a file:db::posts.find(1),x: db::schema.Post. Two imports of one short name are an error; import their directories instead, or alias one. - Names are snake_case, types PascalCase. A predicate is
is_<state>,has_<thing>or a bare verb (contains,starts_with).
// FILE: shapes.nomi
pub struct Box
side: Int
end
pub fn area(box: Box) -> Int
box.side * box.side
end
// FILE: geo/shapes.nomi
pub fn area(radius: Int) -> Int
3 * radius * radius
end
// FILE: main.nomi
import
std::io
demo
geo
end
fn main()
// Two files are `shapes`, so each is reached through its directory.
// The module's own name is its root directory.
io.print(demo::shapes.area(demo::shapes.Box{side: 3}))
io.print(geo::shapes.area(2))
end
// FILE: nomi.toml
[module]
name = "demo"
entry_points = ["main"]9
12
App fields, tests and concurrency
Section titled “App fields, tests and concurrency”- A program’s configuration and dependencies are one app struct. The entry
file’s
fn boot(startup: Startup) -> Result<App, E>builds it from the arguments and environment and returns it inOk. AnErrstops the program beforemain. The struct has at most oneContextfield, which boot builds withContext.root(). - Code reads a field as
App.field. The statementwith App.field = valuereplaces it from that line to the end of the block. Several fields take several lines. test "name"blocks, closed byend, sit beside the code.assertchecks aBool,SomeorOk, or a pattern;refutethe opposite.nomi testruns them.- A
groupholds at most oneclock,bootandsetup, in that order, then its tests. Groups do not nest.boot server.boot(startup)calls an entry’s boot; a test may also callserver.boot(startup)itself to assert on theResult. A test binds the setup value with a pattern:test "loads rows", db. Each test runs clock, boot, setup and body afresh.clock Clock.Virtualmakes waits instant. - Tasks start only inside a
concurrentblock,concurrentalone on its line andend, which waits for them:Task.spawn(fn -> ...)andTask.await(task), fromstd::tasks. Every task is awaited.std::channelssplits a channel into aSenderand aReceiver. ASupervisoris created only whilebootbuilds the app struct.
import
std::io
std::tasks.Task
end
struct App
greeting: String
end
fn boot(startup: Startup) -> Result<App, String>
Ok(App{greeting: Map.get(startup.env, "GREETING") |> Maybe.with_default("hello")})
end
fn greet(name: String) -> String
"${App.greeting}, ${name}"
end
fn main()
io.print(greet("Ada"))
end
group "greetings"
boot boot(Startup{env: {"GREETING" => "hi"}})
test "app fields"
assert greet("Ada") == "hi, Ada"
with App.greeting = "hey"
assert greet("Ada") == "hey, Ada"
end
test "tasks"
total = concurrent
a = Task.spawn(fn -> 20)
b = Task.spawn(fn -> 22)
Task.await(a) + Task.await(b)
end
assert total == 42
end
endhello, Ada
ok greetings / app fields
ok greetings / tasks
test result: ok. 2 passed, 0 failed
- There is no
strftime-style pattern for text a person reads. Write it with a skeleton and a locale:DateTime.format_fields(at, locale, DateTimeFields"yMMMd")names the fields and their widths, and the locale gives the order, punctuation and words.DateTime.format(at, locale, date: .Long, time: .Short)takes a style instead.Date,TimeandNaiveDateTimehave the same two functions. - In
en-US, a skeleton with a date and a time puts a comma after the year and U+202F, a narrow no-break space, beforeAMorPM; a test writes it as\u{202f}. DateTimePattern,DatePatternandTimePatternwrite fixed numeric text for file names, logs and protocols withto_string_with. They refuse month and weekday names andAM/PM.
import std::calendar.{DateTime, DateTimeFields, DateTimePattern}
test "dates"
at = DateTime"2026-01-05T15:04:00-05:00[America/New_York]"
en = Locale"en-US"
assert DateTime.format_fields(at, en, DateTimeFields"yMMMd") == "Jan 5, 2026"
assert DateTime.format_fields(at, en, DateTimeFields"yMMMdjmm") == "Jan 5, 2026, 3:04\u{202f}PM"
assert DateTime.format(at, en, date: .Long, time: .Short) == "January 5, 2026, 3:04\u{202f}PM"
assert DateTime.to_string_with(at, DateTimePattern"yyyy-MM-dd HH:mm") == "2026-01-05 15:04"
endok dates
test result: ok. 1 passed, 0 failed