fs

Filesystem operations: reading, writing, metadata, directories, and path utilities.

Import

import fs

Reading files

fs.read(path: str) -> str

Read the entire file as a string.

fs.read_bytes(path: str) -> [int]

Read the entire file as a byte array.

fs.read_lines(path: str) -> [str]

Read the file and split on newlines, returning an array of lines.

fs.read_stream(path: str) -> reader

Open a streaming reader. The returned object has .read(n) and .close() methods.

Writing files

fs.write(path: str, str: str)

Write a string to the file, replacing any existing content.

fs.write_bytes(path: str, arr: [int])

Write a byte array to the file.

fs.write_stream(path: str) -> writer

Open a streaming writer with .write(s) and .close() methods.

fs.append(path: str, str: str)

Append a string to the file.

Metadata

fs.exists(path: str) -> bool

True if the path exists.

fs.is_file(path: str) -> bool

True if path is a regular file.

fs.is_dir(path: str) -> bool

True if path is a directory.

fs.size(path: str) -> int

File size in bytes.

fs.stat(path: str) -> map

Map with keys: size, mtime, is_dir, is_file, mode.

File manipulation

fs.remove(path: str)

Delete a file.

fs.rename(from: str, to: str)

Move or rename a file.

fs.copy(from: str, to: str)

Copy a file.

fs.chmod(path: str, mode: int)

Set POSIX permission bits.

fs.symlink(target: str, link: str)

Create a symbolic link.

fs.readlink(path: str) -> str

Read the target of a symbolic link. fs.realpath(path) resolves all symlinks to an absolute path.

Directories

fs.mkdir(path: str)

Create a directory. fs.mkdir_p(path) creates parents if needed.

fs.rmdir(path: str)

Remove an empty directory.

fs.list(path: str) -> [str]

List direct children of a directory. Also available as fs.ls(path).

fs.walk(path: str) -> iter

Recursive iterator yielding maps with keys path, is_dir, and metadata.

fs.glob(pat: str) -> [str]

Expand a glob pattern relative to the current directory.

fs.watch(path: str, fn: (event) -> void)

Run fn when the file or directory at path changes.

fs.temp_dir() -> str

Return a platform temp directory path. fs.temp_file(prefix?) creates a temp file.

Path utilities

fs.join(a: str, b: str, ...) -> str

Join path components with the platform separator.

fs.basename(path: str) -> str

Filename component.

fs.dirname(path: str) -> str

Directory component.

fs.ext(path: str) -> str

File extension including the dot.

fs.abs(path: str) -> str

Absolute path from the current directory.

Examples

import fs

fs.write("/tmp/hi.txt", "hello")
let s = fs.read("/tmp/hi.txt")
println(s)  -- hello

for line in fs.read_lines("/etc/hosts") {
    println(line)
}

let info = fs.stat("/tmp/hi.txt")
println(info["size"])    -- 5

fs.mkdir_p("/tmp/a/b/c")
for entry in fs.walk("/tmp/a") {
    println(entry["path"])
}

-- streaming write
let w = fs.write_stream("/tmp/big.txt")
for i in 0..1000 {
    w.write("line {i}\n")
}
w.close()