File System (std.fs)

The std.fs module provides direct, cross-platform operations for interacting with files and directories on the local filesystem, supporting both UTF-8 string text and raw binary (Bytes) payloads.

File Reading & Writing

Flame allows quick one-liner filesystem operations without verbose stream setup:

import std.fs

// Write UTF-8 text to a file (overwrites if it exists, creates if not)
fs.write("config.txt", "server_port = 8080\nenabled = true\n")

// Append additional text to an existing file
fs.append("config.txt", "log_level = info\n")

// Check if the file exists on disk
if fs.exists("config.txt") {
    println($"File exists, size: {fs.size("config.txt")} bytes")
}

// Read entire file content as a UTF-8 string
let config = fs.read("config.txt")
println(config)

// Copy file to another location
fs.copy("config.txt", "config.txt.bak")

Binary File I/O (`readBytes`, `writeBytes`, `appendBytes`)

When working with binary files such as images, archives, audio, or custom .fmp binary formats, use the dedicated byte-level functions:

import std.fs
import std.byte

// Read an entire file into a raw binary Bytes buffer
let raw_bytes = fs.readBytes("input.bin")
println($"Loaded {raw_bytes.len()} raw bytes")
println($"Hex header: {raw_bytes.slice(0, 4).toHex()}")

// Write raw binary bytes to disk (creates or replaces file)
let magic = byte.fromBytes([0x46, 0x4D, 0x50, 0x01]) // FMP\x01
fs.writeBytes("output.bin", magic)

// Append additional binary data to the file
let payload = "Hello Binary!".toBytes()
fs.appendBytes("output.bin", payload)

Directory Operations & Traversal

std.fs provides complete tooling for directory inspection and recursive exploration:

Querying Paths: `isDir`, `isFile`, `exists`, `size`

import std.fs

let target = "src"

if fs.exists(target) {
    if fs.isDir(target) {
        println($"{target} is a directory")
    } else if fs.isFile(target) {
        println($"{target} is a regular file with size: {fs.size(target)} bytes")
    }
}

Creating & Removing Directories

import std.fs

// Create a single directory
fs.mkdir("build")

// Recursively create a directory tree including parent folders
fs.mkdir_all("dist/releases/v1.0")

// Delete a file or recursively delete an entire directory tree
fs.delete("config.txt.bak")
fs.remove("dist") // Alias of delete, recursively deletes folder contents

Reading Directory Contents (`readDir`)

fs.readDir(path) returns an array of child file and directory names (relative names, not full paths):

import std.fs

let entries = fs.readDir("./src")
for name in entries {
    println($"Found entry: {name}")
}

Recursive Directory Traversal Example

Here is how to recursively collect all files in a folder tree, filtering out ignored folders like .git or target:

import std.fs

fn collect_all_files(root: String) -> [String] {
    let mut files = []
    let mut queue = [root]
    let mut q_idx = 0

    while q_idx < queue.len() {
        let current = queue[q_idx]
        q_idx = q_idx + 1

        let entries = fs.readDir(current)
        for name in entries {
            if name == ".git" || name == "target" || name == "node_modules" {
                continue
            }

            let full_path = if current == "." { name } else { $"{current}/{name}" }

            if fs.isDir(full_path) {
                queue.push(full_path)
            } else if fs.isFile(full_path) {
                files.push(full_path)
            }
        }
    }

    files
}

let all_sources = collect_all_files(".")
println($"Found {all_sources.len()} total project files:")
for f in all_sources {
    println($" - {f} ({fs.size(f)} bytes)")
}

Stateful File Objects (`fs.open`)

For object-oriented workflows or multiple consecutive operations on the same file, use fs.open(path) to obtain a File handle:

import std.fs
import std.byte

// Open a file handle
let file = fs.open("session.log")

// Text operations
file.write("=== Session Started ===\n")
file.append("User logged in at 10:00 AM\n")

// Inspect through file handle
if file.exists() {
    println($"Log file size: {file.size()} bytes")
    let contents = file.read()
    println(contents)
}

// Binary operations directly on File handle
let signature = byte.fromHex("deadbeef")
file.writeBytes(signature)
file.appendBytes("extra payload".toBytes())

let binary_data = file.readBytes()
println($"Raw file bytes: {binary_data.toHex()}")

// Clean up
file.delete()

File Object Methods

Method	Arguments	Returns	Description
`file.read()`	None	`String`	Reads entire file contents into a UTF-8 string.
`file.write(data)`	`data: Any`	`Nil`	Overwrites the file with the given text or binary data.
`file.append(data)`	`data: Any`	`Nil`	Appends text or binary data to the end of the file.
`file.readBytes()`	None	`Bytes`	Reads entire file contents into a raw binary `Bytes` buffer.
`file.writeBytes(data)`	`data: Any`	`Nil`	Overwrites file with binary bytes (`Bytes`, array, or string).
`file.appendBytes(data)`	`data: Any`	`Nil`	Appends raw binary bytes to the end of the file.
`file.exists()`	None	`Bool`	Returns `true` if the underlying file exists on disk.
`file.size()`	None	`Int`	Returns the file size in bytes.
`file.delete()`	None	`Nil`	Deletes the file from the filesystem.

API Summary Table

Method	Arguments	Returns	Description
`fs.read`	`path: String`	`String`	Reads entire file contents into a UTF-8 string.
`fs.write`	`path: String, content: Any`	`Nil`	Writes string or binary content to a file, replacing existing content.
`fs.append`	`path: String, content: Any`	`Nil`	Appends string or binary content to the end of a file.
`fs.readBytes`	`path: String`	`Bytes`	Reads an entire file into a raw binary `Bytes` buffer.
`fs.writeBytes`	`path: String, bytes: Any`	`Nil`	Writes binary data (`Bytes`, array, or string) to a file.
`fs.appendBytes`	`path: String, bytes: Any`	`Nil`	Appends binary data to the end of a file.
`fs.exists`	`path: String`	`Bool`	Returns `true` if the path exists on disk (file or directory).
`fs.isDir`	`path: String`	`Bool`	Returns `true` if the specified path is a directory.
`fs.isFile`	`path: String`	`Bool`	Returns `true` if the specified path is a regular file.
`fs.size`	`path: String`	`Int`	Returns the size of the file in bytes.
`fs.readDir`	`path: String`	`[String]`	Reads directory entries, returning child filenames/subdirectories.
`fs.mkdir`	`path: String`	`Nil`	Creates a single directory at the specified path.
`fs.mkdir_all`	`path: String`	`Nil`	Recursively creates a directory path and all missing parent folders.
`fs.copy`	`src: String, dest: String`	`Nil`	Copies a file from `src` to `dest`.
`fs.remove`	`path: String`	`Nil`	Removes a file or recursively deletes a directory tree.
`fs.delete`	`path: String`	`Nil`	Alias for `fs.remove`. Deletes a file or directory tree.
`fs.open`	`path: String`	`File`	Opens a file handle for stateful text and binary operations.