Merge pull request #47 from mgomes/mgomes/v0-16-0o

v0.16.0: control flow and error handling

Author: mgomes

ROADMAP.md

@@ -176,17 +176,17 @@ Goal: make types expressive enough for real workflows while keeping runtime chec
 
 ### Type Semantics
 
-- [ ] Specify variance/invariance rules for container assignments.
-- [ ] Specify nullability interactions with unions (`T?` vs `T | nil`).
-- [ ] Define coercion policy (no coercion vs explicit coercion helpers).
-- [ ] Decide strictness for unknown keyword args under typed signatures.
+- [x] Specify variance/invariance rules for container assignments.
+- [x] Specify nullability interactions with unions (`T?` vs `T | nil`).
+- [x] Define coercion policy (no coercion vs explicit coercion helpers).
+- [x] Decide strictness for unknown keyword args under typed signatures.
 
 ### Runtime and Parser
 
 - [x] Extend parser grammar for generic and union type expressions.
 - [x] Extend type resolver and internal type representation.
 - [x] Add runtime validators for composite/union types.
-- [ ] Add contract interop so capability contracts can reuse type validators.
+- [x] Add contract interop so capability contracts can reuse type validators.
 
 ### Testing and Docs
 
@@ -209,37 +209,37 @@ Goal: improve language ergonomics for complex script logic and recovery behavior
 
 ### Control Flow
 
-- [ ] Add `while` loops.
-- [ ] Add `until` loops.
-- [ ] Add loop control keywords: `break` and `next`.
-- [ ] Add `case/when` expression support (if approved).
-- [ ] Define behavior for nested loop control and block boundaries.
+- [x] Add `while` loops.
+- [x] Add `until` loops.
+- [x] Add loop control keywords: `break` and `next`.
+- [x] Add `case/when` expression support (if approved).
+- [x] Define behavior for nested loop control and block boundaries.
 
 ### Error Handling Constructs
 
 - [ ] Add structured error handling syntax (`begin/rescue/ensure` or equivalent).
 - [ ] Add typed error matching where feasible.
 - [ ] Define re-raise semantics and stack preservation.
-- [ ] Ensure runtime errors preserve original position and call frames.
+- [x] Ensure runtime errors preserve original position and call frames.
 
 ### Runtime Behavior
 
-- [ ] Ensure new control flow integrates with step quota accounting.
-- [ ] Ensure new constructs integrate with recursion/memory quotas.
-- [ ] Validate behavior inside class methods, blocks, and capability callbacks.
+- [x] Ensure new control flow integrates with step quota accounting.
+- [x] Ensure new constructs integrate with recursion/memory quotas.
+- [x] Validate behavior inside class methods, blocks, and capability callbacks.
 
 ### Testing and Docs
 
-- [ ] Add parser/runtime tests for each new control flow construct.
-- [ ] Add nested control flow tests for edge cases.
-- [ ] Add docs updates in `docs/control-flow.md` and `docs/errors.md`.
-- [ ] Add examples under `examples/control_flow/` for each new feature.
+- [x] Add parser/runtime tests for each new control flow construct.
+- [x] Add nested control flow tests for edge cases.
+- [x] Add docs updates in `docs/control-flow.md` and `docs/errors.md`.
+- [x] Add examples under `examples/control_flow/` for each new feature.
 
 ### v0.16.0 Definition of Done
 
-- [ ] No regressions in existing `if/for/range` behavior.
+- [x] No regressions in existing `if/for/range` behavior.
 - [ ] Structured error handling works with assertions and runtime errors.
-- [ ] Coverage includes nested/edge control-flow paths.
+- [x] Coverage includes nested/edge control-flow paths.
 
 ---
 

docs/control-flow.md

@@ -1,27 +1,92 @@
 # Control Flow and Ranges
 
-VibeScript supports familiar Ruby control structures:
+VibeScript supports these control-flow forms:
 
