Filesystem Paths

This example uses the path package to join a directory and filename, then extract the filename and extension. It also creates a raw Unix path to show why filesystem paths cannot always be represented as Unicode strings.

import path.Path

config : Path
config = "config"

settings = config.join("settings.json")

expect settings.to_str() == Ok("config/settings.json")
expect settings.filename()?.to_str() == Ok("settings.json")
expect settings.ext()?.to_str() == Ok("json")

raw = Path.unix_bytes([0xff, 0x61])
expect raw.to_str().is_err()
expect raw.to_raw() == UnixBytes([0xff, 0x61])

The raw path contains a byte that is not valid UTF-8, so to_str returns an error. to_raw preserves the original representation, which is what a platform needs when passing the path to the operating system. The package also supports Windows paths stored as UTF-16 code units.

For human-readable output, display can replace invalid text. That makes it useful for showing a path, but unsuitable for reconstructing the original path later.

These operations only manipulate path values; they do not access the filesystem. The app header selects the package release used by the example:

app [] {
	path: "https://github.com/roc-lang/path/releases/download/4.0.0/7YfABZPwJAXtLBY2vm8FqMyGAtNxncCJ65HdNKHFGNnE.tar.zst",
	roc: "nightly-2026-10-29-a0a9fc2",
}

Output

Run this from the directory that has main.roc in it:

$ roc test main.roc

All (5) tests passed in 31.7 ms.

Validated with Roc nightly-2026-10-29-a0a9fc2.