# 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 ```aro the from the . the from the . ``` ### JSON Files ```aro the from the . the from the . ``` ### Binary Files ```aro the from the . the from the . ``` ### Dynamic Paths ```aro (GET /files/{name}: File API) { the from the . the from the . an with . } ``` ### Error Handling ```aro (Load Config: Configuration) { the from the . "Config not found, using defaults" to the when is empty. the with { port: 8080, debug: false } when is empty. as . an for the . } ``` ## Writing Files ### Text Files ```aro the to the . the to the . ``` ### JSON Files ```aro the to the . the to the . ``` ### Appending ```aro the into the . the into the . ``` ### Creating Directories Directories are created automatically when writing: ```aro (* ./reports/2024/01/ is created if it doesn't exist *) the to the . ``` ## 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: ```aro the with [ { "id": 1, "name": "Alice", "email": "alice@example.com" }, { "id": 2, "name": "Bob", "email": "bob@example.com" } ]. (* JSON - pretty printed *) the to "./output/users.json". (* JSON Lines - one object per line, compact *) the to "./output/users.jsonl". (* YAML - human readable *) the to "./output/users.yaml". (* CSV - spreadsheet friendly *) the to "./output/users.csv". (* XML - variable name becomes root element *) the to "./output/users.xml". (* Markdown table *) the to "./docs/users.md". (* SQL INSERT statements *) the to "./backup/users.sql". (* Log file - date-prefixed entries *) the to "./app.log" with "Server started". the to "./app.log" with "User logged in". (* Environment file - uppercase keys with underscore nesting *) the to "./.env". ``` ### Reading with Format Detection When reading, the extension determines how content is parsed: ```aro (* JSON - parsed to object/array *) the from "./settings.json". (* JSON Lines - parsed to array of objects *) the from "./logs/events.jsonl". (* CSV - parsed to array with headers as keys *) the from "./data.csv". (* YAML - parsed to object/array *) the from "./config.yaml". ``` ### Bypassing Format Detection Use the `String` qualifier to read raw content without parsing: ```aro (* Read as raw string, no JSON parsing *) the from "./data.json". ``` ### CSV/TSV Options CSV and TSV support custom options: ```aro (* Custom delimiter *) the to "./export.csv" with { delimiter: ";" }. (* Without header row *) the to "./export.csv" with { header: false }. (* Read with custom options *) the 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: ```aro (exportData: Export API) { the from the . (* Export to multiple formats *) the to "./export/users.json". the to "./export/users.csv". the to "./export/users.yaml". the to "./docs/users.md". an with "Exported to 4 formats". } ``` ### Round-Trip Example Read from one format, write to another: ```aro (convertData: Data Conversion) { (* Read CSV input *) the from "./input/data.csv". (* Write to JSON and YAML *) the to "./output/data.json". the to "./output/data.yaml". an for the . } ``` ## Deleting Files ```aro the . the . ``` ## Directory Operations ### Listing Directory Contents List all files in a directory: ```aro the with "./uploads". the from the . ``` Filter with glob patterns: ```aro the with "./src". the from the matching "*.aro". ``` List recursively: ```aro the with "./project". the from the 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: ```aro the for the . when is false { "Config not found!" to the . } ``` Check if a directory exists: ```aro the for the . ``` ### Creating Directories Create a directory (including parent directories): ```aro (* Natural syntax with "make" verb *) the at the . (* Alternative syntax *) the to the . ``` ### Getting File Stats Get detailed metadata for a file: ```aro the for the . to the . to the . ``` Get directory metadata: ```aro the for the . ``` ### Copying Files and Directories Copy a file: ```aro the to the . ``` Copy a directory (recursive by default): ```aro the to the . ``` ### Moving and Renaming Rename a file: ```aro the to the . ``` Move to a different directory: ```aro the to the . ``` Move a directory: ```aro the to the . ``` ### Appending to Files Append data to a file: ```aro the to the . ``` Creates the file if it doesn't exist. ## File Watching ### Starting a Watcher Watch directories for changes using the `` action: ```aro (Application-Start: File Processor) { "Starting file processor" to the . (* Watch the inbox directory for new files *) the for the with "./inbox". (* Keep running until shutdown *) the for the . an for the . } ``` **Watch Syntax:** ```aro the for the with "path". ``` The `` 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 ```aro (* Handle new files *) (Handle File Created: File Event Handler) { the from the . "file created" to the . an for the . } (* Handle modified files *) (Handle File Modified: File Event Handler) { the from the . "file modified" to the . an for the . } (* Handle deleted files *) (Handle File Deleted: File Event Handler) { the from the . "file deleted" to the . an for the . } ``` ## Common Patterns ### Config Hot-Reload ```aro (Application-Start: Hot Reload App) { (* Load initial config *) the from the . as . (* Watch for config changes *) the for the with ".". the on port . for . an for the . } (Handle File Modified: File Event Handler) { the from the . "Reloading configuration..." to the when is "./config.json". the from the when is "./config.json". as

when is "./config.json". "Configuration reloaded" to the when is "./config.json". an for the . } ``` ### File Upload Processing ```aro (Application-Start: Upload Processor) { the for the with "./uploads". the on port 8080. for . an for the . } (POST /upload: Upload API) { the from the . the from the . the to the . a with { filename: }. } (Handle File Created: File Event Handler) { the from the . (* Only process files in uploads directory *) the from the when starts with "./uploads/". the from the when starts with "./uploads/". the to the when starts with "./uploads/". the when starts with "./uploads/". "Processed: ${path}" to the when starts with "./uploads/". an for the . } ``` ### Log File Management ```aro (Application-Start: Logging App) { (* Create log directory if needed *) the

to the . an for the . } (Log Event: ApplicationEvent Handler) { the from the . the from the . the with { timestamp: , type: , data: }. the into the . an for the . } ``` ### Batch File Processing ```aro (Process Batch: Scheduled Task) { the from the . for each in { the from the . the from the . the to the . the . } an for the . } ``` ## File Paths ### Relative Paths ```aro the from the . (* Relative to app *) the from the . (* Parent directory *) ``` ### Absolute Paths ```aro the from the . ``` ### Path Construction ```aro the with "./uploads/${user-id}/${filename}". the to the . ``` ## Best Practices ### Always Handle Missing Files ```aro (Load Data: Initialization) { the from the . (* Handle missing file *) the with { items: [] } when is empty. the to the when is empty. as . an for the . } ``` ### Validate File Types ```aro (POST /upload: Upload API) { the from the . the from the . (* Validate file type *) when is not "image/png" and is not "image/jpeg" { a for the . } the to the . a with { filename: }. } ``` ### Use Appropriate Encodings ```aro (* Text files *) the