Generating Code
Some code is better written by a program than by hand: an enum for every
value a data file lists, a lookup function for every row of a table, a typed
function for every SQL query. Nomi has no macros. A library that writes code
for you ships a tool, an ordinary Nomi program that reads your data and
writes ordinary .nomi files. You run it, read what it wrote, and commit
it like any other file of your project.
The Libraries chapter Databases shows the biggest example,
sqlkit’s nomi tool sqlkit generate, which writes typed functions for SQL.
This chapter writes a small one of its own.
A tool
Section titled “A tool”A cafe lists the choices it offers in a file, one line per enum:
Size: small medium large
Roast: light medium dark
A tool turns each line into an enum. A tool is a program in a module’s
tools/ directory, with a fn main like any program. Here it is the
cafe’s own, tools/choices.nomi:
- go.mod
- nomi.toml
- enums.choices
- enums.nomi
- main.nomi
- tools/choices.nomi
nomi tool cafe choices runs tools/choices.nomi from the module cafe,
with the current directory as its working directory, and with the same
access to files, the network and output that nomi run gives a program.
It reads enums.choices and writes enums.nomi, which main.nomi imports
like any other file. The tool builds each enum from a triple-quoted string,
so its template reads like the code it writes. It passes the result through
compiler.format from std::compiler before writing
it, so the generated file is laid out as nomi fmt would lay it out.
This example runs the tool before each run, as you would after an edit. Add a size, or a line of your own, and run it again: the generated file’s tab shows the change.
// FILE: enums.choices
Size: small medium large
Roast: light medium dark
// FILE: main.nomi
import
std::io
enums.{Roast, Size}
end
fn ounces(size: Size) -> Int
case size
Size.Small -> 8
Size.Medium -> 12
Size.Large -> 16
end
end
fn main()
io.print(ounces(Size.Medium))
io.print(Roast.Dark == Roast.Dark)
end
// FILE: enums.nomi
// Generated by `nomi tool cafe choices` from enums.choices. Do not edit.
/// The choices of `Size` in enums.choices.
pub enum Size
Small
Medium
Large
end
/// The choices of `Roast` in enums.choices.
pub enum Roast
Light
Medium
Dark
end
// FILE: tools/choices.nomi
// `nomi tool cafe choices`: write enums.nomi from enums.choices, one
// enum per line. A line `Size: small medium large` declares
// `pub enum Size` with the variants `Small`, `Medium` and `Large`.
import
std::compiler
std::fs
std::io
end
fn main() -> Result<Unit, String>
text = fs.read_text("enums.choices") |> Result.map_err(fn e -> "enums.choices: ${e}")?
enums =
String.split(text, "\n")
|> Iter.with_index()
|> Iter.filter(fn (_, line) -> String.trim(line) != "")
|> Iter.map(fn (i, line) -> enum_of(i + 1, line))
|> Result.collect()?
body = String.join(enums, "\n\n")
source = """
// Generated by `nomi tool cafe choices` from enums.choices. Do not edit.
${body}
"""
text = compiler.format(source) |> Result.map_err(fn e -> "enums.nomi does not parse: ${e}")?
fs.write_text("enums.nomi", text) |> Result.map_err(fn e -> "enums.nomi: ${e}")?
io.print("wrote enums.nomi")
Ok(Unit)
end
// The enum line `number` declares.
fn enum_of(number: Int, line: String) -> Result<String, String>
(name, words) = case String.split(line, ":") |> Iter.to_list()
[name, words] -> (String.trim(name), String.words(words))
_ -> return Err("enums.choices:${number}: write `Name: first second third`")
end
if Some(word) = Iter.find(words, fn w -> not is_snake_case(w)) then
return Err("enums.choices:${number}: `${word}` is not a snake_case word")
end
variants = words |> Iter.map(fn w -> " ${String.pascal_case(w)}") |> String.join("\n")
Ok(
"""
/// The choices of `${name}` in enums.choices.
pub enum ${name}
${variants}
end
"""
)
end
fn is_snake_case(word: String) -> Bool
word != "" and Iter.all_match(word, fn c -> c in "abcdefghijklmnopqrstuvwxyz_")
end
// FILE: go.mod
module cafe
go 1.27.0
// FILE: nomi.toml
[module]
name = "cafe"
entry_points = ["main"]wrote enums.nomi
12
True
enums.nomi starts with a comment saying it is generated and must not be
edited by hand, since the next run of the tool would undo the edit. Change
enums.choices and run the tool instead.
The tool is the place to check its input. Change small to Small in
enums.choices above and run the example. The tool stops with an error
that names the line, and it writes nothing:
$ nomi tool cafe choices error:
The tool’s main returns an Err, which nomi tool prints after
error: , as nomi run does.
Running tools
- A tool is any file in a module’s
tools/directory with afn main. It needs no entry innomi.toml. - The words after the tool’s name are its
startup.args, as a tool reads--checkbelow. - The
nomicommand listsnomi toolwith the other commands.
Keeping generated files current
Section titled “Keeping generated files current”Generated files go stale when an input changes and nobody runs the tool
again. A generator can guard against that in two ways. Take a module
csvdata whose tool, nomi tool csvdata generate, turns each CSV file under
data/ into a lookup function in tables.nomi. It records a SHA-256 digest
of its inputs (hash.sha256_hex from std::hash) at the
top of each file it writes:
// Generated by `nomi tool csvdata generate` from data/*.csv. Do not edit. // inputs sha256: ff6bb7acf34bfd46759e72257f8e01131f1fecfe3f9660edc20f6467999dd93e
The first guard is --check: the tool writes nothing and fails when a
file differs from what it would write. Run that command in an automated
check:
$ nomi tool csvdata generate --check error:
The second guard is a test, which uses the digest. The tool also writes
tables_test.nomi, whose test computes the digest of the inputs again with
csvdata.inputs_digest, the function the tool uses, and compares it with
the one in the header. A plain nomi test then fails when a CSV file
changed after the tool last ran. A test resolves a relative path under its
module root, so it reads the same files wherever nomi test runs:
// Generated by `nomi tool csvdata generate` from data/*.csv. Do not edit. // inputs sha256: ff6bb7acf34bfd46759e72257f8e01131f1fecfe3f9660edc20f6467999dd93e import csvdata test "generated tables are current" assert csvdata.inputs_digest("data") == Ok("ff6bb7acf34bfd46759e72257f8e01131f1fecfe3f9660edc20f6467999dd93e") end
The cafe’s tool serves the cafe alone. A generator that several projects
share is a module of its own. A project adds it like any dependency, with
nomi add ../csvdata, and nomi tool csvdata generate, run there, reads
and writes that project’s files.
Where to go next
Section titled “Where to go next”sqlkit’s generate is a whole generator built this way. It reads SQL
migrations and query files, asks SQLite to describe each query, and writes
the schema’s row types and a typed function per query, each file headed by a
digest of its inputs, as above. The Libraries chapter
Databases walks through it.
Building & Shipping is next. It packages a program for someone else to run.