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.
The basic shape
Section titled “The basic shape”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}")
endlistening on :8080
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
endok greetings / only the audited greeting carries the audit field
test result: ok. 1 passed, 0 failed
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())
endpsst, world
hello, world
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.
withtakes no body: it lasts to the end of the block it stands in. - The target must be an app field.
with Point.x = 1is an error. withworks in any block: aniforcasearm, a lambda body, a test body, a group’ssetup. 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
oncewith a field’s name, sinceApp.namealways reads the field.
Spec: with,
Reading a field.
defer runs block-scoped cleanup
Section titled “defer runs block-scoped cleanup”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")
endopen notes
open log
body
close log
close notes
after the block
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
deferline, 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, asReader.close_quietlydoes. - 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
deferin a lambda runs when that call of the lambda ends, so one in anItercallback runs once per round. - A pending
deferturns a tail call into an ordinary call (Recursion and tail calls).
Spec: defer,
Cleanup and boot failure.
Cleanup and failure in boot
Section titled “Cleanup and failure in boot”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}")
endopening the log
closing the log
error: TOUR_DATABASE_PATH is not set
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 per environment
Section titled “Settings per environment”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")
enddev: postgres://localhost/myapp_dev, 5 connections
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.
Deadlines
Section titled “Deadlines”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
Contextfield runs under a root context with no deadline. An app struct has at most oneContextfield, under any name. bootgets no context. It builds one withContext.root()or a deriver such asContext.with_timeout(Context.root(), d).- A context also carries values keyed by their type, for metadata such as a
trace ID:
Context.with_valueadds one andContext.valuereads it.
Spec: Context, Context values.
Testing code that reads app fields
Section titled “Testing code that reads app fields”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
endenv: dev
ok app-backed behavior / reads the booted field
ok app-backed behavior / a with line replaces a field for the rest of the body
test result: ok. 2 passed, 0 failed
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
endverbose: False
ok quiet by default / takes no arguments
ok verbose / reads -v
test result: ok. 2 passed, 0 failed
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 that fails
Section titled “A boot that fails”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")
endstore: memory
ok postgres without a URL stops the program
test result: ok. 1 passed, 0 failed
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.