Skip to content

Guide File System

Jump to bottom
Kris Simon edited this page Dec 31, 2025 · 7 revisions

File System

ARO provides built-in file system operations for reading, writing, and watching files. This chapter covers file I/O and directory monitoring.

Reading Files

Text Files

<Read> the <content> from the <file: "./data.txt">.
<Read> the <readme> from the <file: "./README.md">.

JSON Files

<Read> the <config: JSON> from the <file: "./config.json">.
<Read> the <data: JSON> from the <file: "./data.json">.

Binary Files

<Read> the <image: bytes> from the <file: "./logo.png">.
<Read> the <document: bytes> from the <file: "./report.pdf">.

Dynamic Paths

(GET /files/{name}: File API) {
    <Extract> the <filename> from the <request: parameters>.
    <Read> the <content> from the <file: "./uploads/${filename}">.
    <Return> an <OK: status> with <content>.
}

Error Handling

(Load Config: Configuration) {
    <Read> the <config: JSON> from the <file: "./config.json">.

    <Log> "Config not found, using defaults" to the <console> when <config> is empty.
    <Create> the <config> with {
        port: 8080,
        debug: false
    } when <config> is empty.

    <Publish> as <app-config> <config>.
    <Return> an <OK: status> for the <loading>.
}

Writing Files

Text Files

<Write> the <content> to the <file: "./output.txt">.
<Write> the <report> to the <file: "./reports/daily.txt">.

JSON Files

<Write> the <config: JSON> to the <file: "./config.json">.
<Write> the <data: JSON> to the <file: "./export.json">.

Appending

<Store> the <log-entry> into the <file: "./logs/app.log">.
<Store> the <record> into the <file: "./data/records.csv">.

Creating Directories

Directories are created automatically when writing:

