@rcrsr/rill 0.1.0 → 0.2.0

package/docs/02_types.md

@@ -53,21 +53,19 @@ true :> $ok
 "upper: {$name -> .upper}"           # Method chain
 ```
 
-### Heredocs
+### Multiline Strings
 
-Multiline strings use heredoc syntax:
+Multiline strings use triple-quote syntax:
 
 ```rill
-prompt(<<EOF
-Review this code:
-{$code}
-
-Check for security issues.
-EOF
-)
+"World" :> $name
+"""
+Hello, {$name}!
+Line two
+"""
 ```
 
-The delimiter (e.g., `EOF`) must not appear on its own line within the content.
+Triple-quote strings support interpolation like regular strings.
 
 See [Strings](09_strings.md) for string methods.
 

package/docs/03_variables.md

@@ -191,6 +191,16 @@ While loops use `$` as the accumulator since named variables in the body don't p
 # $temp not accessible here
 ```
 
+> **Common Mistake:** Attempting to modify outer-scope variables from inside loops. This pattern NEVER works:
+>
+> ```text
+> 0 :> $count
+> [1, 2, 3] -> each { $count + 1 :> $count }  # Creates LOCAL $count!
+> $count                                       # Still 0!
+> ```
+>
+> Use `fold` for reductions, or pack multiple values into `$` as a dict. See [Collections](07_collections.md) for accumulator patterns.
+
 ### Reading Outer Variables
 
 ```rill

package/docs/04_operators.md

@@ -421,7 +421,7 @@ $list[1]                         # "b"
 
 Use a variable as key:
 
-```rill
+```text
 "name" :> $key
 [name: "alice"] :> $data
 $data.$key                       # "alice"
@@ -431,7 +431,7 @@ $data.$key                       # "alice"
 
 Use an expression as key:
 
-```rill
+```text
 0 :> $i
 ["a", "b", "c"] :> $list
 $list.($i + 1)                   # "b"
@@ -441,7 +441,7 @@ $list.($i + 1)                   # "b"
 
 Try keys left-to-right:
 
-```rill
+```text
 [nickname: "Al"] :> $user
 $user.(name || nickname)         # "Al"
 ```

package/docs/05_control-flow.md

