File System (std.fs)

The std.fs module provides direct, cross-platform operations for interacting with files and directories on the local filesystem.

---

File Reading, Writing & Copying

Flame executes top-level script statements directly without requiring an entry function:

import std.fs

// Write text to a file (overwriting if it already exists)
fs.write("output.txt", "Hello from Flame!")

// Verify file existence on disk
if fs.exists("output.txt") {
    println("File confirmed on disk.")
}

// Read file contents as a UTF-8 string
let content = fs.read("output.txt")
println(content) // "Hello from Flame!"

// Copy file to a new location
fs.copy("output.txt", "backup.txt")

---

Directory Operations & Cleanup

Create directory hierarchies and clean up filesystem paths:

import std.fs

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

// Recursively create a directory tree including parent folders
fs.mkdir_all("data/backups/daily")

// Remove files or directories recursively with a single command
fs.remove("backup.txt")
fs.remove("data")

---

API Summary Table

Method	Arguments	Returns	Description
fs.read	path: String	String	Reads entire file contents into a UTF-8 string.
fs.readBytes	path: String	Byte	Reads an entire file into a binary byte array.
fs.write	path: String, content: Any	Nil	Writes string data to a file, overwriting existing content.
fs.writeBytes	path: String, bytes: Byte	Nil	Writes raw binary bytes to a file.
fs.appendBytes	path: String, bytes: Byte	Nil	Appends raw binary bytes to the end of a file.
fs.exists	path: String	Bool	Returns true if the filesystem path (file or directory) exists.
fs.copy	src: String, dest: String	Nil	Copies a file from src to dest.
fs.mkdir	path: String	Nil	Creates a single directory at the specified path.
fs.mkdir_all	path: String	Nil	Recursively creates a directory and any missing parent directories.
fs.remove	path: String	Nil	Removes a file, or recursively deletes a directory and all of its contents.

---

File Objects

You can also interact with files dynamically using the fs.open method, which returns a File object containing stateful operations.

import std.fs

let file = await fs.open("data.txt")

// Write and append string data
file.write("First Line\n")
file.append("Second Line\n")

if file.exists() {
    println($"File size: {file.size()} bytes")
    let content = file.read()
    println(content)
}

// Delete the file when done
file.delete()

File 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 string data.
file.append(data)	data: Any	Nil	Appends the string data to the end of the file.
file.exists()	None	Bool	Returns true if this specific file exists.
file.size()	None	Int	Returns the file size in bytes.
file.delete()	None	Nil	Deletes this file from the filesystem.