(* ./reports/2024/01/ is created if it doesn't exist *)
<Write> the <report> to the <file: "./reports/2024/01/daily.txt">.

Format-Aware File I/O

ARO automatically detects the file format based on the extension and serializes/deserializes data accordingly. Write to .json and get JSON. Write to .csv and get CSV. No manual serialization needed.

Supported Formats

Extension Format Description
.json JSON Pretty-printed JSON
.jsonl, .ndjson JSON Lines One JSON object per line
.yaml, .yml YAML Human-readable YAML
.toml TOML Configuration format
.xml XML Variable name as root element
.csv CSV Comma-separated with headers
.tsv TSV Tab-separated with headers
.md Markdown Markdown table
.html HTML HTML table
.txt Plain Text key=value pairs
.sql SQL INSERT statements
.log Log Date-prefixed entries
.env Environment KEY=VALUE format
.obj Binary Raw binary data

Writing to Different Formats

Same data, different formats - just change the extension:

<Create> the <users> with [
    { "id": 1, "name": "Alice", "email": "alice@example.com" },
    { "id": 2, "name": "Bob", "email": "bob@example.com" }
].

(* JSON - pretty printed *)
<Write> the <users> to "./output/users.json".

(* JSON Lines - one object per line, compact *)
<Write> the <users> to "./output/users.jsonl".

(* YAML - human readable *)
<Write> the <users> to "./output/users.yaml".

(* CSV - spreadsheet friendly *)
<Write> the <users> to "./output/users.csv".

(* XML - variable name becomes root element *)
<Write> the <users> to "./output/users.xml".

(* Markdown table *)
<Write> the <users> to "./docs/users.md".

(* SQL INSERT statements *)
<Write> the <users> to "./backup/users.sql".

(* Log file - date-prefixed entries *)
<Write> the <message> to "./app.log" with "Server started".
<Append> the <entry> to "./app.log" with "User logged in".

(* Environment file - uppercase keys with underscore nesting *)
<Write> the <config> to "./.env".

Reading with Format Detection

When reading, the extension determines how content is parsed:

(* JSON - parsed to object/array *)
<Read> the <config> from "./settings.json".

(* JSON Lines - parsed to array of objects *)
<Read> the <events> from "./logs/events.jsonl".

(* CSV - parsed to array with headers as keys *)
<Read> the <records> from "./data.csv".

(* YAML - parsed to object/array *)
<Read> the <settings> from "./config.yaml".

Bypassing Format Detection

Use the String qualifier to read raw content without parsing:

(* Read as raw string, no JSON parsing *)
<Read> the <raw-json: String> from "./data.json".

CSV/TSV Options

CSV and TSV support custom options:

(* Custom delimiter *)
<Write> the <data> to "./export.csv" with { delimiter: ";" }.

(* Without header row *)
<Write> the <data> to "./export.csv" with { header: false }.

(* Read with custom options *)
<Read> the <data> from "./import.csv" with { delimiter: ";", header: false }.
Option Type Default Description
delimiter String , / \t Field separator
header Boolean true Include/expect header row
quote String " Quote character

Multi-Format Export Pattern

A common pattern is exporting data to multiple formats:

(exportData: Export API) {
    <Retrieve> the <users> from the <user-repository>.

    (* Export to multiple formats *)
    <Write> the <users> to "./export/users.json".
    <Write> the <users> to "./export/users.csv".
    <Write> the <users> to "./export/users.yaml".
    <Write> the <users> to "./docs/users.md".

    <Return> an <OK: status> with "Exported to 4 formats".
}

Round-Trip Example

Read from one format, write to another:

(convertData: Data Conversion) {
    (* Read CSV input *)
    <Read> the <records> from "./input/data.csv".

    (* Write to JSON and YAML *)
    <Write> the <records> to "./output/data.json".
    <Write> the <records> to "./output/data.yaml".

    <Return> an <OK: status> for the <conversion>.
}

Deleting Files

<Delete> the <file: "./temp/cache.json">.
<Delete> the <file: path>.

Directory Operations

Listing Directory Contents

List all files in a directory:

<Create> the <uploads-path> with "./uploads".
<List> the <entries> from the <directory: uploads-path>.

Filter with glob patterns:

<Create> the <src-path> with "./src".
<List> the <aro-files> from the <directory: src-path> matching "*.aro".

List recursively:

<Create> the <project-path> with "./project".
<List> the <all-files> from the <directory: project-path> recursively.

Each entry contains:

  • name - file or directory name
  • path - full path
  • size - file size in bytes
  • isFile - true if file
  • isDirectory - true if directory
  • modified - last modification date

Checking Existence

Check if a file exists:

<Exists> the <found> for the <file: "./config.json">.

when <found> is false {
    <Log> "Config not found!" to the <console>.
}

Check if a directory exists:

<Exists> the <dir-exists> for the <directory: "./output">.

Creating Directories

Create a directory (including parent directories):

(* Natural syntax with "make" verb *)
<Make> the <directory> at the <path: "./output/reports/2024">.

(* Alternative syntax *)
<CreateDirectory> the <output-dir> to the <path: "./output/reports/2024">.

Getting File Stats

Get detailed metadata for a file:

<Stat> the <info> for the <file: "./document.pdf">.
<Log> <info: size> to the <console>.
<Log> <info: modified> to the <console>.

Get directory metadata:

<Stat> the <dir-info> for the <directory: "./src">.

Copying Files and Directories

Copy a file:

<Copy> the <file: "./template.txt"> to the <destination: "./copy.txt">.

Copy a directory (recursive by default):

<Copy> the <directory: "./src"> to the <destination: "./backup/src">.

Moving and Renaming

Rename a file:

<Move> the <file: "./draft.txt"> to the <destination: "./final.txt">.

Move to a different directory:

<Move> the <file: "./inbox/report.pdf"> to the <destination: "./archive/report.pdf">.

Move a directory:

<Move> the <directory: "./temp"> to the <destination: "./processed">.

Appending to Files

Append data to a file:

<Append> the <log-line> to the <file: "./logs/app.log">.

Creates the file if it doesn't exist.

File Watching

Starting a Watcher

Watch directories for changes using the <Watch> action:

(Application-Start: File Processor) {
    <Log> "Starting file processor" to the <console>.

    (* Watch the inbox directory for new files *)
    <Watch> the <file-monitor> for the <directory> with "./inbox".

    (* Keep running until shutdown *)
    <Keepalive> the <application> for the <events>.

    <Return> an <OK: status> for the <startup>.
}

Watch Syntax:

<Watch> the <file-monitor> for the <directory> with "path".

The <Watch> action:

  • Monitors the specified directory recursively
  • Emits events when files are created, modified, or deleted
  • Runs asynchronously (does not block execution)
  • Continues until application shutdown

File Events

Watchers emit events when files change:

Event When Triggered Data
FileCreatedEvent New file created path - file path
FileModifiedEvent Existing file modified path - file path
FileDeletedEvent File deleted path - file path

Event Handler Naming Convention

Feature sets with business activity File Event Handler receive file events. The feature set name determines which event type it handles:

Feature Set Name Handles Event
Handle File Created FileCreatedEvent
Handle File Modified FileModifiedEvent
Handle File Deleted FileDeletedEvent

Event Handler Examples

(* Handle new files *)
(Handle File Created: File Event Handler) {
    <Extract> the <path> from the <event: path>.
    <Log> "file created" to the <console>.
    <Return> an <OK: status> for the <event>.
}

(* Handle modified files *)
(Handle File Modified: File Event Handler) {
    <Extract> the <path> from the <event: path>.
    <Log> "file modified" to the <console>.
    <Return> an <OK: status> for the <event>.
}

(* Handle deleted files *)
(Handle File Deleted: File Event Handler) {
    <Extract> the <path> from the <event: path>.
    <Log> "file deleted" to the <console>.
    <Return> an <OK: status> for the <event>.
}

Common Patterns

Config Hot-Reload

(Application-Start: Hot Reload App) {
    (* Load initial config *)
    <Read> the <config: JSON> from the <file: "./config.json">.
    <Publish> as <app-config> <config>.

    (* Watch for config changes *)
    <Watch> the <file-monitor> for the <directory> with ".".

    <Start> the <http-server> on port <config: port>.
    <Wait> for <shutdown-signal>.
    <Return> an <OK: status> for the <startup>.
}

(Handle File Modified: File Event Handler) {
    <Extract> the <path> from the <event: path>.

    <Log> "Reloading configuration..." to the <console> when <path> is "./config.json".
    <Read> the <new-config: JSON> from the <file: "./config.json"> when <path> is "./config.json".
    <Publish> as <app-config> <new-config> when <path> is "./config.json".
    <Log> "Configuration reloaded" to the <console> when <path> is "./config.json".

    <Return> an <OK: status> for the <reload>.
}

File Upload Processing

(Application-Start: Upload Processor) {
    <Watch> the <file-monitor> for the <directory> with "./uploads".
    <Start> the <http-server> on port 8080.
    <Wait> for <shutdown-signal>.
    <Return> an <OK: status> for the <startup>.
}

(POST /upload: Upload API) {
    <Extract> the <file-data> from the <request: body>.
    <Extract> the <filename> from the <request: headers.filename>.

    <Write> the <file-data> to the <file: "./uploads/${filename}">.

    <Return> a <Created: status> with { filename: <filename> }.
}

(Handle File Created: File Event Handler) {
    <Extract> the <path> from the <event: path>.

    (* Only process files in uploads directory *)
    <Read> the <content> from the <file: path> when <path> starts with "./uploads/".
    <Transform> the <processed> from the <content> when <path> starts with "./uploads/".
    <Write> the <processed> to the <file: "./processed/${filename}"> when <path> starts with "./uploads/".
    <Delete> the <file: path> when <path> starts with "./uploads/".
    <Log> "Processed: ${path}" to the <console> when <path> starts with "./uploads/".

    <Return> an <OK: status> for the <processing>.
}

Log File Management

(Application-Start: Logging App) {
    (* Create log directory if needed *)
    <Write> the <header> to the <file: "./logs/app.log">.
    <Return> an <OK: status> for the <startup>.
}

(Log Event: ApplicationEvent Handler) {
    <Extract> the <event-type> from the <event: type>.
    <Extract> the <event-data> from the <event: data>.

    <Create> the <log-entry> with {
        timestamp: <current-time>,
        type: <event-type>,
        data: <event-data>
    }.

    <Store> the <log-entry: JSON> into the <file: "./logs/app.log">.
    <Return> an <OK: status> for the <logging>.
}

Batch File Processing

(Process Batch: Scheduled Task) {
    <List> the <files> from the <directory: "./inbox">.

    for each <file> in <files> {
        <Read> the <content> from the <file: file>.
        <Process> the <result> from the <content>.
        <Write> the <result> to the <file: "./outbox/${file.name}">.
        <Delete> the <file: file>.
    }

    <Return> an <OK: status> for the <batch>.
}

File Paths

Relative Paths

<Read> the <content> from the <file: "./config.json">.       (* Relative to app *)
<Read> the <content> from the <file: "../shared/data.json">. (* Parent directory *)

Absolute Paths

<Read> the <content> from the <file: "/etc/myapp/config.json">.

Path Construction

<Create> the <path> with "./uploads/${user-id}/${filename}".
<Write> the <data> to the <file: path>.

Best Practices

Always Handle Missing Files

(Load Data: Initialization) {
    <Read> the <data: JSON> from the <file: "./data.json">.

    (* Handle missing file *)
    <Create> the <data> with { items: [] } when <data> is empty.
    <Write> the <data: JSON> to the <file: "./data.json"> when <data> is empty.

    <Publish> as <app-data> <data>.
    <Return> an <OK: status> for the <loading>.
}

Validate File Types

(POST /upload: Upload API) {
    <Extract> the <filename> from the <request: headers.filename>.
    <Extract> the <content-type> from the <request: headers.Content-Type>.

    (* Validate file type *)
    when <content-type> is not "image/png" and <content-type> is not "image/jpeg" {
        <Return> a <BadRequest: status> for the <invalid: file-type>.
    }

    <Write> the <data> to the <file: "./uploads/${filename}">.
    <Return> a <Created: status> with { filename: <filename> }.
}

Use Appropriate Encodings

(* Text files *)
<Read> the <text> from the <file: "./data.txt">.

(* Binary files *)
<Read> the <binary: bytes> from the <file: "./image.png">.

(* JSON files *)
<Read> the <json: JSON> from the <file: "./config.json">.

Clean Up Temporary Files

(Process File: Temporary Processing) {
    <Read> the <input> from the <file: "./input.txt">.
    <Write> the <temp> to the <file: "./temp/processing.tmp">.

    <Process> the <result> from the <temp>.

    <Write> the <result> to the <file: "./output.txt">.
    <Delete> the <file: "./temp/processing.tmp">.

    <Return> an <OK: status> for the <processing>.
}

Next Steps

Home

Getting Started

Language Guide

Fundamentals

Runtime & Events

I/O & Communication

Advanced

Language Reference

Extending ARO

Clone this wiki locally