Docs / Standard Library / File

File

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

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"