@rcrsr/rill 0.2.4 → 0.4.2

package/docs/06_closures.md

@@ -2,10 +2,58 @@
 
 Closures are first-class values that capture their defining scope. This document covers closure semantics, binding behavior, and common patterns.
 
+## Expression Delimiters
+
+rill has two expression delimiters with deterministic behavior:
+
+| Delimiter | Semantics | Produces |
+|-----------|-----------|----------|
+| `{ body }` | Deferred (closure creation) | `ScriptCallable` |
+| `( expr )` | Eager (immediate evaluation) | Result value |
+
+**Key distinction:**
+- **Parentheses `( )`** evaluate immediately and return the result
+- **Braces `{ }`** create a closure for later invocation (deferred execution)
+
+### Pipe Target Exception
+
+When `{ }` appears as a pipe target, it creates a closure and **immediately invokes** it:
+
+```rill
+5 -> { $ + 1 }    # 6 (same observable result as eager evaluation)
+```
+
+This is conceptually two steps happening in sequence:
+
+```text
+5 -> { $ + 1 }
+     ↓
+Step 1: Create closure with implicit $ parameter
+Step 2: Invoke closure with piped value (5) as argument
+     ↓
+Result: 6
+```
+
+The observable result matches eager evaluation, but the mechanism differs. This matters when understanding error messages or debugging—the closure exists momentarily before invocation.
+
+**Comparison:**
+
+| Expression | Mechanism | Result |
+|------------|-----------|--------|
+| `5 -> { $ + 1 }` | Create closure, invoke with 5 | 6 |
+| `5 -> ($ + 1)` | Evaluate expression with $ = 5 | 6 |
+| `{ $ + 1 } :> $fn` | Create closure, store it | closure |
+| `($ + 1) :> $x` | Error: $ undefined outside pipe | — |
+
+The last row shows the key difference: `( )` requires `$` to already be defined, while `{ }` captures `$` as a parameter for later binding.
+
 ## Closure Syntax
 
 ```text
-# No parameters (property-style)
+# Block-closure (implicit $ parameter)
+{ body }
+
+# Zero-parameter closure (property-style, no parameters)
 || { body }
 ||body           # shorthand for simple expressions
 
@@ -18,9 +66,107 @@ Closures are first-class values that capture their defining scope. This document
 |x: string = "hi"| { body }    # default with explicit type
 ```
 
-**Key distinction:**
-- **Blocks `{ }`** execute immediately
-- **Closures `||{ }` or `|params|{ }`** are stored for later invocation
+## Block-Closures
+
+Block syntax `{ body }` creates a closure with an implicit `$` parameter. This enables deferred execution and reusable transformations.
+
+### Basic Block-Closure
+
+```rill
+{ $ + 1 } :> $increment
+
+5 -> $increment       # 6
+10 -> $increment      # 11
+$increment(7)         # 8 (direct call also works)
+```
+
+The block `{ $ + 1 }` produces a closure. When invoked, `$` is bound to the argument.
+
+### Block-Closures vs Zero-Param Closures
+
+| Form | Params | `isProperty` | Behavior |
+|------|--------|-------------|----------|
+| `{ body }` (block-closure) | `[{ name: "$" }]` | `false` | Requires argument |
+| `\|\|{ body }` (zero-param) | `[]` | `true` | Auto-invokes on dict access |
+
+```rill
+{ $ * 2 } :> $double
+|| { 42 } :> $constant
+
+5 -> $double          # 10 (requires argument)
+$constant()           # 42 (no argument needed)
+
+# In dicts
+[
+  double: { $ * 2 },
+  constant: || { 42 }
+] :> $obj
+
+$obj.double(5)        # 10 (explicit call required)
+$obj.constant         # 42 (auto-invoked on access)
+```
+
+Block-closures require an argument; zero-param closures do not.
+
+### Type Checking
+
+Block-closures check type at runtime:
+
+```rill
+{ $ + 1 } :> $fn
+
+type($fn)             # "closure"
+$fn(5)                # 6
+$fn("text")           # Error: Cannot add string and number
+```
+
+### Multi-Statement Block-Closures
+
+Block-closures can contain multiple statements:
+
+```rill
+{
+  ($ * 2) :> $doubled
+  "{$}: doubled is {$doubled}"
+} :> $describe
+
+5 -> $describe        # "5: doubled is 10"
+```
+
+### Collection Operations
+
+Block-closures integrate with collection operators:
+
+```rill
+[1, 2, 3] -> map { $ * 2 }                    # [2, 4, 6]
+[1, 2, 3] -> filter { $ > 1 }                 # [2, 3]
+[1, 2, 3] -> fold(0) { $@ + $ }               # 6 ($@ is accumulator)
+```
+
+### Eager vs Deferred Evaluation
+
+The choice between `( )` and `{ }` determines when code executes:
+
+```rill
+# Eager: parentheses evaluate immediately
+5 -> ($ + 1) :> $result
+$result                # 6 (number, already computed)
+
+# Deferred: braces create closure
+{ $ + 1 } :> $addOne
+type($addOne)          # "closure"
+5 -> $addOne           # 6
+10 -> $addOne          # 11 (invoked later with different value)
+
+# Practical difference
+(5 + 1) :> $six        # 6 (immediate)
+{ $ + 1 } :> $fn       # closure (deferred)
+
+$six                   # 6
+10 -> $fn              # 11
+```
+
+Use `( )` when you want the result now. Use `{ }` when you want reusable logic.
 
 ## Late Binding
 
