Skip to content

App Fields, Defer & Context

A program can define a function named boot. It builds a struct that holds the things the program needs everywhere, such as settings or a logger, and returns it in Ok. Any code can then read one of the struct’s fields through the struct’s type name, as in App.port. These are called app fields.

The struct may have one field of type Context, with any name you like. A context carries a deadline, explained below.

import std::io

struct App
    port:    Int
    context: Context
end

fn boot() -> Result<App, String>
    Ok(App{port: 8080, context: Context.root()})
end

fn main()
    io.print("listening on :${App.port}")
end

boot always returns a Result: Ok with the struct, or Err when the program cannot start, for example because a setting is missing or a database does not open. The error type is yours to choose; String is the plainest. A boot that cannot fail still returns Result, so adding a step that can fail later does not change its signature, and ? works in its body. A boot that returns the struct without a Result is a compile error.

boot goes in the same file as main. This boot takes no parameter. To read the environment or the command-line arguments, declare fn boot(startup: Startup) instead. startup.env is a Map<String, String> of environment variables, read with Map.get(startup.env, "APP_ENV"). startup.args is a List<String> of the arguments. Startup and Context are available everywhere, so you don’t import them.

App fields can’t be read until boot has returned. So boot builds the struct from its startup parameter, if it has one, and from the functions it calls. If a helper builds part of the struct, pass it what it needs from startup.

boot makes the context with Context.root(), or with a narrower context made from that one, such as one with a deadline.

The struct’s fields are the app fields, with the same types. Here, port: Int makes App.port an Int. You can name the struct App, Config, or anything else. Another file that reads its fields imports it like any other type. The context field can have any name too:

import std::duration.Duration

struct Server
    port:      Int
    execution: Context
end

fn boot() -> Result<Server, String>
    Ok(Server{port: 8080, execution: Context.root()})
end

fn bounded_work()
    with Server.execution = Context.with_timeout(Server.execution, Duration.seconds(3))
    serve(Server.port)
end

Nomi finds the context field by its type, not its name.

main runs with the struct its file’s boot returns in Ok. A test runs with the one its group’s boot line returns (see Testing code that reads app fields). Code that reads Server.port must run under a boot that returns a Server. Code that reads no app field runs under any boot, or none.

with replaces a field for the rest of the block

Section titled “with replaces a field for the rest of the block”

with App.field = value replaces one app field from that line to the end of the block it is in. Every function called in that part of the block sees the new value.

The new value must have the field’s type. If the field is an enum, you can write just .Variant. To replace several fields, write several with lines. Each line sees the values set by the lines above it.

with replaces whole fields of the app struct. To change one part of a field, build an updated copy of it: with App.database = {..App.database, host: "localhost"}.

import
    std::log.{self, Logger}
    std::log::testing
end

struct App
    logger: Logger
end

fn boot() -> Result<App, String>
    Ok(App{logger: Logger.text(min: .Warn)})
end

fn main()
    greet("World")
end

fn audit_greet(name: String)
    with App.logger = Logger.with_fields(App.logger, [log.bool("audit", True)])
    greet(name)
end

fn greet(name: String)
    log.info(App.logger, "hello", [log.string("name", name)])
end

group "greetings"
    boot boot()

    test "only the audited greeting carries the audit field"
        got = testing.run(fn logger ->
            with App.logger = logger
            greet("World")
            audit_greet("Alice")
            greet("Bob")
        end)

        fields = Iter.map(got.records, .fields) |> Iter.to_list()

        assert fields == [
            [log.string("name", "World")],
            [log.bool("audit", True), log.string("name", "Alice")],
            [log.string("name", "Bob")],
        ]
    end
end

When the block ends, the field gets its old value back. This happens however the block ends: at its last line, through return, or through a ?. So a function you call can’t change the fields you see.

To replace a field for only part of a function, move that part into a function of its own, as audit_greet does here.

The app’s std::log Logger writes warnings and errors. The test replaces it with a std::log::testing recorder, which keeps every record as a value, so it can check that only Alice’s greeting carries the audit field.

A closure reads app fields when it is called, not when it is made. So a closure returned from a function after a with line doesn’t keep the replacement:

import std::io

struct App
    greeting: String
end

fn boot() -> Result<App, String>
    Ok(App{greeting: "hello"})
end

fn greet() -> String
    "${App.greeting}, world"
end

fn quiet_greeter() -> () -> String
    with App.greeting = "psst"
    io.print(greet())
    fn -> greet()
end

fn main()
    later = quiet_greeter()
    io.print(later())
end

A task is different. It keeps the app fields that were in force when it was spawned (Concurrency).

Fine print

  • One field per line. A comma after the value is an error. with takes no body: it lasts to the end of the block it stands in.
  • The target must be an app field. with Point.x = 1 is an error.
  • with works in any block: an if or case arm, a lambda body, a test body, a group’s setup. To limit it to part of a function, put it in a block statement or a helper.
  • An app struct can’t declare an inherent function or once with a field’s name, since App.name always reads the field.

