File I/O

File operations connect a program to data stored outside its variables. A workflow might read invoice rows from CSV, extract text from a document, and save its results as JSON. Reading data, writing a result, and moving a file are separate operations with different purposes.

This page shows the statement for each operation before combining operations in an error-handling example. These operations need a host runtime with file access; they are not available as arbitrary disk access in the browser playground. See Permissions to limit the files a program may access.

Reading Structured Files

JSON

Read JSON from "config.json" as config

Returns a parsed record or list.

CSV

Read CSV from "invoices.csv" as invoices

Returns a list of records with column headers as field names.

XLSX

Read XLSX cell "Sheet1!B2" as total_amount

Reads a single cell value by sheet and cell reference.

PDF and DOCX

Read PDF text "contract.pdf" as contract_text
Read DOCX text "agreement.docx" as agreement_text

Extracts plain text content from document files.

Writing Files

Write and Overwrite

Write report to "tmp/report.txt"
Overwrite summary to "tmp/summary.txt"

Write saves text. Overwrite explicitly replaces existing content.

Export

Export results to "tmp/results.json"
Export rows to "tmp/output.csv" as CSV

Export serializes records and lists as pretty JSON by default. Use as CSV to write a list of records as a CSV table.

Append

Append "processed\n" to file "tmp/run.log"

Adds text to the end of an existing file without replacing content.

Filesystem Operations

Copy and Move

Copy file from "/inbox/receipt.pdf" to "/receipts/2026-07/receipt.pdf"
Move file from "/tmp/draft.txt" to "/archive/final.txt"

Both create parent directories automatically. Copy supports directories (recursive).

Create and Delete

Create directory "/receipts/2026-07/"
Delete file "/tmp/scratch.txt"

Delete file removes files or directories recursively.

Check Existence

Check if "/inbox/receipt.pdf" exists as file_found

Stores true or false.

File Metadata

Get file info for "/inbox/receipt.pdf" as info

Returns a record with path, type (“file”, “directory”, or “symlink”), size (bytes), and modified (Unix timestamp).

List and Find

List files in "/inbox/" as entries
Find files matching "*.pdf" in "/inbox/" as pdf_files

List files returns sorted filenames. Find files matching uses glob patterns and returns full paths.

Error Handling

Wrap file operations in Try blocks for graceful recovery:

Try:
  Read JSON from "maybe-missing.json" as data
Otherwise:
  data equals record with "default" as mode
  Print last_error