I/O And Filesystem

Import io for console output, file and directory operations, file handles, temporary files, buffers, CSV convenience helpers, and stdin.

io owns filesystem mutation in Geblang. sys owns process and environment state, while path owns path string manipulation. For example, use path.join to build a path, io.mkdir to create it, and sys.tmpdir when you need the host temporary directory.

import io;
import path;
import sys;

let work = path.join(sys.tmpdir(), "geb-work");
io.mkdir(work, 0o755);

Most io functions raise an error on OS failure: missing files, permission errors, invalid handles, failed flushes, and unsupported operations are not silently ignored. Use try/catch when absence or failure is expected.

Console Output

io.print("hello ");
io.println("world");
io.stdoutWrite("raw\n");
io.stderrWrite("warning\n");
io.stderrPrintln("fatal");

print and println accept any printable Geblang value. stdoutWrite and stderrWrite expect strings and do not add formatting.

Whole-File Operations

Use whole-file helpers for small files that fit comfortably in memory.

io.writeText("notes.txt", "first line\n");
io.appendText("notes.txt", "second line\n");

let text = io.readText("notes.txt");
let data = io.readBytes("notes.txt");

For large files or files you want to stream incrementally, use file handles.

File Existence And Metadata

stat(path) returns:

if (io.exists("app.log")) {
    let info = io.stat("app.log");
    io.println(info["size"] as string);
    io.println(info["mode"] as string);
}

exists returns false for missing paths. stat raises an error if the path cannot be inspected.

Directories

let root = io.tempDir("geb-docs-*");
defer io.remove(root);

io.mkdir(root + "/nested/reports", 0o755);
io.writeText(root + "/nested/reports/today.txt", "ok");

for (name in io.listDir(root + "/nested")) {
    io.println(name);
}

mkdir creates missing parents. The mode argument is the requested permission bits, such as 0o755. The host operating system may still apply its normal umask.

remove removes files and directories recursively. Use it carefully when a path comes from user input.

walkDir(path) returns one dictionary per file or directory:

for (entry in io.walkDir("src")) {
    if (!(entry["isDir"] as bool) && entry["name"].endsWith(".gb")) {
        io.println(entry["path"]);
    }
}

Permissions, Ownership, And Links

io.writeText("secret.txt", "token");
io.chmod("secret.txt", 0o600);

io.symlink("secret.txt", "latest-secret.txt");
io.println(io.readLink("latest-secret.txt"));

chmod and chown are OS-level operations. On some platforms, especially Windows, permission semantics may differ from Unix-style mode bits. chown normally requires appropriate OS privileges.

Temporary Files And Directories

Use * in the pattern as the random suffix placeholder.

let file = io.tempFile("geb-example-*.txt");
defer io.remove(file);

io.writeText(file, "temporary data");
io.println(io.readText(file));

let dir = io.tempDir("geb-work-*");
defer io.remove(dir);
io.mkdir(dir + "/cache", 0o755);

Temporary helpers create the path immediately. They do not automatically clean up; use defer io.remove(path) when the file or directory is short-lived.

File Handles

File handles are integer handles owned by the runtime. Open a handle when you need incremental reads/writes, flushing, file locking, or sync control.

Supported open modes:

let f = io.open("app.log", "a");
defer io.close(f);

io.writeln(f, "started");
io.flush(f);

Reading incrementally:

let f = io.open("app.log", "r");
defer io.close(f);

let chunk = io.read(f, 4096);
while (chunk != "") {
    io.print(chunk);
    chunk = io.read(f, 4096);
}

Always close file handles. defer io.close(handle) is the normal pattern.

Streams And Capture

Use stream constructors when you want file-like resources that are not opened from filesystem paths. io.open(path, mode) remains filesystem-only; stdout, stderr, stdin, and memory streams are created explicitly.

Streams work with the same read, readBytes, readAll, write, writeBytes, writeln, flush, and close functions used by file handles, where the operation is supported by the stream.

let mem = io.memory("hello");
io.writeln(mem, " streams");

io.println(io.toString(mem)); # hello streams

Capture helpers are evaluator-local. They are designed for tests and framework code that needs to inspect output without writing to the real console:

let capture = io.captureStdout();

io.println("hidden from real stdout");
io.stdoutWrite("also captured\n");

let text = io.toString(capture);
io.close(capture);

io.println(text.contains("hidden"));

Use defer with redirect helpers when a test temporarily replaces a stream:

let mem = io.memory();
let restore = io.redirectStdout(mem);

io.println("captured in memory");

restore();
io.println(io.toString(mem));

Calling io.close(capture) restores the previous stdout or stderr target. Use io.toString(stream) to inspect memory-backed streams and captures. Use io.read(stream, n), io.readAll(stream), and io.readBytes(stream, n) when you want to consume readable stream content.

File Locking

let f = io.open("state.db", "r+");
defer io.close(f);

io.lock(f);
defer io.unlock(f);

# critical section

Locks are advisory and process-level. Other processes must also cooperate with advisory locking for it to protect shared files.

Buffers

Buffers are in-memory write targets. They are useful when an API accepts a file or buffer handle, or when you want to build text incrementally.

write and writeln accept buffers as well as file handles:

let buf = io.buffer();
io.write(buf, "hello ");
io.writeln(buf, "world");

io.println(io.bufferToString(buf));
io.bufferReset(buf);

Stdin Helpers

let name = io.readLine("Name: ");
if (name != null) {
    io.println("Hello " + name);
}

For masked input and richer terminal UI, use the cli module.

CSV Convenience Helpers

These helpers read or write small CSV files in memory.

let rows = io.readCSV("users.csv");
rows = rows.push(["3", "Linus"]);
io.writeCSV("users.csv", rows);

For large CSV files, use the streaming APIs in the csv module.

Common Patterns

Create a temporary workspace:

let root = io.tempDir("job-*");
defer io.remove(root);

let out = root + "/out.txt";
io.writeText(out, "result");

Safely update a file:

let tmp = io.tempFile("settings-*.tmp");
io.writeText(tmp, newText);
io.chmod(tmp, 0o600);
io.rename(tmp, "settings.conf");

Lock a file while processing:

func processLog(string path): void {
    let f = io.open(path, "r");
    defer io.close(f);

    io.lock(f);
    defer io.unlock(f);

    let content = io.readAll(f);
    # process content
}