@rcrsr/rill 0.1.0

package/docs/02_types.md

@@ -0,0 +1,399 @@
+# rill Type System
+
+*Value types, type assertions, and type checking*
+
+## Overview
+
+rill is dynamically typed and type-safe. Types are checked at runtime, but type errors are always caught—there are no implicit conversions or coercions.
+
+| Type | Syntax | Example |
+|------|--------|---------|
+| String | `"text"` | `"hello"` |
+| Number | `123`, `0.5` | `42`, `0.9` |
+| Bool | `true`, `false` | `true` |
+| List | `[a, b]` | `["file.ts", 42]` |
+| Dict | `[k: v]` | `[output: "text", code: 0]` |
+| Tuple | `*[...]` | `*[1, 2]`, `*[x: 1, y: 2]` |
+| Closure | `\|\|{ }` | `\|x\|($x * 2)` |
+
+**Key principles:**
+- **Type-safe**: No implicit coercion—`"5" + 1` errors, not `"51"` or `6`
+- **Type-locked variables**: A variable that holds a string always holds a string
+- **Value-based**: All copies are deep, all comparisons by value
+- **No null/undefined**: Empty values are valid (`""`, `[]`, `[:]`), but "no value" cannot exist
+- **No truthiness**: Conditions require actual booleans, not "truthy" values
+
+---
+
+## Strings
+
+Double-quoted text with variable interpolation using `{$var}`:
+
+```text
+"hello world"
+"Process {$filename} for review"
+"Result: {$response}"
+```
+
+Escape sequences: `\n`, `\t`, `\\`, `\"`, `{{` (literal `{`), `}}` (literal `}`)
+
+### Interpolation
+
+Any valid expression works inside `{...}`:
+
+```rill
+"alice" :> $name
+3 :> $a
+5 :> $b
+true :> $ok
+"Hello, {$name}!"                    # Variable
+"sum: {$a + $b}"                     # Arithmetic
+"valid: {$a > 0}"                    # Comparison
+"status: {$ok ? \"yes\" ! \"no\"}"   # Conditional
+"upper: {$name -> .upper}"           # Method chain
+```
+
+### Heredocs
+
+Multiline strings use heredoc syntax:
+
+```rill
+prompt(<<EOF
+Review this code:
+{$code}
+
+Check for security issues.
+EOF
+)
+```
+
+The delimiter (e.g., `EOF`) must not appear on its own line within the content.
+
+See [Strings](09_strings.md) for string methods.
+
+---
+
+## Numbers
+
+Used for arithmetic, exit codes, and loop limits:
+
+```rill
+42
+0
+3.14159
+-7
+```
+
+**Arithmetic operators:** `+`, `-`, `*`, `/`, `%` (modulo)
+
+**Type constraint:** All arithmetic operands must be numbers. No implicit conversion:
+
+```rill
+5 + 3                      # 8
+"5" + 1                    # ERROR: Arithmetic requires number, got string
+```
+
+---
+
+## Booleans
+
+Literal `true` and `false`. Conditional expressions (`?`), loop conditions (`@`), and filter predicates require boolean values. Non-boolean values cause runtime errors.
+
+```rill
+true ? "yes" ! "no"        # "yes"
+false ? "yes" ! "no"       # "no"
+```
+
+**No truthiness:** rill has no automatic boolean coercion. Empty strings, zero, and empty lists are not "falsy"—you must explicitly check:
+
+```rill
+"" -> .empty ? "empty" ! "has content"     # Use .empty method
+0 -> ($ == 0) ? "zero" ! "nonzero"         # Use comparison
+```
+
+---
+
+## Lists
+
+Ordered sequences of values:
+
+```rill
+[1, 2, 3] :> $nums
+$nums[0]                   # 1
+$nums[-1]                  # 3 (last element)
+$nums -> .len              # 3
+```
+
+**Access methods:**
+- `[0]`, `[1]` — Index access (0-based)
+- `[-1]`, `[-2]` — Negative index (from end)
+- `.head` — First element (errors on empty)
+- `.tail` — Last element (errors on empty)
+- `.at(n)` — Element at index
+
+**Out-of-bounds access** throws an error:
+
+```text
+[] -> .at(0)               # Error: List index out of bounds
+["a"] -> .at(5)            # Error: List index out of bounds
+```
+
+Use `??` for safe access with default:
+
+```rill
+["a"] :> $list
+$list[0] ?? "default"  # "a"
+```
+
+See [Collections](07_collections.md) for iteration operators.
+
+---
+
+## Dicts
+
+Key-value mappings with string keys:
+
+```rill
+[name: "alice", age: 30] :> $person
+$person.name               # "alice"
+$person.age                # 30
+```
+
+**Access patterns:**
+- `.field` — Literal field access
+- `.$key` — Variable as key
+- `.($i + 1)` — Computed expression as key
+- `.(a || b)` — Alternatives (try keys left-to-right)
+- `.field ?? default` — Default value if missing
+- `.?field` — Existence check (returns bool)
+- `.?field&type` — Existence + type check
+
+**Missing key access** throws an error. Use `??` for safe access:
+
+```rill
+[:] :> $d
+$d.missing ?? ""           # "" (safe default)
+```
+
+### Dict Methods
+
+| Method | Description |
+|--------|-------------|
+| `.keys` | All keys as list |
+| `.values` | All values as list |
+| `.entries` | List of `[key, value]` pairs |
+
+```rill
+[name: "test", count: 42] -> .keys      # ["count", "name"]
+[name: "test", count: 42] -> .values    # [42, "test"]
+[a: 1, b: 2] -> .entries                # [["a", 1], ["b", 2]]
+```
+
+**Reserved methods** (`keys`, `values`, `entries`) cannot be used as dict keys.
+
+### Dict Closures
+
+Closures in dicts have `$` late-bound to the containing dict. See [Closures](06_closures.md) for details.
+
+```rill
+[
+  name: "toolkit",
+  count: 3,
+  str: ||"{$.name}: {$.count} items"
+] :> $obj
+
+$obj.str    # "toolkit: 3 items" (auto-invoked)
+```
+
+---
+
+## Tuples
+
+Tuples package values for explicit argument unpacking at closure invocation. Created with the `*` spread operator:
+
+```rill
+# From list (positional)
+*[1, 2, 3] :> $t              # tuple with positional values
+
+# From dict (named)
+*[x: 1, y: 2] :> $t           # tuple with named values
+
+# Via pipe target
+[1, 2, 3] -> * :> $t          # convert list to tuple
+```
+
+### Using Tuples at Invocation
+
+```rill
+|a, b, c| { "{$a}-{$b}-{$c}" } :> $fmt
+
+# Positional unpacking
+*[1, 2, 3] -> $fmt()          # "1-2-3"
+
+# Named unpacking (order doesn't matter)
+*[c: 3, a: 1, b: 2] -> $fmt() # "1-2-3"
+```
+
+### Strict Validation
+
+When invoking with tuples, missing required parameters error, and extra arguments error:
+
+```rill
+|x, y|($x + $y) :> $fn
+*[1] -> $fn()                 # Error: missing argument 'y'
+*[1, 2, 3] -> $fn()           # Error: extra positional argument
+*[x: 1, z: 3] -> $fn()        # Error: unknown argument 'z'
+```
+
+### Parameter Defaults with Tuples
+
+```rill
+|x, y = 10, z = 20|($x + $y + $z) :> $fn
+*[5] -> $fn()                 # 35 (5 + 10 + 20)
+*[x: 5, z: 30] -> $fn()       # 45 (5 + 10 + 30)
+```
+
+### Auto-Unpacking with Parallel Spread
+
+When a closure is invoked with a single tuple argument, the tuple auto-unpacks:
+
+```rill
+# List of tuples with multi-arg closure
+[*[1,2], *[3,4]] -> map |x,y|($x * $y)    # [2, 12]
+
+# Named tuples work too
+[*[x:1, y:2], *[x:3, y:4]] -> map |x,y|($x + $y)  # [3, 7]
+```
+
+---
+
+## Type Assertions
+
+Use type assertions to validate values at runtime.
+
+### Assert Type (`:type`)
+
+Error if type doesn't match, returns value unchanged:
+
+```rill
+# Postfix form (binds tighter than method calls)
+42:number                     # passes, returns 42
+(1 + 2):number                # passes, returns 3
+42:number.str                 # "42" - assertion then method
+
+# Pipe target form
+"hello" -> :string            # passes, returns "hello"
+"hello" -> :number            # ERROR: expected number, got string
+$val -> :dict -> .keys        # assert dict, then get keys
+```
+
+### Check Type (`:?type`)
+
+Returns boolean, no error:
+
+```rill
+# Postfix form
+42:?number                    # true
+"hello":?number               # false
+
+# Pipe target form
+"hello" -> :?string           # true
+```
+
+Type checks work in conditionals:
+
+```text
+$val -> :?list ? process() ! skip()   # branch on type
+```
+
+**Supported types:** `string`, `number`, `bool`, `closure`, `list`, `dict`, `tuple`
+
+### In Pipe Chains
+
+```rill
+# Assert type and continue processing
+[1, 2, 3] -> :list -> each { $ * 2 }
+
+# Multiple assertions in chain
+"test" -> :string -> .len -> :number   # 4
+```
+
+### Use Cases
+
+```rill
+# Validate function input
+|data| {
+  $data -> :list              # assert input is list
+  $data -> each { $ * 2 }
+} :> $process_items
+
+# Type-safe branching
+|val| {
+  $val -> :?number ? ($val * 2) ! ($val -> .len)
+} :> $process
+$process(5)        # 10
+$process("hello")  # 5
+```
+
+---
+
+## Type-Locked Variables
+
+Variables lock type on first assignment. The type is inferred from the value or declared explicitly:
+
+```rill
+"hello" :> $name              # implicit: locked as string
+"world" :> $name              # OK: same type
+5 :> $name                    # ERROR: cannot assign number to string
+
+"hello" :> $name:string       # explicit: declare and lock as string
+42 :> $count:number           # explicit: declare and lock as number
+```
+
+### Inline Capture with Type
+
+```rill
+"hello" :> $x:string -> .len  # type annotation in mid-chain
+```
+
+Type annotations validate on assignment and prevent accidental type changes:
+
+```rill
+|x|$x :> $fn                  # locked as closure
+"text" :> $fn                 # ERROR: cannot assign string to closure
+```
+
+---
+
+## Global Type Functions
+
+| Function | Description |
+|----------|-------------|
+| `type` | Returns type name as string |
+| `json` | Convert to JSON string |
+
+```rill
+42 -> type              # "number"
+"hello" -> type         # "string"
+[1, 2] -> type          # "list"
+*[1, 2] -> type         # "tuple"
+[a: 1] -> type          # "dict"
+||{ $ } -> type         # "closure"
+
+[a: 1, b: 2] -> json    # '{"a":1,"b":2}'
+```
+
+**`json` closure handling:**
+- Direct closure → error: `|x|{ $x } -> json` throws "Cannot serialize closure to JSON"
+- Closures in dicts → skipped: `[a: 1, fn: ||{ 0 }] -> json` returns `'{"a":1}'`
+- Closures in lists → skipped: `[1, ||{ 0 }, 2] -> json` returns `'[1,2]'`
+
+---
+
+## See Also
+
+- [Variables](03_variables.md) — Declaration, scope, `$` binding
+- [Closures](06_closures.md) — Closure semantics and patterns
+- [Collections](07_collections.md) — List iteration operators
+- [Strings](09_strings.md) — String methods reference
+- [Reference](11_reference.md) — Quick reference tables

