Module fs 

File helpers the tools share: an atomic write, capped text reads, JSON files, and the FileChange a tool that writes publishes. The reads and the path rules here are this machine’s (Local); a tool reads through its Workspace.

Structs

Prefix

The start of a file read by read_prefix.

Functions

file_change

What turning before into after did to the file at path (None: there was no file before, or there is none after): its lines added and removed, counted by a line diff, that diff as hunks with 3 lines of context, the text before, and the FileState of each text: the fact a tool that writes files publishes (FilesChanged).

io_error

A model-visible error for an I/O failure on path.

place

path resolved against base, as a file tool opens it; with confine, refused before any I/O when it lies outside base (None: the working directory). The rule the file tools follow, for code that must decide as they would, such as a preview of a write.

read_json

The JSON file at path as a T, or None when it is missing or is not one.

read_prefix

Reads at most cap bytes of the regular file at path on this machine as a Prefix.

read_text

Reads path as text after checking, without opening it, that it is a regular file of at most MAX_FILE_BYTES: opening a FIFO or a device can block forever. Local’s read_text.

resolve

path as the file tools open it: made absolute against base (None: this process’s working directory), with every symbolic link of its longest existing part followed (the file’s own too, when it exists) and .. folded. Two spellings of one file resolve alike, so this is how the facts the tools publish (FilesRead, FileChange::path) and their footprints name files. A path that cannot be made absolute (no working directory) stays relative.

write_atomic

Replaces the file at path with contents in one step, creating its directory: a temporary file beside it is written, synced and renamed over it, so a crash or a full disk never leaves it half written. A symlink’s target is replaced and the link kept, and a dangling link’s target is created; an existing file keeps its permissions. A read-only file is refused, as is anything but a regular file, because opening a FIFO or a device for writing can block forever.

write_json

Replaces the file at path with value as pretty JSON, by write_atomic.