fs

Filesystem and path primitives.

Naming convention: import the module under its bare name (import "fs"), reach members with a backslash, and call methods in camelCase: fs\someMethod.

Methods

glob

Return paths matching pattern (doublestar-style).

Signature: fs\glob(pattern) -> [Path] - source

Returns: any

Example:

import "std";
import "fs";

foreach (path in fs\glob("cmd/**/*.go") catch []) { std\print(path.value); }

dirname

Directory portion of path.

Signature: fs\dirname(path) -> string - source

Returns: string

Example:

import "std";
import "fs";

std\print(fs\dirname("cmd/magus/main.go"));
// -> "cmd/magus"

basename

Final element of path.

Signature: fs\basename(path) -> string - source

Returns: string

Example:

import "std";
import "fs";

std\print(fs\basename("cmd/magus/main.go"));
// -> "main.go"

exists

True iff path exists.

Signature: fs\exists(path) -> bool¹ - source

Returns: bool

Example:

import "std";
import "fs";

// exists raises when the path cannot be examined at all (an unreadable parent),
// which is not the same answer as "no", so the fallback says no separately.
if (fs\exists("go.mod") catch false) { std\print("Go module"); }

readFile

Return the contents of path as a string.

Signature: fs\readFile(path) -> string - source

Returns: string

Example:

import "std";
import "fs";

final version = fs\readFile("VERSION") catch "unknown";
std\print(version);

writeFile

Write content to path (mode 0644).

Signature: fs\writeFile(path, content) - source

Example:

import "std";
import "fs";

try {
    fs\writeFile("dist/manifest.txt", "artifact list here\n");
} catch (e) {
    std\print("could not write dist/manifest.txt");
}

mkdirAll

Create path and parents (default mode 0755).

Signature: fs\mkdirAll(path, [perm])² - source

join

Join path elements with the OS separator.

Signature: fs\join(parts...) -> string - source

Returns: string

Example:

import "std";
import "fs";

std\print(fs\join(["cmd", "magus", "main.go"]));
// -> "cmd/magus/main.go"

removeAll

Recursively remove path (no error if missing).

Signature: fs\removeAll(path)³ - source

Example:

import "std";
import "fs";

try {
    fs\removeAll("dist/");
} catch (e) {
    std\print("could not remove dist/");
}

remove

Remove a single file or empty directory (no error if missing). Unlike remove_all it refuses a non-empty directory, so a wrong path costs one error rather than a recursive delete.

Signature: fs\remove(path) - source

rename

Move or rename src to dst, creating dst's parent directory if needed. Within one filesystem this is atomic, which is what makes it the last step of a write-to-temp-then-swap. Across filesystems the underlying rename fails rather than silently copying; copy_file plus remove is the explicit form for that.

Signature: fs\rename(src, dst) - source

size

Return path's size in bytes. Raises when path does not exist; stat returns the whole FileInfo when more than the size is wanted.

Signature: fs\size(path) -> int - source

Returns: int

tempFile

Create a new empty temporary file with an optional name prefix and return its path. It is made in the sandbox's private temp dir (the TMPDIR its children get) when the sandbox is on, in the system temp dir otherwise. The file is left in place for the caller to write and remove; temp_dir is the form for a whole tree.

Signature: fs\tempFile([prefix]) -> string - source

Returns: string

writeFileAtomic

Write content to path so a reader sees either the old bytes or the new ones, never a partial file: the content goes to a temporary file in the same directory, is flushed to disk, then renamed over path. Use it for anything another process may read while a target runs - a generated file, a lockfile, a cache index. write_file is the cheaper form when nothing else is looking.

Signature: fs\writeFileAtomic(path, content) - source

listDir

Return directory entries; empty if path does not exist.

Signature: fs\listDir(path) -> []string⁴ - source

Returns: []string

Example:

import "std";
import "fs";

foreach (name in fs\listDir("cmd") catch []) { std\print(name); }

ext

File-name extension of path, including the leading dot ("" if none).

Signature: fs\ext(path) -> string - source

Returns: string

Example:

import "std";
import "fs";

std\print(fs\ext("archive.tar.gz"));
// -> ".gz"

isDir

True iff path exists and is a directory. A sandbox-denied path raises rather than reading as false.

Signature: fs\isDir(path) -> bool - source

Returns: bool

Example:

import "std";
import "fs";

if (fs\isDir("internal") catch false) { std\print("internal is a directory"); }

isFile

True iff path exists and is a regular file. A sandbox-denied path raises rather than reading as false.

Signature: fs\isFile(path) -> bool - source

Returns: bool

Example:

import "std";
import "fs";

if (fs\isFile("go.mod") catch false) { std\print("go.mod is a file"); }

stat

Return metadata for path as {size, mtime, mode, is_dir}: size in bytes, mtime as Unix millis, mode as the integer permission bits. Errors if path is missing.

