Files

Read a bounded UTF-8 file into a Str.

The whole file is copied into the string, so this is capped well below what read_bytes! will read: at most 64 kibibytes, and a file past that is TooLarge rather than truncated. One that is not valid UTF-8 is NotUtf8 rather than an invalid Str.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.

Read a bounded file as ordinary Roc bytes.

At most 16 mebibytes, and a file past that is TooLarge. The ceiling is far above read_text!'s because nothing is copied: the buffer the read filled is the buffer Roc gets.

That is also why there is a second bound. The delivered list owns host-backed storage through Roc ARC, and at most 32 such allocations are live at once; a read made while all 32 are held answers Busy without touching the disk. Retaining a sublist retains the complete source allocation and so holds a slot, which List.release_excess_capacity releases by copying out the part worth keeping.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.

List one directory without recursively walking its children.

Entry order is the filesystem's observed order and is not sorted. Recursion is the app's to drive: only the app knows which subtrees are worth descending into, and a host-side walk would be one unbounded wait.

A listing is bounded at 8192 entries and at one mebibyte of encoded names, whichever binds first; a directory past either is TooLarge rather than a partial listing. It is delivered through the same 32 file-byte slots a byte read uses, so it can answer Busy for the same reason.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.

What one path is, how big it is, and when it last changed.

Symbolic links are followed, so a link to a file is File and a link to nothing is NotFound. That differs from list!, which reports the kind the directory itself records and so calls a symbolic link Other; metadata! answers about the thing at the end of the path, which is what an app deciding whether to read it wants to know.

Polling modified is how an app hot-reloads a shader, a level, or a dataset it did not write. Do it inside a task, and sleep between stats, so the watching costs a parked task rather than a stat every frame:

watch! : Str, Time.Timestamp => Msg
watch! = |path, seen| {
    var $outcome = Unchanged
    while $outcome == Unchanged {
        Task.sleep!(250)
        $outcome = match Files.metadata!(path) {
            Ok(meta) if meta.modified != seen => Modified(meta.modified)
            Ok(_) => Unchanged
            Err(NotFound) => Unchanged
            Err(other) => Stopped(other)
        }
    }
    match $outcome {
        Modified(at) => Changed(path, at)
        Stopped(err) => WatchFailed(err)
        Unchanged => crash("watch!: the loop only ends once the path changed or the stat failed")
    }
}

The loop carries a sentinel tag rather than the message itself, so its while condition can compare it, and the match after the loop turns that sentinel into the one message the task owes.

A loop rather than a recursive call, because a task runs on a fixed-size coroutine stack. NotFound keeps waiting rather than giving up: an editor saving a file often replaces it, so the path can be missing for a moment. update! spawns the watcher again when it handles Changed, and each live watcher holds one of the host's thirty-two task slots for as long as it watches.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.

Replace a file's contents with a Str, creating it if it is not there.

The write replaces the whole file: there is no append, and no partial write is reported as success. Missing parent directories are created, the same as for every file the host writes itself, so an app's first write_text!("saves/slot1.json", ...) does not need a separate step to make saves/.

The path is used as the app gave it, resolved against the process working directory, exactly as read_text! resolves one. Files is not sandboxed in either direction: an app that can read /etc/hosts can write /tmp/out.txt. The one output root this platform enforces belongs to Capture, whose paths are computed by recording machinery rather than written out by the app, and it confines captures only.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.

update! = |model, input| {
    if input.devices.key_pressed(KeyS) {
        Task.spawn!(
            input,
            || match Files.write_text!("saves/slot1.json", encode(model)) {
                Ok({}) => Saved
                Err(err) => SaveFailed(err)
            },
        )
    }
    Ok(model)
}

Replace a file's contents with ordinary Roc bytes.

The same path rules, the same whole-file replacement, and the same parent-directory creation as write_text!; only the payload differs. Nothing about the bytes is inspected, so this is the call for a PNG, a save blob, or anything else that is not text.

Legal in init!, where it blocks startup, and in tasks, where it parks the task; refused in update! and render!.