Skip to content

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 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:

cafe/
  • 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"]

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: enums.choices:1: `Small` is not a snake_case word

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 a fn main. It needs no entry in nomi.toml.
  • The words after the tool’s name are its startup.args, as a tool reads --check below.
  • The nomi command lists nomi tool with the other commands.

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: tables.nomi, tables_test.nomi would change: run `nomi tool csvdata generate`

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.

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.