Docs / Standard library

Files

Read UTF-8 files all at once or stream their lines with automatic loop cleanup.

Browse documentation
On this page

File operations read UTF-8 text. Choose a whole-file operation when the full content is needed, or stream lines when processing them one by one.

Whole-file reads

Signature Result and behavior
file.read(String) -> Result<String, FileError> On success, the file contents.

The operation returns a result. Use postfix try to propagate a failure or catch to recover from one:

let content = file.read("examples/text-stats-sample.txt") try
print(text.word-count(content))

Run that program from the repository root so the sample path resolves.

Streaming reads

Signature Behavior
file.open(String) -> Result<File, FileError> On success, open the file.
file.read-line(File) -> Result<String, FileError> On success, return the next line. End of file is a failure.
file.close(File) -> Unit Close the file. Calling it more than once is safe.

These signatures show built-in return values. User words can omit a return annotation when the body determines one concrete success type; when a try can escape, the checker infers the word’s effective Result<T, E> signature. Explicit return and Result signatures remain supported; see results and error handling.

An open File is a resource: it cannot be printed or compared. Close a file after you finish reading. Reading from a closed file fails.

For a line-at-a-time loop, use for line in file.stream(path). The loop streams chomped lines and always closes the file when it ends, including when its body fails:

for line in file.stream("examples/text-stats-sample.txt")
    print(text.upper(line))

The file.stream form is available only as the source of a for loop.

Writing a file

Signature Result and behavior
file.write(String, String, Bool = false) -> Result<Unit, FileError> On success, Unit: the contents are written to the path. The optional third argument appends instead of truncating.

file.write(contents, path, append) takes the contents first, then the path. Omitting append (or passing false) creates the file or truncates an existing one; append = true appends and creates the file if it is missing. The trailing append argument is a built-in constant default: calls may omit it, and a partial such as file.write(_, "out.txt") keeps it deferred, like a user-word default.

No parent directory is created, and the write is not atomic — a failure can leave a partial or truncated file. The open, write, and close happen inside the operation, so no writable file resource escapes. A created file uses mode 0644 subject to the process umask, and the write follows symlinks.

let saved = file.write(report, "/") catch problem
    print("Save failed: " + error.code(problem))

Inspecting paths

Signature Result and behavior
file.list(String) -> Result<List<String>, FileError> On success, the folder’s entry names.
file.exists(String) -> Bool true when the path exists; false when it does not.
file.size(String) -> Result<Int, FileError> On success, the size in bytes.
file.free-space(String) -> Result<Int, FileError> On success, the bytes available on the volume containing the path.

file.list(folder) lists one level: bare entry names, not paths, in sorted order, dot entries included — filtering them is list.filter work — as a fresh list. A folder with more than one million entries fails collection-limit inside the result before the list is built.

file.exists(path) is a plain Bool. A missing path is the answer false, not a failure; any other stat failure (a parent without permission, an invalid path) is a runtime diagnostic. Applying try or catch to the call selects the checked Result<Bool, FileError> form. The checked form exists only on the direct call: a deferred partial such as let f = file.exists _ locks the plain form, and f(path) try is rejected.

file.size(path) returns a regular file’s size in bytes; a directory reports 0, and nothing is summed recursively. file.free-space(path) accepts any existing path, file or folder, and reports the bytes available to the process on the volume containing it; it works on Unix and Windows, and other platforms fail file-free-space inside the result.

let names = file.list("examples") try
print(names)

A listing that cannot be read fails file-list; a stat failure behind file.exists fails file-exists; size and free-space failures use file-size and file-free-space. Each names the path and the operating system’s reason.

Composing and decomposing paths

Signature Result and behavior
file.join(String, String) -> String The two paths joined with the native separator and cleaned.
file.base(String) -> String The final path element.
file.extension(String) -> String The final element’s final-dot suffix, dot included.
file.directory-of(String) -> String The path without its final element.

These four words are pure lexical operations: no file is read, written, or checked, and every one returns a plain String — never a Result — so no try or catch applies. Separators follow the host platform.

file.join(base, child) concatenates and cleans: file.join("a/b", "../c") is "a/c", and an empty side collapses to the other. An absolute child replaces the base — file.join("a/b", "/c") is "/c" — so an untrusted absolute component never nests under the base.

file.base(path) returns the final element with trailing separators removed; the root is its own base ("/"), and the empty path yields ".". file.extension(path) returns the suffix from the final element’s final dot, including the dot: ".gz" for report.tar.gz, ".bashrc" for the dotfile .bashrc, and empty when there is none. file.directory-of(path) drops the final element; a path ending in a separator has no final element to drop ("/a/b/" yields "/a/b"), the root is its own directory, and a path with nothing to drop yields ".".

.. passes through or cleans lexically — file.join resolves it during the clean, while file.base and file.directory-of treat it as an ordinary element. None of this is a containment guarantee.

let invoice = file.join("/tmp/zhex-out", "june/invoices.csv")
print(file.directory-of(invoice))
print(file.base(invoice))
print(file.extension(invoice))

See the paths example, which composes report paths and decomposes them again without touching the disk.

Creating, removing, and moving

Signature Result and behavior
file.make-folder(String, Bool = false) -> Result<Unit, FileError> On success, Unit: the folder exists. The optional second argument creates missing ancestors.
file.delete(String) -> Result<Unit, FileError> On success, Unit: a file or an empty folder was removed.
file.delete-folder(String, Bool = false) -> Result<Unit, FileError> On success, Unit: an empty folder was removed; the optional second argument removes the whole tree.
file.move(String, String, Bool = false) -> Result<Unit, FileError> On success, Unit: the source was renamed to the target, file or folder. The optional third argument replaces an existing target file.

file.make-folder(path, parents) creates one level and fails on an existing target; parents = true creates every missing ancestor and tolerates a folder that already exists. The trailing mode arguments are built-in constant defaults, like file.write’s append: calls may omit them, and partials keep them deferred.

file.delete(path) removes a file or an empty folder and fails on a nonempty folder — the safety default. file.delete-folder(path, recursive) removes an empty folder by default; recursive = true removes the whole tree best-effort, so part of the tree may already be gone when the first failure is reported and earlier effects stand. Deleting a tree is always a deliberate, visible recursive = true at the call site.

file.move(source, target, overwrite) is rename-based, so it moves folders as well as files. With overwrite omitted or false it fails when the target exists; with overwrite = true it replaces an existing file only — an existing folder target fails under both values, and a cross-device move fails with the platform’s error rather than copying. The check of the target and the rename have an unavoidable check-then-act window: a target that appears in between is left to the rename itself.

file.make-folder("out/reports", true) try
file.move("draft.txt", "out/reports/report.txt") try

Failures use file-make-folder, file-delete, file-delete-folder, and file-move, naming the path or paths and the operating system’s reason. Failures leave earlier effects in place — no transaction promise.

See the file-work example, which builds a work folder, inspects it, and removes the whole tree.

Lines and failures

Line reading removes one trailing line feed (LF) and removes an immediately preceding carriage return (CR) with it. A bare final CR without LF is retained. A final nonempty line without a newline is still read. An empty file produces no lines in a loop.

Opening or reading can fail, and invalid UTF-8 is rejected. Whole-file open failures use file-open; streaming read failures and end-of-file use file-read; invalid text uses file-utf8. A write that cannot open, write, or close the path fails file-write, naming the path, the failing phase, and the operating system’s reason; a failed write may leave a partial or truncated file, and a missing parent directory is never created. Add try to propagate a failure or catch to handle it locally. See results and error handling.

See the text-stats example, which counts a whole file or streams its lines depending on the supplied arguments.