std/file

File System (File)

The std/file module provides bounded, capability-governed file reading, writing, and inspection. All file operations follow the principle that authority belongs to the host application, running inside a language-level sandbox to safely govern AI-generated code.

Basic File Reading & Writing

Initialize a File instance using a file path and a FileMode enumeration. Always close file handles explicitly or within a finally block to release OS file descriptors.

@import("std/file")

val logPath = "audit_log.txt"

// 1. Write text to file
val writer = File(logPath, FileMode.WRITE)
writer.write("ORD-101: AUTHORIZED\n")
writer.write("ORD-102: SETTLED\n")
writer.close()

// 2. Read entire file content
val reader = File(logPath, FileMode.READ)
val content = reader.readText()
reader.close()

println("File content:\n" + content)

Memory-Efficient Streaming with `forEachLine`

To respect managed memory quotas and avoid memory exhaustion, Autolang provides streaming iteration line by line without loading the whole file into RAM at once.

@import("std/file")

val reader = File("audit_log.txt", FileMode.READ)
var settledCount = 0

reader.forEachLine { line ->
    if (line.indexOf("SETTLED") != -1) {
        settledCount += 1
    }
}
reader.close()

println("Settled transactions count: " + settledCount)

File & Directory Inspection

Static utility methods allow checking file existence, inspecting file size, extracting extensions, and listing directory contents.

@import("std/file")

val path = "reports/quarterly.pdf"

if (File.exists(path)) {
    println("File name: " + File.getName(path))
    println("Extension: " + File.getExtension(path))
    println("Size: " + File.getSize(path) + " bytes")
    println("Parent dir: " + File.getParent(path))
}

// Iterate directory entries
val currentDir = "."
if (File.isDirectory(currentDir)) {
    val entries = File.getAllFiles(currentDir)
    println("Total entries: " + entries.size)
}

Security Boundaries & Capability Governance

Autolang applies defense-in-depth protection across all file I/O operations:

1. Default-Deny Authority

Scripts do not have ambient file access. The host application must explicitly register file capabilities or grant directory permissions.

2. Path Length Constraints

Paths exceeding 512 characters are immediately rejected with a SecurityError to prevent buffer overflow attacks.

3. Closed Handle Safeguards

Any read or write operation on a closed handle throws an explicit exception rather than causing an unhandled segmentation crash.

Method Reference

Static Inspection Methods

File.exists(path: String): Bool: Checks whether the file or directory exists.
File.isDirectory(path: String): Bool: Checks whether the path points to a directory.
File.getSize(path: String): Int: Returns file size in bytes.
File.getName(path: String): String: Extracts filename with extension.
File.getExtension(path: String): String: Extracts file extension.
File.getParent(path: String): String: Returns parent directory path.
File.getAllFiles(dir: String): Array<String>: Returns an array of file names in the directory.

File Instance Methods

File(path: String, mode: FileMode): File: Opens a file stream with the given mode.
readText(): String: Reads entire file content as a string.
write(content: String): Writes text content to the file.
forEachLine(action: (String) -> Unit): Streams the file line by line without buffer spikes.
close(): Closes the file stream and releases host resources.