Fix 4 runtime issues: REPL persistence, parser hang, engine errors, pipe operator

Made-with: Cursor

Author: Leo Louvar

README.md

@@ -112,14 +112,14 @@ flowchart TB
 | **Part 2: Language Fundamentals (6–12)** | Variables and all data types (Int, Float, Bool, String, Arrays, Maps), map indexing, type conversions, built-in functions, exercises |
 | **Part 3: Control Flow (13–17)** | If/else, while and for loops, pattern matching, decision-making patterns |
 | **Part 4: Functions (18–22)** | Definition and calling, parameters vs arguments, lambdas, recursion, scope and best practices |
-| **Part 5: Power Features (23–28)** | 25+ built-in functions, engine operations (22 Zig NIFs), Python integration, performance |
+| **Part 5: Power Features (23–28)** | 25+ built-in functions, pipe operator (`\|>`), engine operations (22 Zig NIFs), Python integration, performance |
 | **Part 6: Real-World Projects (29–35)** | Data pipeline, AI text analysis, LLM integration, workflow automation |
 | **Part 7: Mastery (36–40)** | Best practices, performance tips, debugging guide, patterns and anti-patterns |
 | **Appendices** | Grammar reference, quick reference card, common patterns, engine operations table |
 
 **Key features:** Progressive learning, 20+ complete examples, 4 real projects, exercises with solutions, visual aids, error-handling focus, AI/automation emphasis.
 