Signature: fs\stat(path) -> FileInfo - source

Returns: map[string]any

Example:

import "std";
import "fs";

// Bracket access, not info.size: `size` is a built-in map METHOD, so dot access returns
// the method rather than the stat field. The time key is `mtime` (Unix millis), not
// `modTime` - dot access on a missing key is silent, which is how this example went
// unnoticed while printing nothing useful.
try {
    final info = fs\stat("go.mod");
    std\print(info["size"]);
    std\print(info["mtime"]);
} catch (e) {
    std\print("go.mod is not there to stat");
}

copyFile

Copy the file at src to dst (overwriting), preserving its permission bits.

Signature: fs\copyFile(src, dst) - source

Example:

import "std";
import "fs";

try {
    fs\copyFile("dist/magus", "/usr/local/bin/magus");
} catch (e) {
    std\print("could not install dist/magus");
}

copyDir

Recursively copy the directory tree at src to dst, preserving permission bits.

Signature: fs\copyDir(src, dst) - source

Example:

import "std";
import "fs";

// Recursive copy; preserves file mode and dir structure.
try {
    fs\copyDir("assets/", "dist/assets/");
} catch (e) {
    std\print("could not copy assets/ into dist/assets/");
}

watch

Blocking. Watch paths (directories, recursively) and call callback with each debounced batch of changed paths until the callback returns true or the run is interrupted.

Signature: fs\watch(paths, callback) - source

Example:

import "std";
import "fs";

// Blocks; the callback fires per change batch. Return true to keep watching.
try {
    fs\watch(["cmd/**/*.go", "internal/**/*.go"], fun (paths: [str]) > bool {
        foreach (p in paths) { std\print("changed: " + p); }
        return true;
    });
} catch (e) {
    std\print("watch stopped");
}

walk

Recursively walk the directory tree rooted at root, calling callback(path, is_dir) for each entry. Return true from callback to stop the walk early. Sandbox-denied entries are silently skipped.

Signature: fs\walk(root, callback) - source

Example:

import "std";
import "fs";

try {
    fs\walk(".", fun (path: str, isDir: bool) > bool {
        if (isDir and fs\basename(path) == "node_modules") {
            return false;   // skip descent
        }
        if (fs\ext(path) == ".go") { std\print(path); }
        return true;
    });
} catch (e) {
    std\print("walk stopped early");
}

appendFile

Append content to path (creating if absent, mode 0644).

Signature: fs\appendFile(path, content) - source

Example:

import "std";
import "fs";

try {
    fs\appendFile("dist/build.log", "compile done\n");
} catch (e) {
    std\print("could not append to dist/build.log");
}

chmod

Change the permission bits of path to mode (octal integer, e.g. 0755).

Signature: fs\chmod(path, mode) - source

Example:

import "std";
import "fs";

// Mark the release binary executable. Buzz has no octal literal
// (matches upstream); Unix mode 0755 = 493 decimal.
try {
    fs\chmod("dist/magus", 493);
} catch (e) {
    std\print("could not chmod dist/magus");
}

symlink

Create a symbolic link at link pointing to target.

Signature: fs\symlink(target, link) - source

Example:

import "std";
import "fs";

try {
    fs\symlink("dist/magus", "/usr/local/bin/magus");
} catch (e) {
    std\print("could not link /usr/local/bin/magus");
}

readlink

Return the target of the symbolic link at path.

Signature: fs\readlink(path) -> string - source

Returns: string

Example:

import "std";
import "fs";

// readlink raises when the path is not a symlink, so "" reads as "nothing to follow".
std\print(fs\readlink("/usr/local/bin/magus") catch "");

tempDir

Create a new temporary directory with an optional name prefix and return its path. It is made in the sandbox's private temp dir (the TMPDIR its children get) when the sandbox is on, in the system temp dir otherwise.

Signature: fs\tempDir([prefix]) -> string - source

Returns: string

Example:

import "std";
import "fs";

// No sensible fallback path exists, so an unwritable temp dir is reported rather
// than substituted.
try {
    std\print(fs\tempDir("magus-build-"));
    // -> "/tmp/magus-build-abc123"
} catch (e) {
    std\print("no writable temp dir");
}

readLines

Read path and return its lines as a list, with the line terminators stripped. A single trailing newline yields no extra empty element; an empty file yields an empty list.

Signature: fs\readLines(path) -> []string - source

Returns: []string

Example:

import "std";
import "fs";

foreach (line in fs\readLines("targets.txt") catch []) { std\print(line); }

writeLines

Write lines to path (mode 0644), each followed by a newline. The companion to read_lines: write_lines(p, read_lines(p)) round-trips a newline-terminated file.

Signature: fs\writeLines(path, lines) - source

Example:

import "std";
import "fs";

try {
    fs\writeLines("dist/targets.txt", ["build", "test", "lint"]);
} catch (e) {
    std\print("could not write dist/targets.txt");
}