FS

Module fs

import fs

A filesystem you pass around rather than reach for.

A filesystem in Zirric is a value, not a global. FileSystem carries one function per operation, and every module function here takes it as its first argument — so fs.readFile(fsys, "a.txt") and fsys.readFile("a.txt") do the same thing, and the first reads better in a chain.

Because it is a value, it can be swapped. memory() returns an empty in-memory filesystem that touches no disk and needs no cleaning up; os.os.fs returns the real one. Code that accepts a FileSystem — or requires HasFileSystem — works with either.

Everything that can fail returns a prelude.Result rather than stopping the program.

Dependencies

• bytes
  • ranges
• io
• paths
• results

---

Contents

• Data — Entry, File, FileSystem
• Attributes — HasFileSystem
• Functions — cd, close, copy, create, exists, glob, list, memory, mkdirAll, move, open, readFile, readString, remove, root, walk, withFile, writeFile, writeString

---

Data

Entry

`fs/fs.zirr:36`

data Entry {
	name: String
	isDir: Bool
	size: Int
}

One entry of a directory listing.

Fields

---

File

`fs/fs.zirr:29`

data File {
	readFrom: fn(Int) -> Binary
	writeTo: fn(Binary) -> Int
	closeWith: fn() -> Result
}

An open file. It is both a reader and a writer, and must be closed.

Fields

---

FileSystem

`fs/fs.zirr:12`

data FileSystem {
	readFile: fn(String) -> Result
	writeFile: fn(String, Binary) -> Result
	open: fn(String) -> Result
	create: fn(String) -> Result
	exists: fn(String) -> Bool
	remove: fn(String) -> Result
	move: fn(String, String) -> Result
	list: fn(String) -> Result
	mkdirAll: fn(String) -> Result
	cd: fn(String) -> Result
	root: fn() -> String
}

A filesystem. Every operation that can fail returns a Result rather than stopping the program.
Each field has a matching module function taking the filesystem first, which is usually the nicer way to call it.

Fields

---

Attributes

HasFileSystem

`fs/fs.zirr:6`

attr HasFileSystem {
	fileSystem(self: @HasFileSystem) -> FileSystem
}

Provides a filesystem, so that code can require one instead of reaching for os directly.

Fields

---

Functions

cd

`fs/operations.zirr:52`

fn cd(fsys: FileSystem, path: String) -> Result

Returns a filesystem rooted at path, which is how a confined view of this one is handed out.

---

close

`fs/helpers.zirr:8`

fn close(file: File) -> Result

Releases the file. Writes are not guaranteed to have reached the filesystem until this returns.

---

copy

`fs/helpers.zirr:96`

fn copy(source: FileSystem, sourcePath: String, target: FileSystem, targetPath: String) -> Result

Copies one file between filesystems, which may be the same one.

---

create

`fs/operations.zirr:22`

fn create(fsys: FileSystem, path: String) -> Result

Creates path for writing, replacing it if it exists. The file must be closed.

---

exists

`fs/operations.zirr:27`

fn exists(fsys: FileSystem, path: String) -> Bool

Returns whether path exists.

---

glob

`fs/helpers.zirr:72`

fn glob(fsys: FileSystem, base: String, pattern: String) -> Result

Every file path under base matching pattern, where * matches within one path element.

---

list

`fs/operations.zirr:42`

fn list(fsys: FileSystem, path: String) -> Result

Returns the entries of the directory at path.

---

memory

`fs/fs.zirr:51`

extern fn memory() -> FileSystem

An empty in-memory filesystem, which touches no disk and so needs no cleaning up.

---

mkdirAll

`fs/operations.zirr:47`

fn mkdirAll(fsys: FileSystem, path: String) -> Result

Creates path and any missing parent directories.

---

move

`fs/operations.zirr:37`

fn move(fsys: FileSystem, from: String, to: String) -> Result

Moves the file at from to to.

---

open

`fs/operations.zirr:17`

fn open(fsys: FileSystem, path: String) -> Result

Opens path for reading. The file must be closed.

---

readFile

`fs/operations.zirr:7`

fn readFile(fsys: FileSystem, path: String) -> Result

Returns the contents of path.

---

readString

`fs/helpers.zirr:33`

fn readString(fsys: FileSystem, path: String) -> Result

Returns the contents of path decoded as a String.

---

remove

`fs/operations.zirr:32`

fn remove(fsys: FileSystem, path: String) -> Result

Removes path.

---

root

`fs/operations.zirr:57`

fn root(fsys: FileSystem) -> String

Returns the path this filesystem is rooted at.

---

walk

`fs/helpers.zirr:43`

fn walk(fsys: FileSystem, path: String) -> Result

Every file path under path, in no particular order, descending into directories.

---

withFile

`fs/helpers.zirr:14`

fn withFile(opened: Result, body: fn(File) -> Any) -> Result

Runs body with an open file and closes it afterwards, whether or not body succeeded.
This is the safe way to use open and create, which otherwise leak the handle when something goes wrong.

---

writeFile

`fs/operations.zirr:12`

fn writeFile(fsys: FileSystem, path: String, content: Binary) -> Result

Writes content to path, replacing it if it exists, and returns the number of bytes written.

---

writeString

`fs/helpers.zirr:38`

fn writeString(fsys: FileSystem, path: String, content: String) -> Result

Writes content to path, encoded as UTF-8.