Files & I/O

All file access is gated by the file capability (file.read / file.write for least-privilege). Writes are atomic (temp file + rename).

-- Doc example: files & I/O. Needs file capability (deny-by-default).
intent: "doc example: files and I/O"
require file("_doctest_io.txt")

write_file("_doctest_io.txt", "hi from the io demo")
print("read back → " + read_file("_doctest_io.txt"))

test "write then read round-trips (atomic write)"
    write_file("_doctest_io.txt", "hello\nworld")
    assert_eq(read_file("_doctest_io.txt"), "hello\nworld")
    assert(file_exists("_doctest_io.txt"))

Reading

read_file(path)                 -- whole file as text
read_file(path, 1, 100)         -- a line range: lines 1–100 (1-based, EOLs preserved)
read_file(path, 500)            -- from line 500 to EOF
read_file_bytes(path)           -- byte-exact, for binary

Writing & editing

write_file(path, text)          -- atomic overwrite
append_file(path, text)         -- append
edit_file(path, old, new)       -- exact-string replace (old must be unique; replace_all? for all)

Navigating & searching

file_exists(path)               -- bool
file_info(path)                 -- {name, is_dir, size, ...}
list_dir(path)                  -- list of {name, is_dir, size}
grep(target, pattern, opts?)    -- {matches: [{file, line, col, text}], truncated} — streams per line

Path scopes are faithful — a .. escape outside the declared scope is denied. See Capabilities.