Skip to content

Files

std::fs reads and writes files by path, and a path is a String. fs.read_text returns a whole file as text, and fs.write_text replaces a file with new text. Both return a Result, since a file can be missing or locked.

The examples on this page run against files that live in the page, not on your disk. Each // FILE: section that is not Nomi code is a file the program starts with, so you can edit todo.txt below and run it again:

// FILE: main.nomi
import
    std::fs
    std::io
end

fn main() -> Result<Unit, io.Error>
    fs.write_text("todo.txt", "milk\n", mode: .Append)?
    io.write(fs.read_text("todo.txt")?)

    fs.write_text("done.txt", "nothing yet\n")?
    io.write(fs.read_text("done.txt")?)
    Ok(Unit)
end

// FILE: todo.txt
bread

mode says what to do with a file that is already there. The default, .Replace, empties it first. .Append writes at its end, .New fails with AlreadyExists instead of touching it, and .ReplaceAtomically writes a temporary file and renames it over the old one, so a program that reads the file never sees half of the new text. fs.read and fs.write are the same pair for Bytes.

The error is an io.Error, an enum whose variants name the path they are about. A program branches on the ones it expects, and its Display text names the path and the problem for the rest:

import
    std::fs
    std::io
end

fn main()
    case fs.read_text("settings.toml")
        Ok(text)                      -> io.print(text)
        Err(io.Error.NotFound{path:}) -> io.print("no ${path}, so the defaults")
        Err(e)                        -> io.eprint("cannot read the settings: ${e}")
    end

    case fs.write_text("logs/today.txt", "started\n")
        Ok(_)  -> io.print("written")
        Err(e) -> io.print(e)
    end
end

A write into a directory that does not exist is NotFound, and it names the directory. fs.create_dir("logs") makes it.

Fine print

  • A relative path is read from the working directory. Under nomi test a test file’s working directory is its module root, the nearest directory above it with a nomi.toml, so fs.read_text("data/rates.csv") reads the same file wherever the tests run.
  • std::fs::testing.run and fs.within replace the file system for the function they run, and tasks it starts inherit the replacement.
  • A browser build has no disk; its program gets a file system in memory (Files in the browser).

std::fs has every function and error, and the tooling reference’s The test environment has the test rules.

fs.lines(path) is an Iter over a file’s lines, each without its line ending. Each item is a Result, since a read can fail partway through. Result.collect turns the items into one Result holding a list, which stops at the first error. Iter.try_reduce folds them with a function that returns a Result, and stops at the first Err:

// FILE: main.nomi
import
    std::fs
    std::io
end

fn count_errors(path: String) -> Result<Int, io.Error>
    fs.lines(path)
    |> Iter.try_reduce(0, fn count, line ->
        if String.starts_with(line?, "ERROR") then
            Ok(count + 1)
        else
            Ok(count)
        end
    end)
end

fn main() -> Result<Unit, io.Error>
    lines = Result.collect(fs.lines("server.log"))?
    io.print("${Iter.count(lines)} lines")
    io.print("${count_errors("server.log")?} errors")
    io.print(Iter.first(fs.lines("server.log")))
    Ok(Unit)
end

// FILE: server.log
INFO started
ERROR disk full
INFO retrying
ERROR disk full

count_errors folds over the file a line at a time, so it never holds the whole file in memory. Each run of fs.lines opens the file, reads it and closes it, so running the same iterator twice reads the file twice, and if the file changed in between, the second run sees the change. Iter.first stops after one line and closes the file as it stops. fs.chunks(path) is the same for Bytes, a piece at a time.

A file you read or write a piece at a time is a stream. fs.open opens a file as a Reader and fs.create as a Writer. Each is closed by a defer on the next line, so it is closed however the function ends. Reader.copy_to copies everything left in a reader into a writer:

// FILE: main.nomi
import
    std::fs
    std::io.{self, Reader, Writer}
end

