@rcrsr/rill 0.4.1 → 0.4.3

package/docs/99_llm-reference.txt

@@ -1,7 +1,30 @@
-RILL LANGUAGE REFERENCE FOR LLM AGENTS
-=======================================
-
-Rill is a pipe-based scripting language. Data flows through pipes (->), not assignment (=).
+RILL LANGUAGE REFERENCE
+=======================
+
+Rill is designed to be generated by LLMs and understood by humans. The focus is on auditable LLM output, not ergonomic human authoring. It combines the flexibility of imperative languages with the strictness of declaritive specifications.
+
+STRENGTHS AND USE CASES
+-----------------------
+Strengths:
+  - Unambiguous syntax: $ prefix, explicit operators, no implicit coercion
+  - Single-pass parseable: LLMs generate correct code without symbol tables
+  - Readable by humans: pipe chains show data flow left-to-right
+  - Safe defaults: immutable values, type locking, no null/undefined
+
+Use cases:
+  - Workflow orchestration: chain LLM calls, API requests, transformations
+  - State machines: (cond) @ { } loops with $ as state dict handle multi-state logic
+  - Data pipelines: each/map/filter/fold process collections declaratively
+  - Prompt engineering: parse LLM output with parse_json, parse_xml, parse_fence
+
+State machine pattern ($ carries state through iterations):
+  [state: "init", data: $input]
+    -> ($.state != "done") @ {
+      $.state -> [
+        init: { [state: "process", data: transform($.data)] },
+        process: { [state: "done", data: finalize($.data)] }
+      ]
+    }
 
 NAMING CONVENTION: snake_case
 -----------------------------
@@ -118,9 +141,11 @@ Strings:       "hello {$var}"          # interpolation with {}
 Numbers:       42, 3.14, -7
 Booleans:      true, false
 Lists:         [1, 2, 3]
+               [...$list, 4]               # spread: inline list elements
 Dicts:         [name: "alice", age: 30]    # identifier keys
                [1: "one", 2: "two"]        # number keys (incl. negative: [-1: "neg"])
                [true: "yes", false: "no"]  # boolean keys
+               [["a", "b"]: 1]             # multi-key: [a: 1, b: 1]
 Tuples:        *[1, 2, 3]              # for argument unpacking
 Closures:      |x|($x + 1)             # like lambda/arrow functions
 Type annot:    "hi" :> $x:string       # lock type on capture
@@ -318,7 +343,11 @@ DICT DISPATCH (single key):
 Pipe a value to a dict to match keys and return associated values:
   $val -> [apple: "fruit", carrot: "veg"]        # returns "fruit" if $val is "apple"
   $val -> [apple: "fruit"] ?? "not found"         # default if no match
-  $method -> [["GET", "HEAD"]: "safe", ["POST", "PUT"]: "unsafe"]  # multi-key
+  $method -> [["GET", "HEAD"]: "safe", ["POST", "PUT"]: "unsafe"]  # multi-key dispatch
+
+Multi-key dispatch uses the same syntax as multi-key dict literals:
+  [["GET", "HEAD"]: "safe"]                      # dict with keys "GET" and "HEAD" both = "safe"
+  "GET" -> [["GET", "HEAD"]: "safe"]             # "safe" (matches "GET" key)
 
 Type-aware matching (keys matched by value AND type):
   1 -> [1: "number", "1": "string"]              # "number" (number key matches)
@@ -393,11 +422,40 @@ Slice (/<start:stop:step>):
   [0,1,2,3,4] -> /<::-1>              # [4,3,2,1,0] (reverse)
   "hello" -> /<1:4>                   # "ell"
 
+LIST SPREAD IN LITERALS
+-----------------------
+
+Inline list elements into a new list using ... (spread operator):
+  [1, 2] :> $a
+  [...$a, 3]                          # [1, 2, 3]
+  [...$a, ...$b]                      # concatenate lists
+  [...[], 1]                          # [1] (empty spread contributes nothing)
+  [...($nums -> map {$ * 2})]         # spread expression result
+  [...$nested[0]]                     # spread from nested access
+
+Error: spreading non-list throws RUNTIME_TYPE_ERROR
+  "hello" :> $s
+  [...$s]                             # ERROR: Spread requires list, got string
+
+MULTI-KEY DICT LITERALS
+-----------------------
+
+Map multiple keys to the same value using list syntax:
+  [["a", "b"]: 1]                     # [a: 1, b: 1]
+  [[1, "1"]: "x"]                     # [1: "x", "1": "x"] (mixed types)
+  [a: 0, ["b", "c"]: 1]               # [a: 0, b: 1, c: 1] (mixed entries)
+  [a: 0, ["a", "b"]: 1]               # [a: 1, b: 1] (last-write-wins)
+
+Error cases:
+  [[]: 1]                             # ERROR: empty key list
+  [[[1, 2], "a"]: 1]                  # ERROR: non-primitive key element
+
 TUPLES FOR ARGUMENT UNPACKING
 -----------------------------
 
 *[1, 2, 3] -> $fn()                   # positional: $fn(1, 2, 3)
 *[b: 2, a: 1] -> $fn()                # named: $fn(a=1, b=2)
+*[...$list, 3] -> $fn()               # spread in tuple: combines elements
 
 SPREAD OPERATOR (@)
 -------------------

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rcrsr/rill",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Rill - An embeddable scripting language for orchestrating LLM workflows",
   "type": "module",
   "main": "dist/index.js",