@@ -265,6 +411,9 @@ $fn()    # 20 (late binding sees updated $x)
 ```rill
 |x| { $x + 1 } :> $inc
 $inc(5)    # 6
+
+{ $ + 1 } :> $inc
+$inc(5)    # 6 (block-closure)
 ```
 
 ### Pipe Call
@@ -272,8 +421,13 @@ $inc(5)    # 6
 ```rill
 |x| { $x + 1 } :> $inc
 5 -> $inc()    # 6
+
+{ $ + 1 } :> $inc
+5 -> $inc      # 6 (block-closure, no parens needed)
 ```
 
+Block-closures work seamlessly with pipe syntax since `$` receives the piped value.
+
 ### Postfix Invocation
 
 Call closures from bracket access or expressions:
@@ -282,6 +436,9 @@ Call closures from bracket access or expressions:
 [|x| { $x * 2 }] :> $fns
 $fns[0](5)    # 10
 
+[{ $ * 2 }] :> $fns
+$fns[0](5)    # 10 (block-closure)
+
 || { |n| { $n * 2 } } :> $factory
 $factory()(5)    # 10 (chained invocation)
 ```
@@ -300,6 +457,283 @@ $list[0] -> .upper    # "HELLO"
 
 Note: `$list[0].upper` parses `.upper` as field access on `$list`, not as a method call on the element. This throws an error since lists don't have an `upper` field.
 
+## Parameter Metadata
+
+Closures expose parameter metadata via the `.params` property. This enables runtime introspection of function signatures.
+
+### Basic Usage
+
+```rill
+|x, y| { $x + $y } :> $add
+$add.params
+# [
+#   x: [type: ""],
+#   y: [type: ""]
+# ]
+```
+
+### Typed Parameters
+
+```rill
+|name: string, age: number| { "{$name}: {$age}" } :> $format
+$format.params
+# [
+#   name: [type: "string"],
+#   age: [type: "number"]
+# ]
+```
+
+### Block-Closures
+
+Block-closures have an implicit `$` parameter:
+
+```rill
+{ $ * 2 } :> $double
+$double.params
+# [
+#   $: [type: ""]
+# ]
+```
+
+### Zero-Parameter Closures
+
+```rill
+|| { 42 } :> $constant
+$constant.params
+# []
+```
+
+### Practical Use Cases
+
+**Generic Function Wrapper:**
+
+```rill
+|fn| {
+  $fn.params -> .keys -> .len :> $count
+  "Function has {$count} parameter(s)"
+} :> $describe
+
+|x, y| { $x + $y } :> $add
+$describe($add)    # "Function has 2 parameter(s)"
+```
+
+**Validation:**
+
+```text
+|fn| {
+  $fn.params -> .entries -> each {
+    $[1].type -> .empty ? "Missing type annotation: {$[0]}" ! ""
+  } -> filter { !$ -> .empty }
+} :> $checkTypes
+
+|x, y: number| { $x + $y } :> $partial
+$checkTypes($partial)    # ["Missing type annotation: x"]
+```
+
+## Parameter Annotations
+
+Parameters can have their own annotations using `^(key: value)` syntax after the parameter name. These attach metadata to individual parameters for validation, configuration, or documentation purposes.
+
+### Syntax and Ordering
+
+Parameter annotations appear in a specific order:
+
+```text
+|paramName: type ^(annotations) = default| body
+```
+
+**Ordering rules:**
+1. Parameter name (required)
+2. Type annotation with `:` (optional)
+3. Parameter annotations with `^()` (optional)
+4. Default value with `=` (optional)
+
+```rill
+|x: number ^(min: 0, max: 100)|($x) :> $validate
+|name: string ^(required: true) = "guest"|($name) :> $greet
+|count ^(cache: true) = 0|($count) :> $process
+```
+
+### Access Pattern
+
+Parameter annotations are accessed via `.params.paramName.__annotations.key`:
+
+```rill
+|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.x.__annotations.max  # 100
+$fn.params.y.?__annotations     # false (no annotations on y)
+```
+
+### Validation Metadata
+
+Use parameter annotations to specify constraints:
+
+```rill
+|value: number ^(min: 0, max: 100)|($value) :> $bounded
+
+$bounded.params.value.__annotations.min  # 0
+$bounded.params.value.__annotations.max  # 100
+```
+
+**Generic validator pattern:**
+
+```text
+|fn, arg| {
+  $fn.params -> .entries -> .head -> *<$name, $meta>
+  $meta.?__annotations ? {
+    ($arg < $meta.__annotations.min) ? "Value {$arg} below min {$meta.__annotations.min}" !
+    ($arg > $meta.__annotations.max) ? "Value {$arg} above max {$meta.__annotations.max}" !
+    ""
+  } ! ""
+} :> $validate
+
+|x: number ^(min: 0, max: 10)|($x) :> $ranged
+$validate($ranged, 15)  # "Value 15 above max 10"
+```
+
+### Caching Hints
+
+Mark parameters that should trigger caching behavior:
+
+```rill
+|key: string ^(cache: true)|($key) :> $fetch
+
+$fetch.params.key.__annotations.cache  # true
+```
+
+### Format Specifications
+
+Attach formatting metadata to parameters:
+
+```rill
+|timestamp: string ^(format: "ISO8601")|($timestamp) :> $formatDate
+
+$formatDate.params.timestamp.__annotations.format  # "ISO8601"
+```
+
+### Multiple Annotations
+
+Parameters can have multiple annotations:
+
+```rill
+|email: string ^(required: true, pattern: ".*@.*", maxLength: 100)|($email) :> $validateEmail
+
+$validateEmail.params.email.__annotations.required    # true
+$validateEmail.params.email.__annotations.pattern     # ".*@.*"
+$validateEmail.params.email.__annotations.maxLength   # 100
+```
+
+### Annotation-Driven Logic
+
+Use parameter annotations to drive runtime behavior:
+
+```text
+|processor| {
+  $processor.params -> .entries -> each {
+    $[1].?__annotations ? {
+      $[1].__annotations.?required ? "Parameter {$[0]} is required" ! ""
+    } ! ""
+  } -> filter { !$ -> .empty }
+} :> $getRequiredParams
+
+|x, y: string ^(required: true), z|($x) :> $fn
+$getRequiredParams($fn)  # ["Parameter y is required"]
+```
+
+### Checking for Annotations
+
+Use existence check `.?__annotations` to determine if a parameter has annotations:
+
+```rill
+|x: number ^(min: 0), y: string|($x + $y) :> $fn
+
+$fn.params.x.?__annotations  # true
+$fn.params.y.?__annotations  # false
+```
+
+## Annotation Reflection
+
+Closures support annotation reflection via `.^key` syntax. Annotations attach metadata to closures for runtime introspection.
+
+**Type Restriction:** Only closures support annotation reflection. Accessing `.^key` on primitives throws `RUNTIME_TYPE_ERROR`.
+
+### Basic Annotation Access
+
+```rill
+^(min: 0, max: 100) |x|($x) :> $fn
+
+$fn.^min     # 0
+$fn.^max     # 100
+```
+
+### Complex Annotation Values
+
+Annotations can hold any value type:
+
+```rill
+^(config: [timeout: 30, endpoints: ["a", "b"]]) |x|($x) :> $fn
+
+$fn.^config.timeout      # 30
+$fn.^config.endpoints[0] # "a"
+```
+
+### Default Value Coalescing
+
+Use the default value operator for optional annotations:
+
+```rill
+|x|($x) :> $fn
+$fn.^timeout ?? 30  # 30 (uses default when annotation missing)
+
+^(timeout: 60) |x|($x) :> $withTimeout
+$withTimeout.^timeout ?? 30  # 60 (uses annotated value)
+```
+
+### Annotation-Driven Logic
+
+```rill
+^(enabled: true) |x|($x) :> $processor
+
+$processor.^enabled ? "processing" ! "disabled"  # "processing"
+```
+
+### Dynamic Annotations
+
+Annotation values are evaluated at closure creation:
+
+```rill
+10 :> $base
+^(limit: $base * 10) |x|($x) :> $fn
+$fn.^limit  # 100
+```
+
+### Error Cases
+
+**Undefined Annotation Key:**
+
+```rill
+|x|($x) :> $fn
+$fn.^missing   # Error: RUNTIME_UNDEFINED_ANNOTATION
+```
+
+**Non-Closure Type:**
+
+```text
+"hello" :> $str
+$str.^key      # Error: RUNTIME_TYPE_ERROR
+```
+
+All primitive types (string, number, boolean, list, dict) throw `RUNTIME_TYPE_ERROR` when accessing `.^key`.
+
 ## Error Behavior
 
 ### Undefined Variables