fn prepend_header(input: String, output: String) -> Result<Int, io.Error>
    r = fs.open(input)?
    defer Reader.close_quietly(r)

    w = fs.create(output, mode: .ReplaceAtomically)?
    defer Writer.discard(w)

    Writer.write_text(w, "name,price\n")?
    copied = Reader.copy_to(r, w)?
    Writer.close(w)?
    Ok(copied)
end

fn main() -> Result<Unit, io.Error>
    copied = prepend_header("prices.csv", "with-header.csv")?
    io.print("copied ${copied} bytes")
    io.write(fs.read_text("with-header.csv")?)
    Ok(Unit)
end

// FILE: prices.csv
apple,3
pear,4

A writer over a file keeps what you write in memory and sends it to the file in large pieces, so writing to a disk can fail late, when the writer closes. That is why Writer.close returns a Result, and why the success path ends with Writer.close(w)?: the close commits the write and reports a failed close. A defer cannot return an error, so the deferred Writer.discard(w) only gives the write up when the function leaves any other way, by an Err or a trap, and with .ReplaceAtomically the old file stays as it was. A discard after the close does nothing. A reader has nothing to commit, so Reader.close_quietly closes it and ignores a failed close.

The compiler checks both halves. Leave out a defer, and the error is `r` is never released; write `defer Reader.close_quietly(r)` after it, or return it; return Ok without the close, and it is `w` is discarded here: this path returns without `Writer.close(w)?`. A reader dropped unread, _ = fs.open(path)?, is an error too. The editor’s quick fix writes the missing lines (Releasing resources).

A stream goes from the start of a file to its end. For reading and writing anywhere in a file, such as a record in the middle of a database file, fs.open_file opens it as an io.File, whose File.read_at, File.write_at and File.seek take a position in bytes. Close it with defer File.close_quietly(f).

Standard input is a stream too. io.stdin is a Reader, so a function that takes a Reader reads standard input, a file or text alike. Reader.lines(r) is a reader’s lines as an Iter, read as the iterator runs, so unlike fs.lines it runs only once. io.lines() is the lines of standard input:

import std::io.{self, Reader}

fn count_lines(r: Reader) -> Result<Int, io.Error>
    lines = Reader.lines(r) |> Result.collect()?
    Ok(Iter.count(lines))
end

fn main()
    run = io.capture("one\ntwo\nthree\n", fn -> count_lines(io.stdin))
    io.print(run.value)
    io.print(count_lines(Reader.from_text("a\nb")))
end

Reader.from_text and Reader.from_bytes make a reader over data the program already holds, which is how a test feeds a function that takes a Reader. std::io also has readers that make their bytes as they are read.

Fine print

  • A read that waits, on standard input or a slow stream, is a safe point. A task cancelled while it waits stops there, and its defer closes the stream.
  • A call into Go that reads is not interrupted. The task stops once the call returns.
  • io.capture and io.replay reach tasks the captured function starts: what a task prints goes to the capture, not the terminal.
  • A Writer passed to Go is written through the same buffer as the program’s own writes, so the two stay in order.

Spec: Safe points. std::io has the stream functions.

fs.list returns a directory’s entries sorted by name, so a listing is the same on every computer. std::path puts paths together and takes them apart. It only reads the text, so it never fails:

// FILE: main.nomi
import
    std::fs
    std::io
    std::path
end

fn main() -> Result<Unit, io.Error>
    fs.create_dir("photos/2026/summer", parents: True)?
    fs.write_text(path.join("photos/2026", "notes.txt"), "trip\n")?

    entries = fs.list("photos")?
    Iter.each(entries, fn e -> io.print("${e.path} ${Debug.inspect(e.kind)}"))

    io.print(path.extension("photos/beach.jpg"))
    io.print(path.base("photos/2026/notes.txt"))
    io.print(path.clean("photos/2026/../alps.jpg"))
    io.print(fs.exists("photos/2026/notes.txt")?)
    Ok(Unit)
end

// FILE: photos/beach.jpg

// FILE: photos/alps.jpg

