std/fs

The built-ins cover the rest: reading and writing whole files as text or bytes, appending to them, and writing them atomically (read_bytes, append_text, write_atomic, ...), and exists, is_dir, make_dir, list_dir, delete_file, rename_file, current_dir, change_dir, temp_dir, and temp_file. See program input and output.

Open files

open_file(path, mode) opens a file to read and write it in parts, and gives a File, which with closes:

import "std/fs"

with log = open_file("events.log", "a")? do
    file_write_text(log, "started\n")?
end

File input = open_file("data.bin", "r")?
file_seek(input, 16, SeekFrom.START)?
bytes header = file_read(input, 8)?
close_file(input)?

Each returns a Result; the ones with nothing else to give return OK(true). Files are binary: nothing is changed in what is read or written. Reading and writing can follow each other on a file opened for both. An exclusive lock is for one writer; shared locks let several readers hold the file at once. A File is a Reader and a Writer, so it works with functions written for any source or destination of bytes. Using a closed file stops the program.

Information, permissions, and links

file_info(path) tells what a file is, as a FileInfo:

A link is described itself rather than followed. These change files and links:

Each returns a Result whose error says what the system reported.

Directories

Each returns a Result. The user's directories follow each system: ~/.config, ~/.local/share, and ~/.cache on Linux and the BSDs (or the XDG_ variables that move them, and user-dirs.dirs for the documents and the desktop), ~/Library/Application Support and ~/Library/Caches on macOS, and the roaming and local AppData folders on Windows.

walk_dir(root) goes through everything below a directory one entry at a time, reading each directory only when it gets there, so it can stop early on a large tree. Each directory's entries come in order of name, and those of a subdirectory right after it:

Walker w = walk_dir("src")
w.max_depth = 3                 // 1 is the entries of src alone; -1, the default, has no limit
while true do
    match next_entry(w)? do
        when SOME(entry) then
            if entry.name == "build" then
                skip_dir(w)     // leaves out what is inside
            else if path_ext(entry.name) == ".cz" then
                print(entry.path, entry.info.size)
            end
        when NONE then
            break
    end
end

A link to a directory is given as a link and not gone into, unless follow_links is set; then each directory is gone into once, so a link that leads back up does not loop.

Large files and the trash

map_file(path) gives the bytes of a file through the system's memory map of it instead of reading it all: the system brings in the parts a program looks at, so a program can take slices of a file of gigabytes cheaply. The map stays until the program ends, and the file must not change while it is mapped.

trash(path) moves a file or a directory to the system's trash, from where the user can bring it back: the Recycle Bin on Windows, the Trash on macOS, and on Linux and the BSDs the trash of the freedesktop.org specification that file managers share. There, a file on another file system than the home directory cannot go to the trash, which is an ERROR of kind "cross_device". Both return a Result.