package/docs/03_variables.md

@@ -0,0 +1,314 @@
+# rill Variables and Scope
+
+*Variable declaration, type locking, and scope rules*
+
+## Overview
+
+rill uses capture (`:>`) instead of assignment. Variables are type-locked after first assignment and follow strict scoping rules.
+
+**Key principles:**
+- **Capture, not assign**: Use `:>` to capture values into variables
+- **Type-locked**: Variables lock type on first assignment
+- **No shadowing**: Cannot redeclare a variable name from outer scope
+- **No leakage**: Variables created inside blocks don't exist outside
+
+---
+
+## Variable Declaration
+
+Variables are declared via capture (`:>`), not assignment:
+
+```rill
+"hello" :> $greeting
+42 :> $count
+[1, 2, 3] :> $items
+```
+
+### Capture and Continue
+
+The `:>` operator captures the value AND continues the chain:
+
+```rill
+"hello"
+    :> $greeting         # capture "hello" into $greeting
+    -> "{$} world"       # $ is still "hello"
+    :> $message          # capture "hello world" into $message
+    -> .upper            # result: "HELLO WORLD"
+```
+
+### Terminal Capture
+
+Capture at end of expression stores and ends the chain:
+
+```rill
+"hello" :> $result       # capture and end chain (result: "hello")
+```
+
+---
+
+## The Pipe Variable `$`
+
+`$` holds the current piped value in the current scope:
+
+```rill
+"test value" -> {
+  .upper -> log          # $ is "test value", logs "TEST VALUE"
+}
+```
+
+### `$` Binding by Context
+
+| Context | `$` contains |
+|---------|--------------|
+| Inline block `-> { }` | Piped value |
+| Each loop `-> each { }` | Current iteration item |
+| While-loop `(cond) @ { }` | Accumulated value |
+| Do-while `@ { } ? cond` | Accumulated value |
+| Conditional `cond ? { }` | Tested value |
+| Piped conditional `-> ? { }` | Piped value (also used as condition) |
+| Stored closure `\|x\|{ }` | N/A — use explicit params |
+| Dict closure `\|\|{ $.x }` | Dict self (`this`) — late-bound |
+
+### Implied `$`
+
+When certain constructs appear without explicit input, `$` is used implicitly:
+
+| Written | Equivalent to | Context |
+|---------|---------------|---------|
+| `? { }` | `$ -> ? { }` | Piped conditional ($ as condition) |
+| `.method()` | `$ -> .method()` | Method call without receiver |
+| `$fn()` | `$fn($)` | Closure call with no explicit args* |
+
+*Closure calls receive `$` only when: no explicit args, first param has no default, and `$` is not a closure.
+
+```rill
+# Inside blocks, $ flows naturally
+"test value" -> {
+  .upper -> log           # $ is "test value"
+}
+
+# In each loops, $ is the current item
+|x| { $x * 2 } :> $double
+[1, 2, 3] -> each { $double() }   # $double receives 1, 2, 3
+```
+
+**When implied `$` does NOT apply:**
+
+```rill
+# Explicit args override implied $
+|x| { $x } :> $fn
+$fn("explicit")           # uses "explicit", not $
+
+# Params with defaults use the default
+|x: string = "default"| { $x } :> $fn2
+$fn2()                    # uses "default", not $
+```
+
+---
+
+## Type-Locked Variables
+
+Variables lock type after first assignment:
+
+```rill
+"hello" :> $name              # locked as string
+"world" :> $name              # OK: same type
+```
+
+```text
+5 :> $name                    # ERROR: cannot assign number to string
+```
+
+### Explicit Type Annotations
+
+Declare type explicitly with `:type`:
+
+```rill
+"hello" :> $name:string       # declare and lock as string
+42 :> $count:number           # declare and lock as number
+```
+
+**Supported types:** `string`, `number`, `bool`, `closure`, `list`, `dict`, `tuple`
+
+### Inline Capture with Type
+
+```rill
+"hello" :> $x:string -> .len  # type annotation in mid-chain
+```
+
+Type annotations validate on assignment and prevent accidental type changes:
+
+```rill
+|x|$x :> $fn:closure          # locked as closure
+```
+
+```text
+"text" :> $fn                 # ERROR: cannot assign string to closure
+```
+
+---
+
+## Scope Rules
+
+Blocks, loops, conditionals, and grouped expressions create child scopes.
+
+### Three Rules
+
+1. **Read from parent:** Variables from outer scopes are accessible (read-only)
+2. **No shadowing:** Cannot assign to a variable name that exists in an outer scope
+3. **No leakage:** Variables created inside don't exist outside
+
+```rill
+"context" :> $ctx
+
+"check" -> .contains("c") ? {
+  "process with {$ctx}" -> log   # OK: read outer variable
+  "local" :> $temp               # OK: new local variable
+}
+# $temp not accessible here
+```
+
+```text
+"context" :> $ctx
+"check" -> .contains("c") ? {
+  "new" :> $ctx                  # ERROR: cannot shadow outer $ctx
+}
+```
+
+### While Loops and `$`
+
+While loops use `$` as the accumulator since named variables in the body don't persist across iterations:
+
+```rill
+# Use $ as accumulator (body result becomes next iteration's $)
+0 -> ($ < 5) @ { $ + 1 }    # Result: 5
+
+# Variables inside loop body are local to each iteration
+0 -> ($ < 3) @ {
+  ($ * 10) :> $temp    # $temp exists only in this iteration
+  $ + 1
+}
+# $temp not accessible here
+```
+
+### Reading Outer Variables
+
+```rill
+10 :> $x
+[1, 2, 3] -> each {
+  $x + $      # Reads outer $x = 10
+}
+# Result: [11, 12, 13]
+```
+
+---
+
+## Special Variables
+
+| Variable | Contains | Source |
+|----------|----------|--------|
+| `$` | Piped value (current block scope) | Grammar |
+| `$ARGS` | CLI positional args (list) | Runtime |
+| `$ENV.NAME` | Environment variable | Runtime |
+| `$name` | Named variable | Runtime |
+
+`$` is a grammar-level construct. All other variables are runtime-provided with the same scoping rules as user-defined variables.
+
+### `$ARGS`
+
+Access CLI positional arguments:
+
+```text
+$ARGS[0]                     # first argument
+$ARGS[1]                     # second argument
+$ARGS -> each { log($) }     # iterate all arguments
+```
+
+### `$ENV`
+
+Access environment variables:
+
+```text
+$ENV.HOME                    # /home/user
+$ENV.PATH                    # /usr/bin:...
+$ENV.DEPLOY_ENV ?? "dev"     # with default
+```
+
+### Runtime-Provided Variables
+
+Named variables like `$file` or `$config` are provided by the host runtime. rill treats them as any other variable in the outer scope:
+
+```text
+---
+args: file: string, retries: number = 3
+---
+
+# $file and $retries available because host parsed frontmatter
+process($file, $retries)
+```
+
+---
+
+## Inline Capture Pattern
+
+Captures can appear mid-chain for debugging or later reference. Semantically, `:> $a ->` stores the value and returns it unchanged (like `log`):
+
+```rill
+"analyze this" :> $result -> .upper -> .len
+# $result is "analyze this", final result is 12
+```
+
+The value flows: `"analyze this"` → stored in `$result` → uppercased → length.
+
+### Debugging Pattern
+
+```rill
+"test" :> $input -> log -> .upper :> $output -> log
+# logs "test", then logs "TEST"
+# $input is "test", $output is "TEST"
+```
+
+---
+
+## Common Patterns
+
+### Capture for Reuse
+
+Capture when you need the value in multiple places:
+
+```rill
+"hello" :> $greeting
+"{$greeting} world" :> $message
+"{$greeting} there" :> $alt
+```
+
+### Let Data Flow
+
+Prefer implied `$` when the value flows directly to the next statement:
+
+```text
+# Verbose — unnecessary capture
+app::prompt("check status") :> $status
+$status -> .empty ? app::error("No status")
+
+# Idiomatic — data flows naturally
+app::prompt("check status")
+.empty ? app::error("No status")
+```
+
+### Accumulation in Loops
+
+Use `$` for accumulation in while loops:
+
+```rill
+"" -> (.len < 5) @ { "{$}x" }   # "xxxxx"
+```
+
+---
+
+## See Also
+
+- [Types](02_types.md) — Type system and type assertions
+- [Control Flow](05_control-flow.md) — Conditionals and loops
+- [Closures](06_closures.md) — Closure scope and late binding
+- [Reference](11_reference.md) — Quick reference tables