-**Guide stats:** 40+ pages · 20+ code examples · 4 projects · 6 exercises per chapter · 25+ built-in functions · 22 engine ops · modulo, map indexing, type conversions · full grammar reference.
+**Guide stats:** 40+ pages · 20+ code examples · 4 projects · 6 exercises per chapter · 25+ built-in functions · 22 engine ops · pipe operator, modulo, map indexing, type conversions · full grammar reference.
 
 **PDF:** A PDF copy is available at [docs/Zixir Language complete guide.pdf](docs/Zixir%20Language%20complete%20guide.pdf) (same path as the guide, .pdf for download). Website: [zixir-lang.github.io/Zixir/Zixir%20Language%20complete%20guide.pdf](https://zixir-lang.github.io/Zixir/Zixir%20Language%20complete%20guide.pdf). To rebuild locally: **Node** — `npx md-to-pdf "docs/Zixir Language complete guide.md"` (output is already named with spaces); **or** **pandoc** — `./scripts/build-guide-pdf.sh` (Unix) or `.\scripts\build-guide-pdf.ps1` (Windows; requires [pandoc](https://pandoc.org) and LaTeX). To enable automatic PDF build on push: create `.github/workflows/build-guide-pdf.yml` from [scripts/build-guide-pdf-workflow.yml](scripts/build-guide-pdf-workflow.yml) (skip the first 3 comment lines).
 
@@ -233,8 +233,8 @@ After Setup, run `mix zixir.run examples/hello.zixir`. Expected: `11.0`. For JIT
 
 | Feature | Status | Notes |
 |---------|--------|-------|
-| Parser | Complete | Recursive descent; tokenization, expressions, control flow, modulo (`%`), map indexing |
-| Interpreter | Complete | 25+ built-in functions (`length`, `print`, `to_string`, `type_of`, `split`, `join`, `range`, `reverse`, `abs`, `min`, `max`, etc.), map bracket access, closures |
+| Parser | Complete | Recursive descent; tokenization, expressions, control flow, modulo (`%`), map indexing, pipe operator (`\|>`) |
+| Interpreter | Complete | 25+ built-in functions, pipe operator (`\|>`), map bracket access, closures, graceful engine error handling |
 | Engine NIFs | Complete | 20+ Zig operations (sum, product, dot, etc.) |
 | Zig Backend | Complete | Codegen, functions, optimization passes |
 | Type System | Complete | Inference, lambda/map/struct types |
@@ -245,7 +245,7 @@ After Setup, run `mix zixir.run examples/hello.zixir`. Expected: `11.0`. For JIT
 | Workflow | Complete | Steps, retries, checkpoints, sandboxing |
 | Observability | Complete | Logging, metrics, tracing, alerts |
 | Cache | Complete | ETS + disk caching |
-| CLI/REPL | Working | All commands functional |
+| CLI/REPL | Complete | Variable persistence, function persistence, all commands functional |
 | Portable CLI | Working | `zixir_run.sh` / `zixir_run.bat` from release; run from any path |
 | LSP Server | ✅ Ready | `mix zixir.lsp` + VS Code integration |
 | Package Manager | Complete | `Zixir.Package`: resolve, install (Git/path), list, cache; `zixir.toml` manifest |

docs/Zixir Language complete guide.md

@@ -95,15 +95,16 @@ Before we begin, it's important to understand Zixir's current capabilities:
 - ✅ Functions (simple, recursive, closures, lambdas)
 - ✅ Pattern matching
 - ✅ If/else expressions
+- ✅ Pipe operator (`|>`) for chaining function calls
 - ✅ Engine operations (22 high-performance Zig NIF operations)
 - ✅ Python FFI (module-level functions)
 
 **Current Limitations:**
 - ⚠️ **Loops:** While/for loops work but don't support variable accumulation across iterations (by design — Zixir is immutable). Use recursion or engine operations instead.
 - ⚠️ **Python Methods:** Only module-level functions work (e.g., `math.sqrt`), not object methods (e.g., `str.lower`)
-- ⚠️ **Pipe operator:** `|>` syntax is not yet functional
 
 **Recommended Approach:**
+- Use **pipe operator** (`|>`) to chain transformations cleanly
 - Use **built-in functions** for common operations (`length`, `to_string`, `print`, `split`, `join`, etc.)
 - Use **map indexing** for key-value access (`user["name"]`)
 - Use **engine operations** for bulk data processing (fastest)
@@ -728,6 +729,7 @@ Just like in math, some operations happen before others:
 6. Equality: ==, !=
 7. Logical AND: &&
 8. Logical OR: ||
+9. Pipe: |>  (lowest precedence)
 ```
 
 ```zixir
@@ -888,6 +890,56 @@ let bigger = max(5, 3)  # 5
 
 ---
 
+## 6c. Pipe Operator
+
+The pipe operator `|>` passes the result of the left expression as the **first argument** to the function on the right. This lets you chain transformations in a readable, top-to-bottom style instead of nesting function calls.
+
+### Basic Usage
+
+```zixir
+# Without pipe (nested, reads inside-out)
+upper(trim("  hello  "))
+
+# With pipe (reads left-to-right)
+"  hello  " |> trim() |> upper()    # "HELLO"
+```
+
+### Piping into Functions with Arguments
+
+When the right-side function takes additional arguments, the piped value becomes the first argument:
+
+```zixir
+fn add(a, b): a + b
+10 |> add(5)           # 15 (same as add(10, 5))
+
+"hello world" |> contains("world")  # true
+```
+
+### Chaining Multiple Pipes
+
+```zixir
+# Clean and transform a string
+"  Hello World  " |> trim() |> lower() |> length()   # 11
+
+# Convert and format
+-42 |> abs() |> to_string()    # "42"
+```
+
+### Pipe with Built-in Functions
+
+All 25+ built-in functions work with pipes:
+
+```zixir
+[3, 1, 2] |> reverse()        # [2, 1, 3]
+[1, 2, 3] |> length()         # 3
+42 |> type_of()                # "Int"
+"abc" |> upper()               # "ABC"
+```
+
+> **Tip:** The pipe operator has the lowest precedence, so `3 + 4 |> to_string()` evaluates `3 + 4` first, then pipes `7` into `to_string()`.
+
+---
+
 ## 7. Control Flow
 
 Control flow lets your program make decisions and repeat actions.
@@ -2390,6 +2442,10 @@ map["key"]
 # Field access
 object.field
 
+# Pipe operator
+expression |> function_name()
+expression |> function_name(extra_arg)
+
 # Parentheses
 (expression)
 ```
@@ -2409,6 +2465,7 @@ object.field
 | `==` `!=` | 6 | Equality |
 | `&&` | 7 | Logical AND |
 | `||` | 8 | Logical OR |
+| `\|>` | 9 | Pipe (lowest precedence) |
 
 ### Function Definition
 
@@ -2480,6 +2537,7 @@ const PI = 3.14159          # Compile-time constant
 # Other
 ++   # String/array concatenation
 []   # Array/map indexing
+|>   # Pipe (chains function calls)
 ```
 
 ### Built-in Functions
@@ -2570,7 +2628,7 @@ python "random" "random" ()
 
 ### Common Patterns
 
-**Note:** Loops with index are not supported in Zixir v1.0. Use engine operations instead.
+**Note:** Loops don't support variable accumulation (Zixir is immutable). Use recursion, pipes, or engine operations instead.
 
 **Filter array (using engine):**
 ```zixir

docs/Zixir Language complete guide.pdf

@@ -184,6 +184,7 @@ <h3>Grammar in brief</h3>
       <li><strong>Expressions</strong> — literals (numbers, strings, lists, maps), variables, binary ops (<code>+</code>, <code>-</code>, <code>*</code>, <code>/</code>, <code>%</code>)</li>
       <li><strong>Maps &amp; indexing</strong> — <code>user["name"]</code> bracket access, <code>keys(map)</code>, <code>values(map)</code></li>
       <li><strong>Built-in functions</strong> — <code>length</code>, <code>print</code>, <code>to_string</code>, <code>type_of</code>, <code>split</code>, <code>join</code>, <code>range</code>, <code>reverse</code>, <code>abs</code>, <code>min</code>, <code>max</code>, and more</li>
+      <li><strong>Pipe operator</strong> — <code>value |> transform() |> format()</code> chain functions left-to-right</li>
       <li><strong>engine.</strong><code>op(args)</code> — call into the Zig engine (e.g. <code>engine.list_sum([1.0, 2.0, 3.0])</code>)</li>
       <li><strong>python</strong> <code>"module" "function" (args)</code> — call Python (e.g. <code>python "math" "sqrt" (4.0)</code>)</li>
       <li><strong>match</strong> — pattern matching on values</li>
@@ -192,10 +193,11 @@ <h3>How it runs</h3>
     <p style="color: var(--zixir-text-muted); font-size: 0.95rem;">Source is parsed in Elixir into a Zixir AST. It can be <strong>interpreted</strong> (<code>Zixir.eval(source)</code> — engine calls run in Zig NIFs, python calls go to Python via a port) or <strong>compiled</strong> (<code>Zixir.Compiler.compile(source)</code> — type-checks, optimizes, emits Zig; then compile to a native binary or run JIT). Your code stays Zixir-only; the runtime is Elixir + Zig + Python.</p>
     <div class="landing-code" style="margin-top: 1rem;">let data = [1.0, 2.0, 3.0, 4.0, 5.0]
 let total = engine.list_sum(data)
-let count = length(data)
+let count = data |> length()
+let label = total |> to_string() |> upper()
 let user = {"name": "Alice", "score": total}
-print("User: " ++ user["name"] ++ ", items: " ++ to_string(count))
-# result: "User: Alice, items: 5"</div>
+print("User: " ++ user["name"] ++ ", total: " ++ label)
+# result: "User: Alice, total: 15.0"</div>
     <p style="margin-top: 0.75rem; font-size: 0.9rem;"><a href="LANGUAGE.md" style="color: var(--zixir-purple-400);">Full language spec → LANGUAGE.md</a></p>
   </section>
 
@@ -217,7 +219,7 @@ <h3>What's inside</h3>
     <h3>Key features</h3>
     <p style="color: var(--zixir-text-muted); font-size: 0.95rem;">Progressive learning · Every concept explained · 20+ complete examples · 4 real projects · Exercises with solutions · Visual aids · Error handling · AI-focused automation workflows.</p>
     <h3>Guide statistics</h3>
-    <p style="color: var(--zixir-text-muted); font-size: 0.95rem;">40+ pages · 20+ code examples · 4 major projects · 6 practice exercises per chapter · 25+ built-in functions · 22 engine operations · Modulo, map indexing, type conversions · Complete grammar reference · Quick reference card.</p>
+    <p style="color: var(--zixir-text-muted); font-size: 0.95rem;">40+ pages · 20+ code examples · 4 major projects · 6 practice exercises per chapter · 25+ built-in functions · 22 engine operations · Pipe operator, modulo, map indexing, type conversions · Complete grammar reference · Quick reference card.</p>
     <p style="margin-top: 1rem;"><a href="https://github.com/Zixir-lang/Zixir/blob/master/docs/Zixir%20Language%20complete%20guide.md" style="color: var(--zixir-purple-400); font-weight: 600;">→ Zixir Language complete guide (read on GitHub)</a> · <a href="https://github.com/Zixir-lang/Zixir/raw/master/docs/Zixir%20Language%20complete%20guide.md" style="color: var(--zixir-purple-400); font-weight: 600;">Download (Markdown)</a> · <a href="Zixir%20Language%20complete%20guide.pdf" style="color: var(--zixir-purple-400); font-weight: 600;">Download PDF</a></p>
     <p style="font-size: 0.85rem; color: var(--zixir-text-muted);">To rebuild the PDF locally: <code>npx md-to-pdf "docs/Zixir Language complete guide.md"</code> then keep the generated <code>Zixir Language complete guide.pdf</code>; or use <code>.\scripts\build-guide-pdf.ps1</code> (pandoc + LaTeX).</p>
   </section>

docs/index.html

@@ -149,11 +149,21 @@ defmodule Zixir.Interpreter do
   end
 
   defp eval_expr({:engine_call, func_name, args, _line, _col}, env) do
-    # Engine call: engine.list_sum([...])
     with {:ok, evaled_args} <- eval_args(args, env) do
       op = String.to_atom(func_name)
-      result = Zixir.Engine.run(op, evaled_args)
-      {:ok, result}
+      try do
+        result = Zixir.Engine.run(op, evaled_args)
+        {:ok, result}
+      rescue
+        e in ArgumentError ->
+          {:error, "Engine operation #{func_name} failed: #{Exception.message(e)}"}
+        e in ArithmeticError ->
+          {:error, "Engine operation #{func_name} failed: #{Exception.message(e)}"}
+        _e in FunctionClauseError ->
+          {:error, "Engine operation #{func_name}: invalid arguments #{inspect(evaled_args)}"}
+        e ->
+          {:error, "Engine operation #{func_name} failed: #{Exception.message(e)}"}
+      end
     end
   end
 
@@ -245,18 +255,20 @@ defmodule Zixir.Interpreter do
   end
 
   defp eval_expr({:pipe, left_expr, right_expr}, env) do
-    # Pipe operator: left |> right
     with {:ok, left_val} <- eval_expr(left_expr, env) do
-      # Inject left value as first argument to right expression
       case right_expr do
+        {:call, func, args, line, col} ->
+          eval_expr({:call, func, [{:literal, left_val} | args], line, col}, env)
         {:call, func, args} ->
-          eval_expr({:call, func, [left_val | args]}, env)
+          eval_expr({:call, func, [{:literal, left_val} | args]}, env)
         _ ->
           {:error, "Right side of pipe must be a function call"}
       end
     end
   end
 
+  defp eval_expr({:literal, value}, _env), do: {:ok, value}
+
   defp eval_expr({:async, expr, _line, _col}, env) do
     # For now, async just evaluates synchronously
     # In a full implementation, this would spawn a Task

lib/zixir/interpreter.ex

@@ -102,6 +102,7 @@ defmodule Zixir.Parser.Unified do
     "->" => :arrow,
     "=>" => :fat_arrow,
     ".." => :range_op,
+    "|>" => :|>,
     "<" => :lt,
     ">" => :gt
   }
@@ -402,9 +403,15 @@ defmodule Zixir.Parser.Unified do
   defp parse_block(tokens), do: {nil, tokens}
 
   defp parse_block_contents([{:op, :"}", _, _} | rest], acc), do: {{:block, Enum.reverse(acc)}, rest}
-  
+
+  defp parse_block_contents([], _acc) do
+    raise ParseError, message: "Unexpected end of input, expected '}' to close block", line: 0, column: 0
+  end
+
   defp parse_block_contents(tokens, acc) do
     case parse_statement(tokens) do
+      {nil, []} ->
+        raise ParseError, message: "Unexpected end of input, expected '}' to close block", line: 0, column: 0
       {nil, rest} -> parse_block_contents(rest, acc)
       {stmt, rest} -> parse_block_contents(rest, [stmt | acc])
     end
@@ -500,7 +507,23 @@ defmodule Zixir.Parser.Unified do
   # Parser - Expressions (with operator precedence)
   # ============================================================================
 
-  defp parse_expression(tokens), do: parse_or(tokens)
+  defp parse_expression(tokens), do: parse_pipe(tokens)
+
+  defp parse_pipe(tokens) do
+    {left, rest} = parse_or(tokens)
+    case rest do
+      [{:op, :|>, _, _} | rest2] ->
+        {right, rest3} = parse_or(rest2)
+        parse_pipe_chain({:pipe, left, right}, rest3)
+      _ -> {left, rest}
+    end
+  end
+
+  defp parse_pipe_chain(left, [{:op, :|>, _, _} | rest]) do
+    {right, rest2} = parse_or(rest)
+    parse_pipe_chain({:pipe, left, right}, rest2)
+  end
+  defp parse_pipe_chain(left, rest), do: {left, rest}
 
   defp parse_or(tokens) do
     {left, rest} = parse_and(tokens)
@@ -755,11 +778,6 @@ defmodule Zixir.Parser.Unified do
     parse_identifier_suffix({:field, expr, field}, rest)
   end
 
-  defp parse_identifier_suffix(expr, [{:op, :|>, _, _} | rest]) do
-    {right, rest2} = parse_unary(rest)
-    parse_identifier_suffix({:pipe, expr, right}, rest2)
-  end
-  
   defp parse_identifier_suffix(expr, rest), do: {expr, rest}
 
   defp parse_arg_list(tokens), do: parse_arg_list_impl(tokens, [])

lib/zixir/parser/unified.ex

@@ -31,7 +31,7 @@ defmodule Zixir.REPL do
   require Logger
 
   @welcome_message """
-  Welcome to Zixir REPL v0.1.0
+  Welcome to Zixir REPL v7.1.0
   Type :help for help, :quit to exit
   
   """
@@ -194,45 +194,28 @@ defmodule Zixir.REPL do
   end
 
   defp evaluate(code, state) do
-    case Zixir.eval(code) do
-      {:ok, result} ->
-        # Extract any new variable bindings from the code
-        new_env = extract_bindings(code, result, state.env)
-        
-        # Print result (unless it's nil from a let statement)
+    case Zixir.Interpreter.eval(code, state.env) do
+      {:ok, result, new_env} ->
         if result != nil do
           IO.puts(format_result(result))
         end
-        
+
         {:continue, %{state | env: new_env, history: [code | state.history]}}
-      
+
+      {:error, message} when is_binary(message) ->
+        IO.puts("Error: #{message}")
+        {:continue, %{state | multiline_buffer: "", line_count: 0}}
+
       {:error, %Zixir.CompileError{} = error} ->
         IO.puts("Error: #{error.message}")
-        if error.line && error.line > 0 do
-          IO.puts("  at line #{error.line}, column #{error.column}")
-        end
         {:continue, %{state | multiline_buffer: "", line_count: 0}}
-      
+
       {:error, reason} ->
         IO.puts("Error: #{inspect(reason)}")
         {:continue, %{state | multiline_buffer: "", line_count: 0}}
     end
   end
 
-  defp extract_bindings(code, _result, env) do
-    # Simple extraction of let bindings
-    # In a full implementation, we'd parse and track all bindings properly
-    case Regex.run(~r/^let\s+(\w+)\s*=/, code) do
-      [_, var_name] ->
-        # Re-evaluate to get the value
-        case Zixir.eval(code) do
-          {:ok, value} -> Map.put(env, var_name, value)
-          _ -> env
-        end
-      _ -> env
-    end
-  end
-
   defp format_result(result) when is_float(result) do
     # Format floats nicely
     if result == trunc(result) do