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.

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