Files and directories

pub fn path_sep() -> character

The separator of a loft path: '/' on every platform. A path a program hands loft may also use '\' (it reads as '/'), and every path loft hands back uses '/'.

pub fn file(path: text) -> File fs#read

Use as the entry point for all file I/O. A relative path resolves against the program's own directory (or against the working directory under #cwd), so ../data.txt names the file above the script — the same file an absolute path would name, and it answers the same either way. A path means the same on every platform: / and \ both separate; a name no platform could hold (a:b, q?, aux.txt, a trailing dot or space) is refused everywhere; a name means its exact spelling, so B.txt beside b.txt is refused. A refused path answers like a missing one, and is logged once.

pub fn exists(path: text) -> boolean fs#read

Use to check whether a path is accessible before reading or writing it. A RELATIVE path resolves against the program's own directory, or against the working directory under #cwd; an absolute path is used as given, including one outside the project. This is not an access boundary — the boundary is the fs capability a [sandbox] profile grants or withholds.

pub fn exists(self: const File) -> boolean fs#read

Method form: f = file("path"); if f.exists() { .. } Also callable as exists(file_obj): a self first parameter gives a function both call spellings, the method one and the free one.

pub fn delete(path: text) -> FileResult fs#update

Use to remove a file after processing or as a cleanup step. Returns FileResult.Ok on success and FileResult.NotFound when the file did not exist. A path outside the project is deleted like any other; withhold the fs capability in a [sandbox] profile to prevent that.

pub fn move(from: text, to: text) -> FileResult fs#update

Use to rename or relocate a file. The destination must not already exist (FileResult.Other if it does), and a missing source is FileResult.NotFound. Neither path is confined to the project directory.

pub fn mkdir(path: text) -> FileResult fs#update

Create a single directory level; the parent must already exist (FileResult.NotFound when it does not). FileResult.Other when the directory is already there. rmdir() removes an empty directory again.

pub fn mkdir_all(path: text) -> FileResult fs#update

Create a directory and all missing parents (like Unix mkdir -p). Idempotent: a directory that already exists is FileResult.Ok, which is what makes it safe on the way into a run. rmdir() removes an empty directory again.

pub fn rmdir(path: text) -> FileResult fs#update

Remove the EMPTY directory path. Returns FileResult.NotEmpty when it still holds entries, NotFound when it does not exist, and Other when path is a file rather than a directory. Empty directories only: a recursive removal is a separate decision, and the walk is writable here — list_dir() the children, delete() the files, rmdir() the directory, deepest first. Use to undo a mkdir(), or to clean up a scratch directory a program made.

pub fn is_dir(path: text) -> boolean fs#read

Returns true if path exists and is a directory. Use to branch on a path's kind before descending into / reading it.

pub fn is_file(path: text) -> boolean fs#read

Returns true if path exists and is a regular file. Use to confirm a directory entry is a readable file before opening it.

pub fn is_symlink(path: text) -> boolean fs#read

Returns true if path itself is a symbolic link, whatever it points at — is_dir and is_file answer for the TARGET, so a walk that must not follow a link asks this first. False on a browser host, which has no links.

pub fn list_dir(path: text) -> vector<text> ?fs#read

Lists the entry NAMES of directory path (base names, not full paths), sorted. A MISSING / non-directory path lists as NULL (distinct from an EMPTY directory, []); discharge with ?? [] to keep the old shape. Use to enumerate a directory; join with path to build full child paths.

pub fn files(self: const File) -> vector<File> fs#read

Returns the entries inside a directory, sorted by path — the same order as list_dir, so an index into either listing means the same entry. The File must have format == Format.Directory; anything else lists as [] (where list_dir answers null, because it has no format to check first). Use to iterate over all files in a folder.

pub fn write(self: File, v: text) -> FileResult fs#update

Writes v as UTF-8 text at the file's position: the first write through a File replaces the file's content, later ones follow it. Returns FileResult.Ok on success and FileResult.Other on an OS write failure (disk full, permission denied, a bad path) — a failed write is OBSERVABLE, not silently swallowed. Discarding callers (f.write(s) as a statement) are unaffected; check with f.write(s).ok() or match the result.