-- `if/elsif/else` expressions
-- `for` loops iterating arrays or ranges
-- Numeric ranges via `start..finish`
+- `if` / `elsif` / `else`
+- `case` / `when` expressions
+- `for` loops over arrays and ranges
+- `while` and `until` loops
+- loop control with `break` and `next`
+- numeric ranges via `start..finish`
 
-Example range usage:
+## `for` loops
 
 ```vibe
-def fizzbuzz(limit)
-  for n in 1..limit
-    if n % 15 == 0
-      puts("FizzBuzz")
-    elsif n % 3 == 0
-      puts("Fizz")
-    elsif n % 5 == 0
-      puts("Buzz")
-    else
-      puts(n)
+def sum_first_five()
+  total = 0
+  for n in 1..5
+    total = total + n
+  end
+  total
+end
+```
+
+## `case` / `when` expressions
+
+`case` evaluates to the matching branch expression (or `nil` when no branch matches and no `else` is provided).
+
+```vibe
+def label(score)
+  case score
+  when 100
+    "perfect"
+  when 90, 95
+    "great"
+  else
+    "ok"
+  end
+end
+```
+
+## `while` and `until`
+
+```vibe
+def countdown(n)
+  out = []
+  while n > 0
+    out = out + [n]
+    n = n - 1
+  end
+  out
+end
+
+def count_up(limit)
+  out = []
+  n = 0
+  until n >= limit
+    out = out + [n]
+    n = n + 1
+  end
+  out
+end
+```
+
+## `break` and `next`
+
+```vibe
+def odds_under_five()
+  out = []
+  for n in [1, 2, 3, 4, 5]
+    if n == 5
+      break
+    end
+    if n % 2 == 0
+      next
     end
+    out = out + [n]
   end
+  out
 end
 ```
 
-See `examples/loops/` and `examples/ranges/` for runnable scripts.
+Semantics:
+
+- In nested loops, `break` and `next` target the nearest active loop.
+- `break`/`next` used outside any loop raise runtime errors.
+- `break`/`next` cannot cross call boundaries (for example from block callbacks back into outer loops).
+
+## Quotas
+
+Loop execution participates in step and memory quotas. Infinite loops will terminate with quota errors when limits are exceeded.
+
+See `examples/control_flow/`, `examples/loops/`, and `examples/ranges/` for runnable scripts.

docs/errors.md

