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")) { 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";

if (fs\exists("go.mod")) { 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");
std\print(version);

writeFile

Write content to path (mode 0644).

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

Example:

import "fs";

fs\writeFile("dist/manifest.txt", "artifact list here\n");

mkdirall

Create path and parents (default mode 0755).

Signature: fs\mkdirall(path, [perm])² · source

Example:

import "fs";

// Buzz has no octal literal (matches upstream); Unix mode 0755 = 493 decimal.
fs\mkdirall("dist/reports", 493);

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 "fs";

fs\removeAll("dist/");

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")) { 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 reads as false).

Signature: fs\isDir(path) → bool · source

Returns: bool

Example:

import "std";
import "fs";

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

isFile

True iff path exists and is a regular file (a sandbox-denied path reads as false).

Signature: fs\isFile(path) → bool · source

Returns: bool

Example:

import "std";
import "fs";

if (fs\isFile("go.mod")) { 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.
final info = fs\stat("go.mod");
std\print(info["size"]);
std\print(info["mtime"]);

copyFile

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

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

Example:

import "fs";

fs\copyFile("dist/magus", "/usr/local/bin/magus");

copyDir

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

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

Example:

import "fs";

// Recursive copy; preserves file mode and dir structure.
fs\copyDir("assets/", "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.
fs\watch(["cmd/**/*.go", "internal/**/*.go"], fun (paths: [str]) > bool {
    foreach (p in paths) { std\print("changed: " + p); }
    return true;
});

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";

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;
});

appendFile

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

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

Example:

import "fs";

fs\appendFile("dist/build.log", "compile done\n");

chmod

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

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

Example:

import "fs";

// Mark the release binary executable. Buzz has no octal literal
// (matches upstream); Unix mode 0755 = 493 decimal.
fs\chmod("dist/magus", 493);

symlink

Create a symbolic link at link pointing to target.

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

Example:

import "fs";

fs\symlink("dist/magus", "/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";

std\print(fs\readlink("/usr/local/bin/magus"));

tempDir

Create a new temporary directory (in os.TempDir()) with an optional name prefix and return its path.

Signature: fs\tempDir([prefix]) → string · source

Returns: string

Example:

import "std";
import "fs";

final tmp = fs\tempDir("magus-build-");
std\print(tmp);
// -> "/tmp/magus-build-abc123"

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")) { 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 "fs";

fs\writeLines("dist/targets.txt", ["build", "test", "lint"]);