Docs / Standard Library / File

File

The File module provides functions for reading and writing files, managing file operations, and querying file information.

File Capabilities

File system builtins require authority in scope. Read operations require FileReadAuth, FileAuth, or RootAuth; write/delete operations require FileWriteAuth, FileAuth, or RootAuth. Use Auth.File, IO.FileAuth, or delegated FilePath capabilities when you want explicit least-authority APIs.

Reading Files

File.read
String -> Result String IOError
Reads the entire contents of a file as a string. 
match File.read "config.txt"
  | Ok contents -> println contents
  | Err e -> println "Error: ${e}"
File.lines
String -> List String
Reads a file and returns its contents as a list of lines. 
lines = File.lines "data.txt"
lines |> each (fn(line) => println line)
File.read-bytes
String -> Result (List Int) IOError
Reads a file as a list of bytes (integers 0-255). 
match File.read-bytes "image.png"
  | Ok bytes -> println "Read ${length bytes} bytes"
  | Err e -> println "Error: ${e}"
File.fold-lines
String -> (a -> String -> a) -> a -> Result a IOError
Folds over lines of a file with an accumulator. Memory-efficient for large files. 
# Count lines in a file
match File.fold-lines "large.txt" (fn(count, _) => count + 1) 0
  | Ok n -> println "Lines: ${n}"
  | Err e -> println "Error: ${e}"
File.with-lines
String -> (String -> ()) -> Result () IOError
Iterates over lines of a file, calling a function for each line. 
File.with-lines "data.txt" (fn(line) => println line)
File.fold-bytes
String -> Int -> (a -> List Int -> a) -> a -> Result a IOError
Folds over bytes of a file in chunks. The second argument is the chunk size.
File.with-bytes
String -> Int -> (List Int -> ()) -> Result () IOError
Iterates over bytes of a file in chunks. The second argument is the chunk size.
File.mmap
String -> Result String IOError
Memory-maps a file for efficient reading. Use File.munmap to release.
File.munmap
String -> Result () IOError
Unmaps a memory-mapped file.

Writing Files

File.write
String -> String -> Result () IOError
Writes content to a file, overwriting any existing content. 
match File.write "output.txt" "Hello, World!"
  | Ok _ -> println "File written"
  | Err e -> println "Error: ${e}"
File.append
String -> String -> Result () IOError
Appends content to the end of a file. 
File.append "log.txt" "New log entry\n"
File.write-bytes
String -> List Int -> Result () IOError
Writes a list of bytes to a file. 
File.write-bytes "output.bin" [0x48, 0x65, 0x6c, 0x6c, 0x6f]
File.append-bytes
String -> List Int -> Result () IOError
Appends a list of bytes to a file.

File Operations

File.copy
String -> String -> Result () IOError
Copies a file from source to destination. 
match File.copy "original.txt" "backup.txt"
  | Ok _ -> println "Copied"
  | Err e -> println "Error: ${e}"
File.move
String -> String -> Result () IOError
Moves or renames a file. 
File.move "old-name.txt" "new-name.txt"
File.delete
String -> Result () IOError
Deletes a file. 
match File.delete "temp.txt"
  | Ok _ -> println "Deleted"
  | Err e -> println "Error: ${e}"

File Information

File.exists?
String -> Bool
Returns true if the file exists. 
if File.exists? "config.toml" then
  println "Config found"
else
  println "Config not found"
File.size
String -> Int
Returns the size of a file in bytes. 
size = File.size "data.bin"
println "File size: ${size} bytes"
File.stat
String -> Result {size, mode, ...} IOError
Returns detailed file statistics including size, mode, timestamps, etc. 
match File.stat "file.txt"
  | Ok info -> println "Size: ${info.size}"
  | Err e -> println "Error: ${e}"

Permissions

File.mode
String -> Result Int IOError
Returns the file's permission mode as an integer.
File.chmod
Int -> String -> Result () IOError
Changes a file's permissions. Mode is specified as an octal integer. 
# Make file executable (755)
File.chmod 0o755 "script.sh"
File.readable?
String -> Bool
Returns true if the file is readable by the current user.
File.writable?
String -> Bool
Returns true if the file is writable by the current user.
File.executable?
String -> Bool
Returns true if the file is executable by the current user.

Temporary Files

File.temp-dir
() -> Result String IOError
Returns the system's temporary directory path. 
match File.temp-dir()
  | Ok dir -> println "Temp dir: ${dir}"
  | Err e -> println "Error: ${e}"
# => "Temp dir: /tmp"
File.temp
String -> Result String IOError
Creates a temporary file with the given prefix and returns its path. 
match File.temp "myapp-"
  | Ok path -> println "Temp file: ${path}"
  | Err e -> println "Error: ${e}"
# => "Temp file: /tmp/myapp-abc123"