Standard Library — The io Module

Contents

• The io Standard Library Module
• readFile
• writeFile
• appendFile
• readBytes
• writeBytes
• Examples

The io Standard Library Module

The io module provides file I/O through simple functions that read and write entire files at once — both text-mode (str) and binary-mode (Buffer). It is a standard library module, not part of the prelude — programs that need file I/O must import it explicitly:

use @std.io

Individual functions can be imported selectively:

use @std.io.[readFile, writeFile, readBytes, writeBytes]

readFile

fn readFile(path: str) -> Result[str, IoError]

Read the entire contents of a file as a string. Returns Ok(str) on success or Err(IoError.Other(msg)) on failure (file not found, permission denied, I/O error, etc.). Returns Ok("") if the file exists but is empty.

use @std.io

content = io.readFile("data.txt")?
println("{content}")

writeFile

fn writeFile(path: str, content: str) -> Result[(), IoError]

Write a string to a file. Creates the file if it does not exist; truncates the file to zero length if it does. Returns Ok(()) on success or Err(IoError.Other(msg)) on failure (permission denied, I/O error, etc.).

use @std.io

io.writeFile("output.txt", "Hello, world!\n")?

appendFile

fn appendFile(path: str, content: str) -> Result[(), IoError]

Append a string to the end of a file. Creates the file if it does not exist. Returns Ok(()) on success or Err(IoError.Other(msg)) on failure.

use @std.io

io.appendFile("log.txt", "entry: something happened\n")?

readBytes

fn readBytes(path: str) -> Result[Buffer, IoError]

Read the entire contents of a file as raw bytes. Returns Ok(Buffer) on success or Err(IoError.Other(msg)) on failure (file not found, permission denied, I/O error, etc.). Returns an empty Buffer if the file exists but is empty.

Unlike readFile, this function does not interpret the file contents as UTF-8 — the bytes are returned exactly as they appear on disk.

use @std.io

data = io.readBytes("image.png")?
println("file size: {data.length()} bytes")

writeBytes

fn writeBytes(path: str, content: Buffer) -> Result[(), IoError]

Write raw bytes to a file. Creates the file if it does not exist; truncates the file to zero length if it does. Returns Ok(()) on success or Err(IoError.Other(msg)) on failure (permission denied, I/O error, etc.).

use @std.io

mut buf = Buffer.new()
buf.push(0x7Fb)       # ELF magic byte (example)
buf.push(0x45b)
io.writeBytes("output.bin", buf)?

Examples

Reading and processing a file:

use @std.io

fn wordCount(path: str) -> Result[uint, IoError]
    content = io.readFile(path)?
    words = content.split(" ")
    return Ok(words.length())
end

Writing output:

use @std.io

fn saveResults(path: str, results: List[str]) -> Result[(), IoError]
    output = results.join("\n")
    io.writeFile(path, output)?
    return Ok(())
end

Appending to a log:

use @std.io

fn logMessage(path: str, message: str) -> Result[(), IoError]
    io.appendFile(path, "{message}\n")?
    return Ok(())
end

Error handling:

use @std.io

match io.readFile("data.txt")
    Ok(content) then println("{content}")
    Err(IoError.Other(msg)) then println("error: {msg}")
    Err(_) then println("unknown error")
end

Note: Non-blocking I/O, streaming/line-by-line reading, directory operations, and path manipulation are outside the scope of this initial io module specification. Programs requiring these capabilities will need to wait for future language extensions (see roadmap.md).