Skip to content
Weaverv0.5.0

Files and paths

Module weaver.fs: its API, wv doc weaver.fs.

Three modules share the work: weaver.fs does what the system does to a file or a directory by its path, weaver.io reads and writes an open file piece by piece, and weaver.path builds the paths both take. Every function that touches the disk returns ! IoError, whose message names the path and the reason.

import weaver.{Fs}
val text = Fs.readText("notes.txt")! // InvalidUtf8 if it is not text
Fs.writeText("notes.txt", text + "one more\n")!
val data = Fs.read("image.png")! // Bytes

Fs.write and Fs.writeText replace the file. Reading a whole file is right up to what fits easily in memory; past that, read it piece by piece.

A Path is a value, nothing on disk: Path.from("a").join("b.txt"), parent(), an optional, fileName(), extension(). A function of weaver.fs takes a Path or a String alike, through AsPath.

val dir = Env.tempDir().join("report")
val out = dir.join("2025.txt")
Fs.createDirAll(out.parent() ?? dir)!

join with an absolute path gives that path, as a shell would.

  • Fs.exists(p), Fs.metadata(p): its kind, isFile(), isDir(), its size(), mode, modified; symlinkMetadata for the link itself.
  • Fs.createDir, createDirAll, createTempDir("prefix-"); readDir, the entries of a directory; walk(root, (path, metadata) => …), a tree, the function returning false to skip a directory.
  • Fs.copy, rename, remove for a file, removeDir for an empty directory, removeAll for a tree; setMode, setTimes, symlink.
  • Errors are matched by variant, Fs.metadata(p) is Err(NotFound(_)), or by kind, e.kind() == .denied.

Dir.open(path) holds a directory open and works below it: createFile, openFile, openDir, entries, remove. Names are resolved inside it, however the path above it changes meanwhile.

File.create(path) opens for writing, replacing what was there; File.createNew refuses a file that exists; File.open(path) opens for reading. A file is a resource: using closes it at the end of its block, and an error closing it goes up.

import weaver.io.{File, Buffered}
{
using out = Buffered.new(File.create("log.txt")!)
out.writeLine("started")!
out.write("raw bytes".bytes())!
} // flushed and closed here
using input = Buffered.new(File.open("log.txt")!)
while input.readLine(b'\n')! is Some(line) { handle(line) }
  • Buffered gathers small reads and writes into large ones; without it, each is a system call.
  • readLine(b'\n') gives a line with its separator, None at the end; readBlock lends the complete lines a buffer holds, without copying them.
  • The Reader and Writer contracts are what readers and writers share, files, sockets, standard input, BytesReader over bytes in memory: read(&buf) returns how many bytes came, 0 at the end; pipeTo(writer) copies one into another.
  • File.anonymous(dir) is a temporary file with no name, gone when closed.

print and printErr write a line. Standard input is read through Stdin.lock(), a buffered reader:

val stdin = mut Stdin.lock()
while stdin.readLine(b'\n')! is Some(line) { handle(line) }

Stdout.lock() writes without a line per call; isTerminal() says whether a person is reading.