Working with Files (planned)

Luma offers a clean, expressive, and safe approach to file handling, balancing ergonomics with resource safety.

Philosophy

• Minimal syntax for maximum clarity
• Auto-closing handles via use blocks
• Optional file locking via use lock for concurrency safety
• Unified API for bytes, text, and binary data

File Existence, Deletion & Creation

Luma provides built-in helpers for managing files safely and expressively.

file.exist(path: str) -> bool

Checks whether the file at path exists.

if file.exist("config.json") {
    print("Config found")
}

• Returns true if the file exists, false otherwise.
• Works for regular files only (future support for directories possible).

file.delete(path: str) -> bool

Deletes the file at the given path.

success: bool = file.delete("old.log")

• Returns true on success.
• Returns false if the file didn’t exist or deletion failed (e.g. permissions).

file.create(path: str) -> handle

Creates a new file or truncates an existing one, returning a writable handle.

use h = file.create("new.txt") {
    h.append("Hello world")
}

• Equivalent to file.open("new.txt", "w"), but more semantic.
• Safer than raw open/close — auto-closed at the end of use block.
• Encourages readable and structured file creation.

Basic File Access

use handle = file.open("data.txt", "r") {
    text: str = handle.text()
    print(text)
    print("File is ${handle.size()} bytes")
}
// Auto-closed at end of block

• file.open(path, mode) opens a file in "r", "w", or "a" mode
• Default mode is "r" (read)
• Handle is automatically closed at the end of the use block

Read Entire File

As Text:

use handle = file.open("notes.txt") {
    text: str = handle.text()
}

As Bytes:

use handle = file.open("data.bin") {
    bytes: [byte] = handle.bytes()
}

Write or Append to File

use handle = file.open("log.txt", "a") {
    handle.append("New log\n")
    handle.append([0x48, 0x65])  // UTF-8 or raw bytes auto-detected
}

Method: .append(value)

• Accepts str or [byte]
• Automatically encodes to UTF-8 if needed

Exclusive File Access

For concurrent-safe writes, use the use lock construct:

use lock handle = file.open("out.txt", "w") {
    handle.append("Critical write\n")
}
// Lock is released and file closed

• Ensures exclusive access
• Blocks until the file is safe to write
• Lock is released automatically when block ends

The lock keyword builds on Luma’s philosophy of safety by design.

Chained Writes

use handle = file.open("log.txt", "a") {
    handle.append("Line 1\n").append("Line 2\n")
}

• .append() is chainable
• Keeps your code clean and fluent

Memory-Mapped Files

Ideal for large file operations without loading into memory.

Read-only mapping:

use mmap = file.mmap("huge.bin", "r") {
    print(mmap[0..100])
}

Writable mapping:

use mmap = file.mmap("data.bin", "w") {
    mmap[0] = 0xFF
}

Auto-unmaps on exit. Use slicing like regular lists.

File Search & Paths

Recursive glob:

files = file.glob("**/*.txt")

Non-recursive:

files = file.glob("*.log")

Path Utilities

file.join("dir", "file.txt")       // → "dir/file.txt"
file.ext("archive.tar.gz")         // → ".gz"
file.basename("/tmp/file.txt")     // → "file.txt"
file.dirname("/tmp/file.txt")      // → "/tmp"

Summary