RILL LANGUAGE REFERENCE FOR LLM AGENTS
=======================================

Rill is a pipe-based scripting language. Data flows through pipes (->), not assignment (=).

NAMING CONVENTION: snake_case
-----------------------------
Use snake_case for all identifiers:
  $user_name, $item_list, $is_valid    # variables
  $double_value, $cleanup_text         # closures
  [first_name: "x", last_name: "y"]    # dict keys

SPACING RULES
-------------
Operators:    space both sides       5 + 3, $x -> .upper, "a" :> $b
Parentheses:  no inner space         ($x + 1), ($ > 3) ? "yes"
Braces:       space inside           { $x + 1 }, each { $ * 2 }
Brackets:     no inner space         $list[0], $dict.items[1]
Literals:     space after , and :    [1, 2, 3], [name: "x", age: 30]
Closures:     space after params     |x| ($x * 2), |a, b| { $a + $b }
Methods:      no space before . or ( $str.upper(), $list.join(", ")
Pipes:        space both sides       "x" -> .upper -> .len
Continuations: indent 2 spaces       $data
                                       -> .filter { $.active }
                                       -> map { $.name }

IMPLICIT $ SHORTHAND (always prefer)
------------------------------------
$.method()  ->  .method            "x" -> .upper  (not $.upper())
func($)     ->  func               "x" -> log     (not log($))
$fn($)      ->  $fn                5 -> $double   (not $double($))

NO THROWAWAY CAPTURES
---------------------
Don't capture just to continue - use line continuation instead:
  # avoid                          # good
  "x" :> $a                        "x"
  $a -> .upper :> $b                 -> .upper
  $b -> .len                         -> .len

Only capture when the variable is reused later in the code.

CRITICAL DIFFERENCES FROM MAINSTREAM LANGUAGES
----------------------------------------------

1. NO ASSIGNMENT OPERATOR
   Wrong: x = 5
   Right: 5 :> $x

   Pipe (->): passes value to next operation
   Capture (:>): stores value AND continues chain
   Example: "hello" :> $x -> .upper :> $y   # $x="hello", $y="HELLO"

2. NO NULL/UNDEFINED
   Empty values ("", [], [:]) exist. "No value" cannot be represented.
   Use ?? for defaults: $dict.field ?? "default"
   Use .empty to check: $str -> .empty ? "was empty"

3. NO TRUTHINESS
   Conditions MUST be boolean. No implicit coercion.
   Wrong: "" ? "yes" ! "no"
   Right: "" -> .empty ? "yes" ! "no"
   Wrong: 0 ? "yes" ! "no"
   Right: (0 == 0) ? "yes" ! "no"

4. VARIABLES LOCK TO FIRST TYPE
   "hello" :> $x
   42 :> $x        # ERROR: cannot assign number to string variable

5. NO VARIABLE SHADOWING (CRITICAL FOR LOOPS)
   Child scopes can READ parent variables but cannot WRITE or redeclare them.
   Variables created inside blocks/loops do NOT leak out.

   WRONG - this pattern NEVER works:
     0 :> $count
     [1, 2, 3] -> each { $count + 1 :> $count }  # creates LOCAL $count
     $count                                       # still 0!

   RIGHT - use $ or $@ as state carrier (see LOOP STATE PATTERNS below)

6. NO EXCEPTIONS
   Errors halt execution. No try/catch. Use conditionals for error handling.
   Script-level exit functions (error, stop) must be host-provided.

SYNTAX QUICK REFERENCE
----------------------

Variables:     $name (always prefixed with $)
Strings:       "hello {$var}"          # interpolation with {}
               """..."""               # multiline (also interpolates)
Numbers:       42, 3.14, -7
Booleans:      true, false
Lists:         [1, 2, 3]
Dicts:         [name: "alice", age: 30]
Tuples:        *[1, 2, 3]              # for argument unpacking
Closures:      |x|($x + 1)             # like lambda/arrow functions
Comments:      # single line only

PIPES AND $ BINDING
-------------------

$ is the current piped value. Its meaning depends on context:

| Context                    | $ contains              |
|----------------------------|-------------------------|
| -> { body }                | piped value             |
| -> each { }                | current item            |
| (cond) @ { }               | accumulated value       |
| @ { } ? cond               | accumulated value       |
| cond ? { } ! { }           | tested value            |
| -> ? { } ! { }             | piped value             |
| ||{ $.field } in dict      | the containing dict     |
| |x|{ } stored closure      | N/A - use parameters    |

Implied $: bare .method() means $ -> .method()
Example: "hello" -> .upper   # same as "hello" -> $.upper()

CONTROL FLOW
------------

Conditional (if-else):
  cond ? then_expr ! else_expr
  cond ? then_expr                    # else returns ""

Piped conditional ($ becomes condition):
  value -> ? then_expr ! else_expr

Condition loop (NO "while" keyword - use @ operator):
  init_value -> ($ < 10) @ { $ + 1 }  # $ is accumulator

Do-condition loop (body runs at least once):
  init_value -> @ { $ + 1 } ? ($ < 10)

Break (exits loop, returns collected results before break):
  [1,2,3,4,5] -> each { ($ == 3) ? break; $ }  # returns [1, 2]

Return (exits block or script with value):
  { 5 :> $x; ($x > 3) ? ("big" -> return); "small" }  # returns "big"
  "done" -> return                                     # exits script with "done"

LOOP STATE PATTERNS (CRITICAL)
------------------------------
Rill loops CANNOT modify outer variables. All state must flow through $ or $@.

WRONG - outer variable modification (NEVER works):
  0 :> $sum
  [1, 2, 3] -> each { $sum + $ :> $sum }  # $sum unchanged!

WRONG - "while" keyword does not exist:
  while ($i < 10) { $i + 1 :> $i }        # SYNTAX ERROR

RIGHT - use fold for reduction:
  [1, 2, 3] -> fold(0) { $@ + $ }         # 6 ($@ is accumulator)

RIGHT - use each(init) when you need both results AND accumulator:
  [1, 2, 3] -> each(0) { $@ + $ }         # [1, 3, 6] (running totals)

RIGHT - use (cond) @ { } with $ as state dict for multiple values:
  [iter: 0, max: 3, text: $input, done: false]
    -> (!$.done && $.iter < $.max) @ {
      $.iter + 1 :> $i
      process($.text) :> $result
      $result.finished ? [iter: $i, max: $.max, text: $.text, done: true]
                       ! [iter: $i, max: $.max, text: $result.text, done: false]
    }
  # Access final state: $.text, $.iter

Pattern summary:
  - Single value accumulation     -> fold(init) { $@ + $ }
  - Per-item results + running    -> each(init) { ... $@ ... }
  - Multiple state values / while -> (cond) @ { } with $ as state dict
  - "while" and "for" keywords    -> DO NOT EXIST

COLLECTION OPERATORS
--------------------

| Operator           | Execution  | Returns              | Break? |
|--------------------|------------|----------------------|--------|
| -> each { }        | sequential | all body results     | yes    |
| -> each(i) { $@+$} | sequential | all with accumulator | yes    |
| -> map { }         | parallel   | all body results     | NO     |
| -> filter { }      | parallel   | matching elements    | NO     |
| -> fold(i) { $@+$} | sequential | final result only    | yes    |

$@ is the accumulator in each(init) and fold(init).

Method shorthand in collection operators:
  ["a", "b"] -> map .upper            # ["A", "B"]
  ["", "x"] -> filter (!.empty)       # ["x"]

CLOSURES
--------

Definition:
  |x|($x + 1) :> $inc                 # single param
  |a, b|($a + $b) :> $add             # multiple params
  |x = 0|($x + 1) :> $inc_or_one      # default value
  |x: number|($x + 1) :> $typed       # type annotation

Invocation:
  $inc(5)                             # direct call: 6
  5 -> $inc()                         # piped call: 6
  [1,2,3] -> map $inc                 # in collection op

LATE BINDING: closures capture scope, not values. Variables resolve at call time.

Dict closures (methods):
  [count: 3, double: ||{ $.count * 2 }] :> $obj
  $obj.double                         # 6 ($ is bound to dict)

PROPERTY ACCESS
---------------

$data.field                           # dict field
$data[0], $data[-1]                   # list index (negative from end)
$data.$key                            # variable as key
$data.($i + 1)                        # computed key
$data.(a || b)                        # try keys left-to-right
$data.field ?? "default"              # default if missing
$data.?field                          # existence check (boolean)
$data.?field&string                   # existence AND type check

TYPE OPERATIONS
---------------

:type   - assert type (error if wrong): 42:number passes; "x":number errors
:?type  - check type (boolean): 42:?number is true; "x":?number is false

Types: string, number, boolean, list, dict, tuple, closure

EXTRACTION OPERATORS
--------------------

Destructure (*<>):
  [1, 2, 3] -> *<$a, $b, $c>          # $a=1, $b=2, $c=3
  [x: 1, y: 2] -> *<x: $a, y: $b>     # $a=1, $b=2
  [1, 2, 3] -> *<$first, _, $third>   # _ skips element

Slice (/<start:stop:step>):
  [0,1,2,3,4] -> /<1:3>               # [1, 2]
  [0,1,2,3,4] -> /<-2:>               # [3, 4]
  [0,1,2,3,4] -> /<::-1>              # [4,3,2,1,0] (reverse)
  "hello" -> /<1:4>                   # "ell"

TUPLES FOR ARGUMENT UNPACKING
-----------------------------

*[1, 2, 3] -> $fn()                   # positional: $fn(1, 2, 3)
*[b: 2, a: 1] -> $fn()                # named: $fn(a=1, b=2)

SPREAD OPERATOR (@)
-------------------

Chains closures sequentially:
  5 -> @[$inc, $double, $add10]       # (5+1)*2+10 = 22

STRING METHODS
--------------

.len            length
.empty          is empty string
.trim           remove whitespace
.upper          uppercase
.lower          lowercase
.split(sep)     split into list
.lines          split on newlines
.join(sep)      join list with separator (on list)
.contains(s)    substring check
.starts_with(s) prefix check
.ends_with(s)   suffix check
.replace(p,r)   replace first match
.replace_all(p,r) replace all matches
.match(regex)   first match info (dict with matched, index, groups)
.is_match(regex) boolean regex check
.head           first character
.tail           last character
.at(i)          character at index

LIST/DICT METHODS
-----------------

.len            length
.empty          is empty
.head           first element
.tail           last element
.at(i)          element at index
.keys           dict keys as list
.values         dict values as list
.entries        dict as list of [key: k, value: v]

PARSING FUNCTIONS (for LLM output)
----------------------------------

parse_auto(str)           auto-detect format
parse_json(str)           parse JSON (repairs common errors)
parse_xml(str, tag?)      extract XML tag content
parse_fence(str, lang?)   extract fenced code block
parse_fences(str)         all fenced blocks as list
parse_frontmatter(str)    parse --- delimited YAML + body
parse_checklist(str)      parse markdown task lists

GLOBAL FUNCTIONS
----------------

type(val)                 returns type name
log(val)                  print and pass through
json(val)                 convert to JSON string
identity(val)             returns input unchanged
range(start, end, step?)  number sequence
repeat(val, count)        repeat value n times
enumerate(coll)           add index to elements

ITERATION LIMITS
----------------

Default: 10,000 iterations max for loops.
Override: ^(limit: N) statement

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

COMMON MISTAKES
---------------

1. Using = for assignment          -> use :> instead
2. Using || for defaults           -> use ?? instead
3. Assuming truthiness             -> explicit boolean checks required
4. Breaking from map/filter        -> only works in each/fold
5. Modifying outer vars in loops   -> use fold/$@ or $ as state dict (see LOOP STATE PATTERNS)
6. Expecting variables to leak     -> block scope is strict
7. Forgetting () on methods        -> .upper() not .upper (unless property)
8. Reassigning different type      -> variables lock to first type
9. Using while/for keywords        -> use (cond) @ { } or -> each { } instead

SCRIPT RETURN VALUES
--------------------

true / non-empty string -> exit code 0
false / empty string    -> exit code 1
[0, "message"]          -> exit code 0 with message
[1, "message"]          -> exit code 1 with message