@@ -37,6 +37,31 @@ division by zero
   at calculate (7:7)
 ```
 
+## Type Errors
+
+Typed argument and return checks include:
+
+- parameter or function context
+- expected type
+- actual runtime type
+
+```text
+argument payload expected { id: string, score: int }, got { id: string, score: string }
+```
+
+For composite values, actual types include shape/element detail (`array<int | string>`, `{ id: string, ... }`) to make fixes local and explicit.
+
+## Loop Control Errors
+
+Loop control diagnostics are explicit:
+
+- `break used outside of loop`
+- `next used outside of loop`
+- `break cannot cross call boundary`
+- `next cannot cross call boundary`
+
+These boundary errors happen when `break`/`next` are raised inside called blocks/functions and attempt to escape into an outer loop.
+
 ## REPL Debugging
 
 The REPL stores the previous failure. Use:

docs/typing.md

@@ -182,6 +182,43 @@ Typed blocks catch callback mismatches at runtime with errors that include param
 
 Duration methods like `ago`/`after` return `Time`. Typed signatures use `time` or `time?` for those values.
 
+## Type semantics
+
+### Container compatibility rules
+
+Container annotations are checked by validating contained values against the declared type.
+
+- `array<T>` validates every element with `T`.
+- `hash<K, V>` validates every key with `K` and every value with `V`.
+
+Practical consequence:
+
+- `array<int>` is valid for `array<number>` because each `int` satisfies `number`.
+- `array<number>` is only valid for `array<int>` when all elements are actually ints.
+
+### `T?` and `T | nil`
+
+`T?` and `T | nil` are equivalent at runtime: both accept `nil` and values matching `T`.
+
+- Prefer `T?` for simple optional values.
+- Use `T | nil` when you are already expressing a broader union (for example `int | string | nil`).
+
+### Coercion policy
+
+Typed checks do not perform implicit coercion.
+
+- `int` does not accept `"1"`.
+- `string` does not accept `1`.
+
+Convert explicitly before calling typed boundaries (for example `.to_i`, `.to_f`, `.string`, parsers/builders for time and duration).
+
+### Unknown keyword args under typed signatures
+
+Unknown keyword arguments are strict for all function calls, including typed signatures.
+
+- Extra keyword arguments raise `unexpected keyword argument <name>`.
+- This behavior is the same for typed and untyped functions.
+
 ## Notes and limitations
 
 - Types are nominal by kind.

examples/control_flow/case_when.vibe

@@ -0,0 +1,14 @@
+def label(score)
+  case score
+  when 100
+    "perfect"
+  when 90, 95
+    "great"
+  else
+    "ok"
+  end
+end
+
+def run()
+  [label(100), label(95), label(70)]
+end

examples/control_flow/loop_control.vibe

@@ -0,0 +1,19 @@
+def odds_below(limit)
+  out = []
+  n = 0
+  while n < limit
+    n = n + 1
+    if n == limit
+      break
+    end
+    if n % 2 == 0
+      next
+    end
+    out = out + [n]
+  end
+  out
+end
+
+def run()
+  odds_below(10)
+end

examples/control_flow/until_loop.vibe

@@ -0,0 +1,13 @@
+def collect_until(limit)
+  out = []
+  n = 0
+  until n >= limit
+    out = out + [n]
+    n = n + 1
+  end
+  out
+end
+
+def run()
+  collect_until(5)
+end

examples/control_flow/while_loop.vibe

@@ -0,0 +1,13 @@
+def countdown(start)
+  out = []
+  n = start
+  while n > 0
+    out = out + [n]
+    n = n - 1
+  end
+  out
+end
+
+def run()
+  countdown(5)
+end

vibes/ast.go

@@ -122,6 +122,38 @@ type ForStmt struct {
 func (s *ForStmt) stmtNode()     {}
 func (s *ForStmt) Pos() Position { return s.position }
 
+type WhileStmt struct {
+	Condition Expression
+	Body      []Statement
+	position  Position
+}
+
+func (s *WhileStmt) stmtNode()     {}
+func (s *WhileStmt) Pos() Position { return s.position }
+
+type UntilStmt struct {
+	Condition Expression
+	Body      []Statement
+	position  Position
+}
+
+func (s *UntilStmt) stmtNode()     {}
+func (s *UntilStmt) Pos() Position { return s.position }
+
+type BreakStmt struct {
+	position Position
+}
+
+func (s *BreakStmt) stmtNode()     {}
+func (s *BreakStmt) Pos() Position { return s.position }
+
+type NextStmt struct {
+	position Position
+}
+
+func (s *NextStmt) stmtNode()     {}
+func (s *NextStmt) Pos() Position { return s.position }
+
 type Identifier struct {
 	Name     string
 	position Position
@@ -276,6 +308,21 @@ type RangeExpr struct {
 func (e *RangeExpr) exprNode()     {}
 func (e *RangeExpr) Pos() Position { return e.position }
 
+type CaseWhenClause struct {
+	Values []Expression
+	Result Expression
+}
+
+type CaseExpr struct {
+	Target   Expression
+	Clauses  []CaseWhenClause
+	ElseExpr Expression
+	position Position
+}
+
+func (e *CaseExpr) exprNode()     {}
+func (e *CaseExpr) Pos() Position { return e.position }
+
 type BlockLiteral struct {
 	Params   []Param
 	Body     []Statement