Core Language Specification

rill is an embeddable, sandboxed scripting language designed for AI agents.

Experimental. Active development. Breaking changes will occur before stabilization.

Overview

rill is an imperative scripting language that is dynamically typed and type-safe. Types are checked at runtime, but type errors are always caught—there are no implicit conversions. Type annotations are optional, but variables lock their type on first assignment. The language is value-based: no references, all copies are deep, all comparisons are by value. Empty values are valid (empty strings, lists, dicts), but null and undefined do not exist. Control flow is singular: no exceptions, no try/catch. Data flows through pipes (->), not assignment.

Design Principles

For design principles, see Design Principles.

Quick Reference Tables

Expression Delimiters

Operators

See Operators for detailed documentation.

Control Flow

See Control Flow for detailed documentation. Script-level exit functions must be host-provided.

Collection Operators

See Collections for detailed documentation.

Types

See Types for detailed documentation.

Functions

See Closures for detailed documentation.

Special Variables

See Variables for detailed documentation.

$ Binding by Context

Property Access

Dispatch

Pipe a value to a collection (dict or list) to retrieve the corresponding element.

Dict Dispatch: Match keys and return associated values.

$value -> [apple: "fruit", carrot: "vegetable"]  # Returns "fruit" if $value is "apple"
$value -> [apple: "fruit"] ?? "not found"        # Returns "not found" if no match
$method -> [["GET", "HEAD"]: "safe", ["POST", "PUT"]: "unsafe"]  # Multi-key dispatch

Type-Aware Dispatch: Keys match by both value and type.

Dict keys can be identifiers, numbers, or booleans. Multi-key syntax [k1, k2]: value maps multiple keys to the same value.

Hierarchical Dispatch: Navigate nested structures using a path list.

Path element types: string keys for dict lookup, number indexes for list access (negative indexes supported). Type mismatch throws RUNTIME_TYPE_ERROR.

Terminal closures receive $ bound to the final path key.

["name", "first"] -> [name: [first: "Alice"]]              # "Alice" (dict path)
[0, 1] -> [[1, 2, 3], [4, 5, 6]]                           # 2 (list path)
["users", 0, "name"] -> [users: [[name: "Alice"]]]         # "Alice" (mixed path)
["req", "draft"] -> [req: [draft: { "key={$}" }]]          # "key=draft" (terminal closure)

List Dispatch: Index into a list using a number.

0 -> ["first", "second", "third"]     # "first"
1 -> ["first", "second", "third"]     # "second"
-1 -> ["first", "second", "third"]    # "third" (last element)
5 -> ["a", "b"] ?? "not found"        # "not found" (out of bounds)

Variable Dispatch: Use stored collections.

[apple: "fruit", carrot: "vegetable"] => $lookup
"apple" -> $lookup                    # "fruit"

["a", "b", "c"] => $items
1 -> $items                           # "b"

Error Messages:

Core Methods

See Strings for detailed string method documentation.

Global Functions

See Iterators for range and repeat documentation.

Implied $

When constructs appear without explicit input, $ is used implicitly:

Extraction Operators

Destructure *<>

Extract elements from lists or dicts into variables:

[1, 2, 3] -> *<$a, $b, $c>
# $a = 1, $b = 2, $c = 3

[name: "test", count: 42] -> *<name: $n, count: $c>
# $n = "test", $c = 42

Slice /<>

Extract portions using Python-style start:stop:step:

[0, 1, 2, 3, 4] -> /<0:3>        # [0, 1, 2]
[0, 1, 2, 3, 4] -> /<-2:>        # [3, 4]
[0, 1, 2, 3, 4] -> /<::-1>       # [4, 3, 2, 1, 0]
"hello" -> /<1:4>                # "ell"

See Operators for detailed extraction operator documentation.

Annotation Reflection

Access annotation values on closures using .^key syntax.

Type Restriction: Annotations attach to closures only. Accessing .^key on primitives (string, number, boolean, list, dict) throws RUNTIME_TYPE_ERROR.

^(min: 0, max: 100) |x|($x) => $fn

$fn.^min     # 0
$fn.^max     # 100
$fn.^missing # Error: RUNTIME_UNDEFINED_ANNOTATION

Annotations are metadata attached to closures during creation. They enable runtime configuration and introspection.

Common Use Cases

Function Metadata:

^(doc: "validates user input", version: 2) |input|($input) => $validate

$validate.^doc      # "validates user input"
$validate.^version  # 2

Configuration Annotations:

^(timeout: 30000, retry: 3) |url|($url) => $fetch

$fetch.^timeout  # 30000
$fetch.^retry    # 3

Complex Annotation Values:

^(config: [timeout: 30, endpoints: ["a", "b"]]) |x|($x) => $fn

$fn.^config.timeout      # 30
$fn.^config.endpoints[0] # "a"

Error Handling

Accessing undefined annotation keys throws RUNTIME_UNDEFINED_ANNOTATION:

|x|($x) => $fn
$fn.^missing   # Error: Annotation 'missing' not defined

Use default value operator for optional annotations:

|x|($x) => $fn
$fn.^timeout ?? 30  # 30 (uses default since annotation missing)

Accessing .^key on non-closure values throws RUNTIME_TYPE_ERROR:

"hello" => $str
$str.^key        # Error: Cannot access annotation on string

Parameter Annotations

Parameters can have their own annotations using ^(key: value) syntax. These attach metadata to individual parameters.

Syntax: |paramName ^(annotation: value)| body

Order: Parameter annotations appear after the type annotation (if present) and before the default value (if present).

|x: number ^(min: 0, max: 100)|($x) => $validate
|name: string ^(required: true) = "guest"|($name) => $greet
|count ^(cache: true) = 0|($count) => $process

Access via .params:

The .params property returns a dict keyed by parameter name. Each entry is a dict containing:

• type — Type annotation (string) if present
• __annotations — Dict of parameter-level annotations if present

|x: number ^(min: 0, max: 100), y: string|($x + $y) => $fn

$fn.params
# Returns:
# [
#   x: [type: "number", __annotations: [min: 0, max: 100]],
#   y: [type: "string"]
# ]

$fn.params.x.__annotations.min  # 0
$fn.params.y.?__annotations     # false (no annotations on y)

Use Cases:

# Validation metadata
|value ^(min: 0, max: 100)|($value) => $bounded

# Caching hints
|key ^(cache: true)|($key) => $fetch

# Format specifications
|timestamp ^(format: "ISO8601")|($timestamp) => $formatDate

See Closures for parameter annotation examples and patterns.

Tuples

Tuples package values for argument unpacking:

|a, b, c|"{$a}-{$b}-{$c}" => $fmt
*[1, 2, 3] -> $fmt()             # "1-2-3"
*[c: 3, a: 1, b: 2] -> $fmt()    # "1-2-3" (named)

See Types for detailed tuple documentation.

Runtime Limits

Iteration Limits

Loops have a default maximum of 10,000 iterations. Override with ^(limit: N):

^(limit: 100) 0 -> ($ < 50) @ { $ + 1 }

Concurrency Limits

The ^(limit: N) annotation also controls parallel concurrency in map:

^(limit: 3) $items -> map { slow_process($) }

See Host Integration for timeout and cancellation configuration.

Host-Provided Functions

rill is a vanilla language. The host application registers domain-specific functions via RuntimeContext:

const ctx = createRuntimeContext({
  functions: {
    prompt: async (args) => await callLLM(args[0]),
    'io::read': async (args) => fs.readFile(String(args[0]), 'utf-8'),
  },
  variables: {
    config: { apiUrl: 'https://api.example.com' },
  },
});

Scripts call these as prompt("text") or io::read("file.txt").

See Host Integration for complete API documentation.

Script Frontmatter

Optional YAML frontmatter between --- markers. Frontmatter is opaque to rill—the host interprets it:

---
timeout: 00:10:00
args: file: string
---

process($file)

Script Return Values

Scripts return their last expression:

Comments

Single-line comments start with #:

# This is a comment
"hello"  # inline comment

Grammar

The complete formal grammar is in grammar.ebnf.

Error Codes

Runtime and parse errors include structured error codes for programmatic handling.

See Host Integration for error handling details.

See Also

For detailed documentation on specific topics:

• Types — Type system, type assertions
• Variables — Declaration, scope, $ binding
• Control Flow — Conditionals, loops
• Operators — All operators
• Closures — Late binding, dict closures
• Collections — each, map, filter, fold
• Iterators — range, repeat, .first()
• Strings — String methods
• Host Integration — Embedding API