Standard Library: std.fs
● Intermediate5 min
Every type, method and function of std.fs: what the spec lists, then each declaration in its source, with its examples and the line that declares it.
Spec 14.3 · learn it in Files.
A declaration below shows what a program writes against: a type's fields, a function's parameters, what it gives, its contracts (require, ensure) and its examples. kavach test runs every example, so each one is true of the code.
What the spec lists
| Function | Gives |
|---|---|
fs.read_text(path) -> String ! FsError | The file's text (it must be UTF-8) |
fs.write_text(path, text) ! FsError | Replaces the file atomically: the new text goes to a temporary file that is then renamed, so a crash never leaves half a file |
fs.append_text(path, text) ! FsError | Adds to the end, creating the file if needed |
fs.read_bytes(path) -> Bytes ! FsError | The file's contents, any bytes (2.13) |
fs.write_bytes(path, data) ! FsError | Replaces the file atomically, like write_text |
fs.write_durable(path, data) ! FsError | Replaces the file atomically and forces it to the disk (fsync on the file, then on its folder) before returning: after it, a power cut keeps the new contents. Storage engines build on this |
fs.lines(path) ! FsError | The file's lines, read as a for loop goes, without their line ending (\n or \r\n) |
fs.chunks(path, size) ! FsError | The file's bytes in Bytes pieces of size (the last may be shorter), read as a for loop goes |
fs.exists(path) -> Bool | Whether a file or folder is there |
fs.list(folder) -> [String] ! FsError | The names in a folder, sorted |
fs.remove(path) ! FsError | Deletes a file or an empty folder |
fs.create_dir(path) ! FsError | Creates a folder and any missing parents |
fs.info(path) -> FileInfo ! FsError | What is at path: its kind, size, last change and permissions (below). A link is described itself, not what it points to |
fs.set_read_only(path, read_only) ! FsError | Makes a file read-only, or writable again, on every system |
fs.set_permissions(path, mode) ! FsError | Sets the Unix permission bits, written in octal: 0o644, 0o755. Windows keeps only whether the owner may write: without that bit the file is read-only |
fs.rename(from, to) ! FsError | Moves or renames a file or folder; a file already at to is replaced |
fs.copy(from, to) ! FsError | Copies a file, with its permissions; a file already at to is replaced |
fs.remove_all(path) ! FsError | Deletes a folder and everything in it, or a file |
fs.symlink(target, link) ! FsError | Makes a symbolic link at link that points to target, kept as written (a relative target is relative to the link's folder). With uses Fs("…") (8.1) both must be inside its folders. Windows allows it only in Developer Mode or with administrator rights; otherwise it fails with Denied |
| Function or method | Gives |
|---|---|
fs.create_writer(path) -> FileWriter ! FsError | A new, empty file at path to write; one already there is emptied |
w.write(data) ! FsError | Adds the Bytes data at the file's end. Writes are gathered in memory and go to the file 64 KB at a time |
w.write_text(text) ! FsError | The same for text, as UTF-8 |
w.finish(sync: false) -> Int ! FsError | Writes what is gathered, closes the file, and gives how many bytes it holds. With sync: true it also forces them to the disk (fsync), so a rename after it can't leave a short file after a crash |
std.fs · fs.kav
use std.fs: 4 types and 2 functions. stdlib/fs/fs.kav
FsError type
Why a file operation failed.
pub type FsError = NotFound(path: String) | Denied(path: String) | Failed(path: String, reason: String)FileKind type
What kind of thing a path names.
pub type FileKind = File | Folder | LinkFileInfo type
What is at a path (fs.info).
pub type FileInfo {
pub kind: FileKind
/// In bytes; 0 for a folder.
pub size: Int
/// When it last changed: a moment, in milliseconds since 1970 (14.4).
pub modified_ms: Int
/// Whether the owner may not write it.
pub read_only: Bool
/// The Unix permission bits, such as `0o644`.
pub permissions: Int
}info function
What is at path: its kind, size, last change and permissions. A link is described itself, not what it points to.
pub fn info(path: String) -> FileInfo ! FsError uses Fs.readFileWriter type
A file being written piece by piece (fs.create_writer, spec 14.3). Let go before finish, its file is deleted.
pub type FileWriter: Drop {
id: Int
}write method
Adds data at the end of the file.
pub fn write(self, data: Bytes) ! FsError uses Fs.writewrite_text method
Adds text at the end of the file, as UTF-8.
pub fn write_text(self, text: String) ! FsError uses Fs.writefinish method
Writes what is gathered, closes the file, and gives how many bytes it holds; with sync, they are on the disk before it returns.
pub fn finish(self, sync: Bool = false) -> Int ! FsError uses Fs.writecreate_writer function
A new, empty file at path (one there is emptied), written piece by piece as its data comes.
pub fn create_writer(path: String) -> FileWriter ! FsError uses Fs.write