Spec: with, Reading a field.

defer runs a call when the block it is in ends. Several deferred calls run in reverse order, last one first:

import std::io

fn main()
    begin
        io.print("open notes")
        defer io.print("close notes")
        io.print("open log")
        defer io.print("close log")
        io.print("body")
    end

    io.print("after the block")
end

close log runs before close notes, the reverse of the order they were deferred in. Both run when the inner block ends, before the line after it.

Opening something can fail. When it returns a Result, open it with ? and then defer the cleanup:

notes = fs.open("notes.txt")?

defer Reader.close_quietly(notes)

If opening fails, the ? returns before the defer line runs, so there is nothing to close. Calls deferred earlier in the block still run. Files has more on closing files.

A function that opens something and returns it can’t defer the close, since the caller still needs it. defer on error runs its call only if the function fails after that line, through a ?, a return of Err or None, or a trap:

pub fn open(path: String) -> Result<SqliteStore, sql.Error>
    conn = sqlite.open(path)?
    defer on error sql.close_quietly(conn)
    _ = Conn.exec(conn, Sql"CREATE TABLE IF NOT EXISTS notes (body TEXT)")?
    Ok(SqliteStore{conn:})
end

The checker holds these rules for every resource. An opened value that is neither released by a defer nor returned is an error. So is a ? between opening a value and handing it on, with nothing that releases it on that path, and a path that returns normally without the value, such as return Ok(None), unless it calls the release first. A value that a plain defer releases can’t leave its block, since it is closed by the time anything outside sees it. Files shows the errors.

Fine print

  • The function and its arguments are evaluated on the defer line, with the app fields in force there. Only the call waits.
  • The deferred call must return Unit, so it can’t report a failure. A cleanup that can fail handles it inside, as Reader.close_quietly does.
  • Every way out of the block runs it: the end, return, break, continue, a ? and a trap. A deferred call that traps doesn’t stop the others or hide the failure that ended the block.
  • A defer in a lambda runs when that call of the lambda ends, so one in an Iter callback runs once per round.
  • A pending defer turns a tail call into an ordinary call (Recursion and tail calls).

Spec: defer, Cleanup and boot failure.

A defer written directly in the body of the program’s boot runs after main and the tasks it owns have finished. In a test, a defer in boot runs when that test finishes. A defer inside a function boot calls, or inside a nested block, runs when that function or block ends, as usual. So if a helper opens something and returns it, boot must defer its cleanup.

boot fails by returning Err. Then main doesn’t run. Any work already started is shut down, the cleanup boot deferred runs, and the program prints error: and the error on stderr and exits with status 1, as when main returns Err. The error prints through its Display impl when it has one; a String prints as itself. A boot whose error is an Exit prints its message and exits with its code, as main would. A trap in boot stops the program the same way a trap anywhere does.

import std::io

struct App
    database: String
end

fn setting(startup: Startup, key: String) -> Result<String, String>
    case Map.get(startup.env, key)
        Some(value) -> Ok(value)
        None        -> Err("${key} is not set")
    end
end

fn boot(startup: Startup) -> Result<App, String>
    io.print("opening the log")
    defer io.print("closing the log")
    database = setting(startup, "TOUR_DATABASE_PATH")?
    Ok(App{database:})
end

fn main()
    io.print("using ${App.database}")
end

In a test, a boot that returns Err fails the test before its setup and body run, and the cleanup boot deferred runs when the test ends (see A boot that fails).

Settings are ordinary code: field defaults for development, a function that adjusts them for each environment, and boot reading the environment variables that override them. Here NOMI_ENV names the environment:

import std::io

struct Config
    deployment:      String = "dev"
    database_url:    String = "postgres://localhost/myapp_dev"
    max_connections: Int = 5
end

fn configure(deployment: String) -> Config
    base = Config{deployment:}

    case deployment
        "prod" -> {..base, max_connections: 20}
        "test" -> {..base, database_url: "postgres://localhost/myapp_test", max_connections: 2}
        _      -> base
    end
end

fn boot(startup: Startup) -> Result<Config, String>
    deployment = Map.get(startup.env, "NOMI_ENV") |> Maybe.with_default("dev")
    configured = configure(deployment)

    database_url =
        Map.get(startup.env, "DATABASE_URL") |> Maybe.with_default(configured.database_url)

    Ok({..configured, database_url:})
end

fn main()
    io.print("${Config.deployment}: ${Config.database_url}, ${Config.max_connections} connections")
end

Every variable the program reads is a Map.get in boot, so there is no hidden mapping from the environment to the struct.

