File API: First Edition - Simple, Powerful, Luma-style

We’re excited to announce the first official File API in Luma! It brings clean, readable, and expressive file handling - in a way that matches Luma’s philosophy of clarity, safety, and zero boilerplate.

Highlights

Safe Resource Handling with use

use handle = file.open("data.txt", "r") {
    print(handle.text())
}

• Auto-closes the file after the block
• Cleaner and safer than manual close()

Intuitive Reading & Writing

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

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

• Text and bytes both supported
• Chaining with .append() is natural and expressive

File Info Made Easy

ext = file.ext("photo.jpg")      // "jpg"
size = handle.size()             // in bytes

• .ext() returns just the extension, no dot (user-friendly)
• .size() reports file size (no extra logic needed)

Memory Mapping Support

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

• Efficient access for large files
• Read and write support

File Path Tools

path = file.join("dir", "data.txt")   // cross-platform
base = file.basename("/tmp/a.txt")    // "a.txt"

Future Ready

We’ve designed the File API with these goals in mind:

• Minimal syntax, maximum clarity
• Safe by default (use ensures auto-close)
• Ergonomic chaining where it makes sense
• Optional locking for concurrency safety
• Consistent method naming (snake_case, return bools, etc.)

What’s Next?

• .copy(), .move() planned
• file.exists(), file.delete()
• Directory operations
• File permissions and metadata
• Extended glob & filters
• File streaming?

Luma’s File API is not just about access — it’s about developer experience. We hope you enjoy this new addition. Let us know your thoughts or proposals!