@@ -110,6 +110,8 @@ true -> ? {
 
 Pre-condition loop. Condition is evaluated before each iteration. The body result becomes the next iteration's `$`.
 
+> **Note:** There is no `while` keyword. Use `(condition) @ { body }` syntax. Loop bodies cannot modify outer-scope variables—use `$` to carry all state. For multiple values, pack them in a dict.
+
 ### Syntax
 
 ```text
@@ -151,6 +153,25 @@ Use `^(limit: N)` annotation to set maximum iterations (default: 10,000):
 
 Exceeding the limit throws `RuntimeError` with code `RUNTIME_LIMIT_EXCEEDED`.
 
+### Multiple State Values
+
+When you need to track multiple values across iterations, use `$` as a state dict:
+
+```text
+# Track iteration count, text, and done flag
+[iter: 0, text: $input, done: false]
+  -> (!$.done && $.iter < 3) @ {
+    $.iter + 1 :> $i
+    app::process($.text) :> $result
+    $result.finished
+      ? [iter: $i, text: $.text, done: true]
+      ! [iter: $i, text: $result.text, done: false]
+  }
+# Access final state: $.text, $.iter
+```
+
+This pattern replaces the common (but invalid) approach of trying to modify outer variables from inside the loop.
+
 ---
 
 ## Do-While Loop

package/docs/07_collections.md

@@ -15,6 +15,8 @@ rill provides four collection operators for transforming, filtering, and reducin
 
 All three operators share similar syntax but differ in execution model and output.
 
+> **Important:** Loop bodies cannot modify outer-scope variables (see [Variables](03_variables.md)). Use `fold` or `each(init)` with accumulators instead.
+
 ```rill
 # Sequential: results in order, one at a time
 [1, 2, 3] -> each { $ * 2 }     # [2, 4, 6]

package/docs/10_parsing.md

@@ -130,7 +130,7 @@ $response -> parse_xml
 ### Chain-of-Thought Pattern
 
 ```rill
-prompt(<<EOF
+"""
 Analyze this problem step by step.
 
 <thinking>
@@ -140,8 +140,9 @@ Show your reasoning here
 <answer>
 Return your final answer as JSON
 </answer>
-EOF
-) :> $response
+""" :> $prompt_text
+
+app::prompt($prompt_text) :> $response
 
 # Log reasoning for debugging
 $response -> parse_xml("thinking") -> log
@@ -152,22 +153,21 @@ $response -> parse_xml("answer") -> parse_json :> $result
 
 ### Tool Calling Pattern
 
-```rill
-prompt(<<EOF
+```text
+"""
 You have access to tools. To call a tool, use:
 <tool>
   <name>tool_name</name>
   <args>{"param": "value"}</args>
 </tool>
-EOF
-) :> $response
+""" -> app::prompt() :> $response
 
 $response -> parse_xml("tool") :> $tool
 $tool -> parse_xml("name") :> $fn_name
 $tool -> parse_xml("args") -> parse_json :> $fn_args
 
-# Call the function dynamically
-call($fn_name, $fn_args)
+# Call the function dynamically (host-provided)
+app::call($fn_name, $fn_args)
 ```
 
 ## Fenced Code Blocks

package/docs/11_reference.md

@@ -72,7 +72,7 @@ See [Collections](07_collections.md) for detailed documentation.
 
 | Type | Syntax | Example |
 |------|--------|---------|
-| String | `"text"` | `"hello"` |
+| String | `"text"`, `"""text"""` | `"hello"`, `"""line 1\nline 2"""` |
 | Number | `123`, `0.5` | `42`, `0.9` |
 | Bool | `true`, `false` | `true` |
 | List | `[a, b]` | `["file.ts", 42]` |

package/docs/12_examples.md

@@ -15,57 +15,51 @@ args: requirements: string
 ---
 
 # Phase 1: Validate requirements
-prompt(<<EOF
+"""
 Review the requirements document at {$requirements}.
 Check for completeness and clarity.
 Output READY if complete, or list missing elements.
-EOF
-) :> $validation
+""" -> prompt() :> $validation
 
 $validation -> ?(!.contains("READY")) {
   error("Requirements incomplete: {$validation}")
 }
 
 # Phase 2: Create specification
-prompt(<<EOF
+"""
 Create a technical specification from {$requirements}.
 Include API design, data models, and component structure.
-EOF
-) :> $spec
+""" -> prompt() :> $spec
 
 "Specification created" -> log
 
 # Phase 3: Review loop - iterate until approved
 ($spec -> .contains("REVISION")) @ {
-  prompt(<<EOF
+  """
 Review this specification for issues:
 {$}
 
 Output APPROVED if ready, or REVISION REQUIRED with feedback.
-EOF
-  ) :> $review
+  """ -> prompt() :> $review
 
   $review -> ?(.contains("APPROVED")) { break }
 
   # Apply feedback and continue
-  prompt(<<EOF
+  """
 Update the specification based on this feedback:
 {$review}
 
 Original spec:
 {$}
-EOF
-  )
-} :> $approved_spec
+  """ -> prompt()} :> $approved_spec
 
 # Phase 4: Implementation
-prompt(<<EOF
+"""
 Implement the approved specification:
 {$approved_spec}
 
 Create the necessary files and tests.
-EOF
-) :> $implementation
+""" -> prompt() :> $implementation
 
 # Phase 5: Verify
 prompt("Run tests and verify implementation") :> $verification
@@ -91,7 +85,7 @@ prompt("Read {$plan} and find the first unchecked item (- [ ])") :> $status
 
 # Work loop
 $status -> @(!.contains("ALL COMPLETE")) {
-  prompt(<<EOF
+  """
 Based on this status:
 {$}
 
@@ -99,9 +93,7 @@ Based on this status:
 2. Mark it complete in {$plan}
 3. Check if any unchecked items remain
 4. Output ALL COMPLETE if done, or describe next item
-EOF
-  )
-} :> $final
+  """ -> prompt()} :> $final
 
 "Plan complete: {$final}" -> log
 ```
@@ -122,14 +114,12 @@ prompt("Run tests for {$target} and report results") :> $result
 $result -> @(.contains("FAIL")) {
   "Fixing failures..." -> log
 
-  prompt(<<EOF
+  """
 Fix these test failures:
 {$}
 
 Make minimal changes. Then run tests again and report results.
-EOF
-  )
-} :> $final
+  """ -> prompt()} :> $final
 
 $final -> ?(.contains("PASS")) {
   "All tests passing"
@@ -151,22 +141,20 @@ args: file: string
 prompt("Read and summarize {$file}") :> $summary
 
 # Security check
-prompt(<<EOF
+"""
 Evaluate for SECURITY issues:
 {$summary}
 
 Output PASS, WARN, or FAIL with explanation.
-EOF
-) :> $security
+""" -> prompt() :> $security
 
 # Performance check
-prompt(<<EOF
+"""
 Evaluate for PERFORMANCE issues:
 {$summary}
 
 Output PASS, WARN, or FAIL with explanation.
-EOF
-) :> $performance
+""" -> prompt() :> $performance
 
 # Check results
 $security -> ?(.contains("FAIL")) {
@@ -196,21 +184,17 @@ $ENV.DEPLOY_ENV -> ?(.empty()) {
 
 # Environment-specific deployment
 ($ENV.DEPLOY_ENV == "production") ? {
-  prompt(<<EOF
+  """
 Deploy {$service} to production.
 - Run full test suite first
 - Enable monitoring
 - Use blue-green deployment
-EOF
-  )
-} ! ($ENV.DEPLOY_ENV == "staging") ? {
-  prompt(<<EOF
+  """ -> prompt()} ! ($ENV.DEPLOY_ENV == "staging") ? {
+  """
 Deploy {$service} to staging.
 - Run smoke tests
 - Enable debug logging
-EOF
-  )
-} ! {
+  """ -> prompt()} ! {
   prompt("Deploy {$service} to development environment")
 } :> $result
 
@@ -229,13 +213,11 @@ args: operation: string
 
 # Do-while: body runs first, then condition checked
 ^(limit: 5) @ {
-  prompt(<<EOF
+  """
 Perform: {$operation}
 
 Output SUCCESS, RETRY, or FAILED.
-EOF
-  )
-} ? (.contains("RETRY"))
+  """ -> prompt()} ? (.contains("RETRY"))
 
 # Loop exits when result doesn't contain RETRY
 .contains("SUCCESS") ? [0, "Succeeded"] ! [1, "Failed: {$}"]
@@ -263,14 +245,13 @@ prompt("Analyze this content:\n{$raw}") :> $analysis -> log -> ?(.empty()) {
 }
 
 # Both $raw and $analysis available
-prompt(<<EOF
+"""
 Compare the original:
 {$raw}
 
 With the analysis:
 {$analysis}
-EOF
-)
+""" -> prompt()
 ```
 
 Semantically, `:> $var ->` is `:> $var.set($) ->` — the capture acts like `log`, storing the value while passing it through unchanged.
@@ -326,13 +307,12 @@ prompt("Read {$logfile} and find all ERROR lines") :> $errors
 $errors -> ?(.empty()) {
   "No errors found"
 } ! {
-  prompt(<<EOF
+  """
 Analyze these errors and categorize them:
 {$errors}
 
 For each unique error type, suggest a fix.
-EOF
-  ) :> $analysis
+  """ -> prompt() :> $analysis
 
   "Error analysis complete" -> log
   $analysis
@@ -393,12 +373,10 @@ range(1, $batches + 1) -> each {
   (($batch_num - 1) * 10) :> $start
   ($start + 10) :> $end
 
-  prompt(<<EOF
+  """
 Process batch {$batch_num} of {$batches}
 Items {$start} through {$end}
-EOF
-  )
-}
+  """ -> prompt()}
 
 [0, "Processed all batches"]
 ```
@@ -415,27 +393,24 @@ exceptions:
   - ":::NEEDS_HUMAN:::"
 ---
 
-prompt(<<EOF
+"""
 Work on this task: {$task}
 
 Rules:
 - Output :::BLOCKED::: if you need information you don't have
 - Output :::NEEDS_HUMAN::: if human judgment is required
 - Output :::DONE::: when complete
-EOF
-) :> $result
+""" -> prompt() :> $result
 
 $result -> @(!.contains(":::DONE:::")) {
-  prompt(<<EOF
+  """
 Continue working on: {$task}
 
 Previous progress:
 {$}
 
 Remember the signal rules.
-EOF
-  )
-} :> $final
+  """ -> prompt()} :> $final
 
 "Task complete: {$final}" -> log
 ```
@@ -607,11 +582,10 @@ $response -> parse_xml("answer") -> parse_json :> $answer
 ### Parse Tool Calls
 
 ```rill
-prompt(<<EOF
+"""
 What function should I call?
 Return in format: <tool><name>func</name><args>{...}</args></tool>
-EOF
-) :> $response
+""" -> prompt() :> $response
 
 $response -> parse_xml("tool") :> $tool
 $tool -> parse_xml("name") :> $fn_name