File Operations

Reading and Writing Files

Read Files

(* Read text file *)
Read the <content> from the <file: "./README.md">.

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

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

Write Files

(* Write text - creates parent directories automatically *)
Write the <report> to the <file: "./output/report.txt">.

(* Write JSON *)
Write the <data: JSON> to the <file: "./export.json">.

Append to Files

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

Directory Operations

List Directory Contents

(* List all entries — `from`, like every other REQUEST action *)
List the <entries> from the <directory: "./uploads">.

(* Filter with a glob pattern *)
List the <aro-files> from the <directory: "./src"> matching "*.aro".

(* List recursively *)
List the <all-files> from the <directory: "./project"> recursively.

Each entry includes:

• name - file or directory name
• path - full path
• size - size in bytes
• isFile / isDirectory - type flags
• modified - last modification date

Check Existence

(* Check if file exists *)
Exists the <found> for the <file: "./config.json">.

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

(* Check if directory exists *)
Exists the <dir-exists> for the <directory: "./output">.

Create Directories

(* Create directory with all parent directories *)
CreateDirectory the <output-dir> to the <path: "./output/reports/2024">.

Get File Metadata

(* Get detailed file stats *)
Stat the <info> for the <file: "./document.pdf">.

Log <info: size> to the <console>.
Log <info: modified> to the <console>.

Copy and Move

Copy Files

(* 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">.

Move and Rename

(* Rename a file *)
Move the <file: "./draft.txt"> to the <destination: "./final.txt">.

(* Move to different directory *)
Move the <file: "./inbox/report.pdf"> to the <destination: "./archive/report.pdf">.

Complete Example

Here's a complete example that demonstrates file operations:

(Application-Start: File Operations Demo) {
    Log "=== File Operations ===" to the <console>.

    (* Check and create the output directory *)
    Exists the <dir-exists> for the <directory: "./demo-output">.

    when <dir-exists> is false {
        Make the <output-dir> at the <directory: "./demo-output">.
        Log "Created directory" to the <console>.
    }

    (* Write a file *)
    Write the <content> to the <file: "./demo-output/hello.txt">
        with "Hello from ARO!".

    (* Append to it *)
    Append the <line> to the <file: "./demo-output/hello.txt">
        with "Appended line.".

    (* Get stats — interpolation takes a plain name, so extract first *)
    Stat the <info> for the <file: "./demo-output/hello.txt">.
    Extract the <size> from the <info: size>.
    Log "Size: ${size} bytes" to the <console>.

    (* Copy and list *)
    Copy the <backup> to the <file: "./demo-output/hello.bak">.
    List the <entries> from the <directory: "./demo-output">.
    Log <entries> to the <console>.

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

Path Qualifiers

Paths are taken apart and put together with Compute qualifiers (ARO-0036 §9). All of them are pure functions — none touches the filesystem, so they answer the same way for a path that does not exist:

Three rules are worth knowing before you rely on them:

• extension has no dot, and a dotfile is a name rather than an extension.
• dirname of a bare filename is ".".
• An absolute right-hand component does not reset the path. path-join of /uploads and /etc/passwd is /uploads/etc/passwd — deliberately unlike Python, because the call it exists for is joining a trusted directory to an untrusted name.

Permissions and Timestamps

Configure sets a file's mode and binds { path, permissions, octal, previous }. Octal and the symbolic form Stat prints are both accepted, so a mode read off one file applies to another:

Configure the <mode> for the <file: "./run.sh"> with { permissions: "755" }.

Touch creates the file, or stamps it if it is already there:

Touch the <marker> for the <file: "./build.stamp">.

Actions Reference