Paths use / on every operating system, Windows included. std::fs also removes, renames and copies files, reads their metadata and permissions, and makes and reads symlinks.

fs.walk goes through every entry under a directory, depth first and in name order: each directory, then what is in it. It does not follow symlinks, so it never leaves the tree. fs.glob returns the paths that match a pattern, where * matches within one name and ** any number of directories:

// FILE: main.nomi
import
    std::fs
    std::io
end

fn main() -> Result<Unit, io.Error>
    entries = Result.collect(fs.walk("notes"))?
    Iter.each(entries, fn e -> io.print("${e.path} ${Debug.inspect(e.kind)}"))

    io.print(fs.glob("notes/**/*.md")?)
    Ok(Unit)
end

// FILE: notes/todo.md
milk

// FILE: notes/2026/trip.md
alps

// FILE: notes/2026/budget.csv
food,40

Like fs.lines, a walk lists the directories again each time it runs. A directory it cannot list is an Err among the entries, and the walk goes on, so Result.collect stops at the first one and Iter.filter can skip them.

A path that comes from outside the program, such as a name in an archive or a request, can reach any file: ../../etc/passwd. fs.within(dir, fn -> ...) runs a function with every file call in it confined to dir. A relative path starts there, and a path that leads outside, by .. or through a symlink, is an error instead of a file:

// FILE: main.nomi
import
    std::fs
    std::io
end

fn page(name: String) -> Result<String, io.Error>
    fs.within("site", fn -> fs.read_text(name)) |> Result.map(String.trim)
end

fn main()
    io.print(page("index.txt"))
    io.print(page("../private.txt"))
end

// FILE: site/index.txt
home

// FILE: private.txt
secret

On the disk the operating system enforces the confinement, so a symlink changed while the function runs cannot lead out either.

A test should not depend on what is on the disk of the computer it runs on. std::fs::testing runs a function against a sandbox: a file system in memory, made from the files you give it. std::fs::testing.run returns the function’s result and every file afterwards:

import
    std::fs
    std::fs::testing.{self, Failure, Sandbox}
    std::io
end

fn sort_file(input: String, output: String) -> Result<Int, io.Error>
    lines = Result.collect(fs.lines(input))?
    sorted = Iter.sort(lines)
    fs.write_text(output, String.join(sorted, "\n") + "\n", mode: .ReplaceAtomically)?
    Ok(Iter.count(sorted))
end

test "sorts the lines into the output file"
    ran = testing.run(Sandbox{files: {"in.txt" => "pear\napple\n"}}, fn ->
        sort_file("in.txt", "out.txt")
    end)

    assert ran.value == Ok(2)
    assert testing.text(ran, "/work/out.txt") == Some("apple\npear\n")
    assert ran.open == []
end

test "a full disk leaves the old output in place"
    sandbox = Sandbox{
        files: {"in.txt" => "b\na\n", "out.txt" => "old\n"},
        failures: [
            Failure{path: "out.txt", operation: .Write, error: io.Error.NoSpace{path: "out.txt"}},
        ],
    }

    ran = testing.run(sandbox, fn -> sort_file("in.txt", "out.txt"))

    assert ran.value == Err(io.Error.NoSpace{path: "out.txt"})
    assert testing.text(ran, "/work/out.txt") == Some("old\n")
end

A sandbox’s working directory is /work, so ran.files names every file by its full path. A Failure makes an operation on a path fail with the error you pick, here the write that would fill the disk. ran.open lists the files still open when the function returned, so assert ran.open == [] catches a reader you forgot to close. Tasks the function starts use the same sandbox.

For code whose behavior depends on the real disk, fs.make_temp_dir makes a fresh directory, and defer fs.remove_all_quietly(dir) on the next line removes it and everything in it when the function or test ends.

A web page has no disk, so a program built with nomi build --web gets a file system in memory, as the examples on this page do. The page gives it its files when it runs it, and gets every file back when it ends, as Building & Shipping shows.

JSON & Dynamic is next. It reads data whose shape comes from outside the program.