The Basics

Source Files

ARO source files use the .aro extension. An application is a directory containing one or more .aro files:

MyApp/
├── openapi.yaml    # Required for HTTP server
├── main.aro
├── users.aro
└── events.aro

All files in the directory are automatically compiled together. No import statements needed.

For larger projects, you can organize files in subdirectories. The sources/ convention provides clean separation:

MyApp/
├── openapi.yaml    # Configuration in root
├── main.aro        # Entry point
└── sources/        # Source files subdirectory
    ├── users/
    │   └── users.aro
    └── orders/
        └── orders.aro

Files can be nested to any depth. The runtime discovers all .aro files recursively.

Comments

ARO uses Pascal-style block comments:

(* This is a comment *)

(*
   Multi-line comments
   are also supported
*)

(* Comments can contain (* nested comments *) *)

Feature Sets

A feature set is the primary organizational unit in ARO. It groups related statements that accomplish a business goal:

(Feature Name: Business Activity) {
    (* statements go here *)
}

Example

(Validate User Credentials: Authentication) {
    Extract the <username> from the <request: body username>.
    Extract the <password> from the <request: body password>.
    Retrieve the <user> from the <user-repository> where username = <username>.
    Compare the <password> against the <user: passwordHash>.
    Return an <OK: status> with <user>.
}

Statements

Every statement follows the Action-Result-Object pattern:

Action [article] <result> preposition [article] <object> [modifiers].

Every statement ends with a period (.).

Variables

Variables are denoted with angle brackets and hold values during execution.

Simple Variables

<user>
<order>
<total>

Qualified Variables

Add context with a colon and qualifier:

<user: id>           (* The id property of user *)
<request: body>      (* The body of the request *)
<order: lineItems>   (* The lineItems of an order *)

Compound Names

<user-id>
<order-total>
<customer-email>

Prepositions

Prepositions define the relationship between result and object:

Literals

String Literals

Log "Hello, World!" to the <console>.

String Interpolation

Create the <greeting> with "Hello, ${user-name}!".

Object Literals

Create the <user> with {
    name: "John Doe",
    email: "john@example.com",
    role: "admin"
}.

Special Feature Sets

Application-Start

The required entry point:

(Application-Start: My Application) {
    (* Initialization code *)
    Return an <OK: status> for the <startup>.
}

Application-End

Optional exit handlers:

(Application-End: Success) {
    (* Cleanup on graceful shutdown *)
    Return an <OK: status> for the <shutdown>.
}

(Application-End: Error) {
    (* Cleanup on error *)
    Return an <OK: status> for the <error-handling>.
}

Event Handlers

Feature sets with "Handler" in the business activity:

(Send Email: UserCreated Handler) { ... }
(Process File: FileCreated Handler) { ... }
(Log Connection: ClientConnected Handler) { ... }

Reserved Words

The following words have special meaning in ARO:

• Articles: a, an, the
• Prepositions: from, to, for, with, into, against, via, on, as
• Control Flow: if, then, else, when, where, and, or, not, is
• Status: OK, Created, NoContent, BadRequest, NotFound, Forbidden