File I/O API

Complete file and directory operations with file handles, buffer integration, and cross-platform path utilities.

Overview

The File I/O API provides quick single-call operations, fine-grained file handles with seeking and line-by-line reading, seamless Buffer integration for binary data, cross-platform path manipulation, and directory management.

Quick File Operations

Reads an entire file as a string.

• path (string) — path to the file

var content = fileRead("config.txt")
print(content)

Writes data to a file, creating or truncating it.

• path (string) — path to the file
• data (string) — content to write

Appends data to an existing file (or creates it if it doesn't exist).

• path (string) — path to the file
• data (string) — content to append

Checks if a file or directory exists.

Returns: true if exists, false otherwise.

if (fileExists("config.json")) {
    var config = fileRead("config.json")
}

Deletes a file.

Copies a file from source to destination.

Renames or moves a file.

Gets file information.

Returns: Map with size (bytes), isDirectory, isFile, and modified (timestamp).

var info = fileStat("document.pdf")
print("File size: %v bytes", info.size)
print("Is directory: %v", info.isDirectory)

File Handles

Opens a file and returns a file handle object.

• path (string) — path to the file
• mode (string, optional) — open mode (default: "r")

Modes: "r" read, "w" write (truncate), "a" append, "rb" read binary, "wb" write binary, "ab" append binary, "r+" read/write, "rb+" or "r+b" read/write binary.

Handle Read Methods

Reads the entire remaining file content as a string.

Reads count bytes from the file as a string.

Reads a single line (up to \n or \r\n). Returns null at EOF.

Reads all remaining lines. Returns a list of strings (one per line, without newlines).

var file = fileOpen("lines.txt", "r")
while (true) {
    var line = file.readLine()
    if (line == null) { break }
    print(line)
}
file.close()

Handle Write Methods

Writes data to the file.

Writes data followed by a newline character.

Flushes buffered writes to disk.

Handle Navigation

Sets the file position to the specified byte offset.

Returns the current file position.

Returns the total file size in bytes.

Returns true if at end-of-file.

Handle Lifecycle

Closes the file handle, releasing system resources.

Returns true if the file is currently open.

Returns the file path.

Returns the file open mode.

Handle Properties

The position property is a native reference that synchronizes with the file's internal position. Read and write directly.

var file = fileOpen("data.txt", "r")
print("Position: %v", file.position)  // 0
file.position = 10
var data = file.readBytes(5)
print("Position: %v", file.position)  // 15
file.close()

Buffer Integration

Reads an entire file directly into a new buffer.

Returns: Buffer containing the file contents.

Writes the entire contents of a buffer to a file.

Reads data from the file into an existing buffer. Reads from current file position, writes at buffer's current position, advances both. Stops at buffer capacity or EOF.

Returns: Number of bytes read.

Writes data from a buffer to the file. If count is omitted, writes from buffer position to buffer length.

Returns: Number of bytes written.

var buffer = Buffer(256)
buffer.writeUInt32(0xDEADBEEF)
buffer.writeString("Data")
fileWriteBuffer("output.bin", buffer)

var loaded = fileReadBuffer("output.bin")
loaded.position = 0
var magic = loaded.readUInt32()
var text = loaded.readString()

Directory Operations

Creates a new directory.

Removes an empty directory.

Lists the contents of a directory. Returns a list of strings (excluding . and ..).

var entries = dirList("my_folder")
var i = 0
while (i < length(entries)) {
    print("- %v", entries[i])
    i = i + 1
}

Checks if a directory exists. Returns true or false.

Path Operations

Joins two path components with the platform-specific separator.

var path = pathJoin("folder", "file.txt")
// Windows: "folder\file.txt"
// Unix: "folder/file.txt"

Returns the directory portion of a path, or "." if no directory.

Returns the filename portion of a path.

Returns the file extension including the dot (e.g. ".txt"), or empty string if none.

Normalizes a path by converting separators to the platform-specific format.

Converts a relative path to an absolute path.

Returns true if the path is absolute, false if relative.

Examples

Project Structure Creation

func createProjectStructure(projectName) {
    if (!dirExists(projectName)) {
        dirCreate(projectName)
    }
    var srcDir = pathJoin(projectName, "src")
    var docsDir = pathJoin(projectName, "docs")
    var testsDir = pathJoin(projectName, "tests")
    dirCreate(srcDir)
    dirCreate(docsDir)
    dirCreate(testsDir)

    var mainFile = pathJoin(srcDir, "main.zym")
    fileWrite(mainFile, "// Main entry point\n")
    print("Created project structure")
}

createProjectStructure("my_project")

Chunked File Processing

var file = fileOpen("large_file.dat", "rb")
var buffer = Buffer(4096)
var totalBytes = 0

while (!file.eof()) {
    buffer.clear()
    var bytesRead = file.readToBuffer(buffer)
    if (bytesRead > 0) {
        totalBytes = totalBytes + bytesRead
        buffer.position = 0
        // Process buffer data...
    }
}

file.close()
print("Total: %v bytes", totalBytes)