Language Specifications
The ARO language is documented through 67 numbered specifications that cover everything from core syntax to native compilation.
Reading Order
For newcomers to ARO, we recommend reading the specifications in order. Each builds on concepts from the previous ones.
Language Specifications
These documents define the complete ARO language.
| # | Specification | Topics |
|---|---|---|
| 0001 | Language Fundamentals | Core syntax, literals, expressions, variable scoping |
| 0002 | Control Flow | When guards, match expressions, iteration, collections |
| 0003 | Type System | Types, OpenAPI integration, contract-first APIs |
| 0004 | Actions | Action roles, built-in actions, custom extensions |
| 0005 | Application Architecture | App structure, lifecycle, concurrency model |
| 0006 | Error Philosophy | "Code is the error message" approach |
| 0007 | Events & Reactive | Event dispatch, state machines, repositories |
| 0008 | I/O Services | HTTP server/client, file system, sockets |
| 0009 | Native Compilation | LLVM code generation, aro build command |
| 0010 | Advanced Features | Regular expressions, date/time, system exec |
| 0011 | HTML/XML Parsing | Parse action for HTML and XML documents |
| 0014 | Domain Modeling | DDD patterns: entities, value objects, aggregates |
| 0015 | Testing Framework | BDD-style testing with Given/When/Then |
| 0016 | Interoperability | Foreign function interface, plugins, database integration |
| 0018 | Data Pipelines | Filter, Map, Reduce operations on collections |
| 0019 | Standard Library | Primitive types, core utilities |
| 0022 | State Guards | Event handler filtering with field:value syntax |
| 0030 | IDE Integration | Syntax highlighting, editor support |
| 0031 | Context-Aware Formatting | Adaptive output for machine/human/developer |
| 0034 | Language Server Protocol | LSP implementation for IDE features |
| 0035 | Configurable Runtime | Configure action for timeouts and settings |
| 0036 | Extended File Operations | Exists, Stat, Make, Copy, Move actions |
| 0037 | Regex Split | Split action with regex delimiters |
| 0038 | List Element Access | first, last, index, range specifiers |
| 0040 | Format-Aware I/O | Auto format detection for JSON, YAML, CSV, etc. |
| 0041 | Date/Time Ranges | Date arithmetic, ranges, recurrence patterns |
| 0042 | Set Operations | intersect, difference, union on collections |
| 0043 | Sink Syntax | Expressions in result position |
| 0044 | Runtime Metrics | Execution counts, timing, Prometheus format |
| 0045 | Package Manager | Plugin installation, aro add/remove, dependency resolution |
| 0046 | Typed Event Extraction | Schema-validated event data extraction |
| 0047 | Command-Line Parameters | CLI argument parsing, Parameters action |
| 0048 | WebSocket | WebSocket server support, real-time messaging |
| 0049 | Interactive REPL | Read-eval-print loop, plugin management commands |
| 0050 | Template Engine | Mustache-style templates, Render action |
| 0051 | Streaming Execution | Lazy evaluation, Stream Tee, Aggregation Fusion |
| 0073 | Store Files | File-backed repositories, YAML seed data, permission-based writability |
| 0080 | Git Actions | Native Git via libgit2: status, stage, commit, push, pull, clone, checkout, tag |
| 0081 | User-Defined Actions | Define custom actions in ARO source files |
| 0082 | Numeric Separators | Underscores in decimal literals for readable large numbers |
| 0083 | Terminal UI | Terminal user-interface system for interactive console applications |
| 0084 | Local LLM | Local language-model integration (superseded by aro ask) |
| 0085 | Terminal Shadow Buffer | Terminal shadow-buffer rendering optimization (draft) |
| 0086 | Automatic Pipeline Detection | Implicit detection of streaming pipelines across statements |
| 0087 | Plugin SDK | Plugin SDK and developer experience across Swift, Rust, C, and Python |
| 0088 | Concurrency Model | What runs concurrently: deferral, forcing, parallel for each, ordered effects |
| 0089 | Ranges | 1->10 as a value, both ends included; the for each collection slot iterates one in O(1) memory |
| 0090 | Streaming I/O | Request bodies that stream vs. become values; per-route size limits |
| 0091 | Jupyter Kernel | Machine-readable REPL protocol, native ZMQ kernel, notebooks, widgets, debugging |
| 0092 | aro ask Assistant |
Local model inside the binary, tool registry, approval model, .context |
| 0094 | Caller-Scoped Repositories | A repository belongs to a caller: application, session or connection scope |
Runtime & Compiler Internals
These proposals specify how the implementation works rather than what the
language does. They are here because an ARO-NNNN reference in the
source should always resolve to something you can read.
| # | Proposal | Topics |
|---|---|---|
| 0052 | Unified URL I/O | One I/O surface for files, HTTP URLs and streams |
| 0053 | Lexer Lookup Optimization | Keyword, article and preposition recognition |
| 0054 | Execution Engine Refactor | Restructuring the interpreter's core |
| 0055 | Lexer Reserved Words | Faster reserved-word recognition |
| 0056 | Numeric Literal Underscores | Superseded by 0082 |
| 0057 | Lexer peekNext Cache |
Tokenization performance |
| 0059 | Structured Logging | JSON-shaped log records |
| 0060 | Raw String Literals | Verbatim string syntax |
| 0061 | AST Visitor Pattern | Traversal abstraction over the AST |
| 0062 | Dead Code Detection | Unreachable feature-set warnings |
| 0063 | Value-Type AST Nodes | Sendable AST representation |
| 0064 | Event Subscription Matching | Cheaper subscription lookup |
| 0067 | Pipeline Operator | Explicit pipelines (see also 0086) |
| 0068 | Extract Within Case | Pattern-style extraction inside match |
| 0069 | Async Plugin Compilation | Parallel plugin builds |
| 0070 | LLVM Expression Optimization | Native codegen improvements |
| 0071 | Type Narrowing | Flow-sensitive type refinement in branches |
| 0072 | Binary Socket & File Events | Binary payload event handlers in compiled mode |
Contributing
Want to propose a new feature? Open an issue on GitHub with your idea and we'll discuss whether it should become a formal specification.