Skip to the content.

file

import "file" as file

Files, directories and the standard streams.

Opening files: open(path, mode="r")

import "file" expose open

let f = open("notes.txt", "w")
f.write("first line\n")
f.close()

f = open("notes.txt")
term.log(f.read())
f.close()

The mode is a base mode, optionally followed by modifiers:

Base Meaning
r read (the file must exist)
w write, creating or truncating the file
a append, creating the file if needed
x create a new file, failing if it already exists
Modifier Meaning
b binary: read and write buffers instead of strings
+ open for both reading and writing

For example: "rb", "w+", "ab". An invalid mode throws file.FileError.

File methods

Method Description
.read(size?) read up to size bytes, or the whole file if size is omitted
.write(data) write a string (text mode) or buffer (binary mode); returns the number of bytes written
.seek(offset, whence=0) move the position: whence is 0 (from the start), 1 (from the current position) or 2 (from the end)
.tell() the current position
.flush() flush buffered writes
.size() the file’s size in bytes
.close() close the file (closing twice is harmless)

Files also have .mode and .closed attributes.

In text mode, read returns a string, and reading at the end of the file returns "". In binary mode, it returns a buffer.

Reads start at the current position, so .read() after .read(5) returns the rest of the file:

import "file" as file

let p = file.temp_file("demo-*.txt")
let f = file.open(p, "w")
f.write("hello world")
f.close()

f = file.open(p)
term.log(f.read(6))   # hello
term.log(f.read())    # world
f.close()
file.delete_file(p)

Standard streams

file.stdin, file.stdout, file.stderr and file.stdnull are already-open File objects in binary mode, so they read and write buffers:

import "file" as file

file.stdout.write(buffer.from_string("to stdout\n"))
file.stderr.write(buffer.from_string("to stderr\n"))

file.stdin.read() reads all of standard input as a buffer, which is useful when a program is used in a pipeline:

let input = file.stdin.read().to_string()

Files and directories

Function Description
file.is_file(path) whether path is an existing file
file.is_directory(path) whether path is an existing directory
file.get_metadata(path) {size, mtime, mtime_ns, device, inode}
file.mkdir(path) create a directory
file.makedirs(path) create a directory and any missing parents; no error if it already exists
file.tree_dir(path) array of every file and directory under path (recursive, absolute paths)
file.copy_file(source, destination) copy a file
file.copy_dir(source, destination) copy a directory recursively
file.move(source, destination) move or rename a file or directory
file.move_contents(source, destination) move everything inside source into destination
file.delete_file(path) delete a file
file.delete_dir(path) delete a directory and everything in it
file.temp_file(pattern) create an empty temporary file and return its path
file.temp_dir(pattern) create a temporary directory and return its path

The temporary file functions replace the * in pattern with random characters:

import "file" as file
import "path" as path

let dir = file.temp_dir("demo-*")
let target = path.join(dir, "a", "b")
file.makedirs(target)

let f = file.open(path.join(target, "hello.txt"), "w")
f.write("hi")
f.close()

for (entry in file.tree_dir(dir)) term.log(path.relative_to(entry, dir))
file.delete_dir(dir)

Exceptions

The file module’s exceptions are available as file.<name>:

Catch a specific error, or FileError for any of them:

import "file" as file

try do
    file.open("/does/not/exist")
catch (file.FileNotFoundError as e) do
    term.log("not found:", e.message)

try file.open("/does/not/exist")
catch (FileError as e) term.log(type(e).__name__)   # FileNotFoundError

Next