A group’s boot line passes the Startup it builds, not the real environment, so a test picks the test settings with boot boot(Startup{env: {"NOMI_ENV" => "test"}}) (Testing code that reads app fields). nomi test also sets NOMI_ENV to test in its own environment unless it is already set, which a program the tests start sees.

A Context carries a deadline. To set one for the rest of a block, replace the context field: with App.context = Context.with_timeout(App.context, duration). Concurrency shows what a deadline stops and how each task gets its own context.

Fine print

  • A deadline can only get shorter. A child context with a later deadline than its parent keeps the parent’s.
  • A program with no Context field runs under a root context with no deadline. An app struct has at most one Context field, under any name.
  • boot gets no context. It builds one with Context.root() or a deriver such as Context.with_timeout(Context.root(), d).
  • A context also carries values keyed by their type, for metadata such as a trace ID: Context.with_value adds one and Context.value reads it.

Spec: Context, Context values.

Code that reads app fields, such as Config.env, needs a boot to run. In a test, the group calls boot on a boot line, passing a Startup if boot takes one. Code that reads no app field needs no boot line. Testing covers groups, setup and the order they run in for each test.

import std::io

struct Config
    env: String
end

fn boot(startup: Startup) -> Result<Config, String>
    Ok(Config{env: Map.get(startup.env, "APP_ENV") |> Maybe.with_default("dev")})
end

fn main()
    io.print("env: ${Config.env}")
end

group "app-backed behavior"
    boot boot(Startup{env: {"APP_ENV" => "test"}})

    test "reads the booted field"
        assert Config.env == "test"
    end

    test "a with line replaces a field for the rest of the body"
        with Config.env = "staging"
        assert Config.env == "staging"
    end
end

The tests here are in the same file as main, so the boot line calls boot by its bare name. Startup’s fields are empty unless you set them, so the group sets only env.

Most tests need no startup input. If boot reads none, it takes no parameter, and groups write boot boot(). If boot does read startup input, give its parameter a default. Then a group that needs no input writes boot boot(), and the others pass the inputs they want:

import std::io

struct Config
    verbose: Bool
end

fn boot(startup: Startup = Startup{}) -> Result<Config, String>
    Ok(Config{verbose: "-v" in startup.args})
end

fn main()
    io.print("verbose: ${Config.verbose}")
end

group "quiet by default"
    boot boot()

    test "takes no arguments"
        assert Config.verbose == False
    end
end

group "verbose"
    boot boot(Startup{args: ["-v"]})

    test "reads -v"
        assert Config.verbose
    end
end

When the program itself runs, boot still gets the real arguments. The default is used only by a boot line that passes nothing. To run the same tests under several boots, put the group’s lines in a subtests block (Testing).

In a larger project, tests live in their own file. They import the file that holds main and call its boot, as server.boot below. Its setup swaps in a fake mailer with a with line:

// server_test.nomi
import
    server
    server.App
    test_support
    test_support.FakeMailer
end

group "welcome email"
    boot server.boot(test_support.startup())

    setup begin
        with App.mailer = FakeMailer
        "ada@example.com"
    end

    test "sends through the fake", to
        assert server.welcome(to)
    end
end

Here test_support.startup() builds the inputs this group needs. If server.nomi declares pub fn boot(startup: Startup = Startup{}) -> Result<App, String>, a group that needs no input writes boot server.boot().

A boot returns a Result, and a group’s boot line takes it. When boot returns Err, each test in the group fails before its setup and body run. The report is the one a ? gives when it ends a test early: the boot line, and the Err it returned. The cleanup boot deferred still runs when the test ends.

group "without a database path"
    boot server.boot(Startup{})

    test "never gets this far"
        assert server.is_ready()
    end
end

If server.boot returns Err("DATABASE_PATH is not set") for an empty Startup, nomi test reports:

FAIL server_test.nomi :: without a database path / never gets this far
  line 2: test returned early
    boot server.boot(Startup{})
    returned:
      Err("DATABASE_PATH is not set")

To test how boot fails, call it in the test like any function and assert on the Result it returns. A call in a test publishes no app fields, and what boot starts, its cleanup and supervised work, ends with the test.

import std::io

struct App
    store: String
end

fn boot(startup: Startup) -> Result<App, String>
    store = Map.get(startup.env, "STORE") |> Maybe.with_default("memory")

    if store == "postgres" and not ("DATABASE_URL" in startup.env) then
        return Err("STORE=postgres needs DATABASE_URL")
    end

    Ok(App{store:})
end

fn main()
    io.print("store: ${App.store}")
end

test "postgres without a URL stops the program"
    startup = Startup{env: {"STORE" => "postgres"}}
    assert boot(startup) is Err("STORE=postgres needs DATABASE_URL")
end

Only a test and a group’s boot line can call an entry’s boot. Anywhere else, a call of it, or a use of it as a value, is an error.

Input & Output is next. It prints, reads input and sets the exit status.