@shd101wyy/yo 0.1.27 → 0.1.29

package/.github/skills/yo-syntax/syntax-cheatsheet.md

@@ -78,7 +78,17 @@ if(done, println("done"), println("pending"));
 - Always write `match(...)`, never bare `match ...`
 - `if(a, b)` and `if(a, b, c)` are macro forms over `cond`
 - Write `return(value)` or `return()`; `return value` is invalid.
-- Write `escape(value)` or `escape()`; `escape value` is invalid.
+- Write `unwind(value)` or `unwind()`; `unwind value` is invalid.
+- If a `match`/`cond` branch returns an enum variant and inference fails, qualify
+  the variant with its enum type: `TypeValue.Unit` instead of `.Unit`.
+- Do not match enum payload literals directly, e.g. avoid `.Some(false)` and
+  `.Some(true)` as sibling branches. Match `.Some(value)` once, then branch with
+  `if(value, ...)` or `cond(...)` inside the arm; otherwise generated C can
+  contain duplicate enum `case` labels.
+- In large enum matches, avoid binding a pattern variable with the same name as a
+  variant field (for example, prefer `struct_field_types` over `field_types`).
+  This can currently produce invalid generated C in some self-hosted codegen
+  paths.
 
 ## String types
 
@@ -111,7 +121,7 @@ masked := ((A | B) | C);
 - Yo has no operator precedence; fully parenthesize binary expressions
 - Preserve grouping around infix expressions on operator RHS positions: `true => (x / y)`, `value := (x + y)`, `(ptr &+ 1).*`
 - Line breaks can disambiguate operator chains; keep line-leading operators like `(4\n| 5\n| 6)` and newlines after `:` before a lambda unless you add equivalent grouping
-- When an operator ends a line, indent its RHS one level as a continuation: `(given(x) : T) =\n  (v) -> { ... }`
+- When an operator ends a line, indent its RHS one level as a continuation: `(x : T) =\n  (v) -> { ... }`
 - Prefix operators (`!`, `&`, `-`, `~`) require parenthesized operands: `func(&(s), a, b)`, `!(ready)`, `-(value)`.
 - Tight special forms also require immediate parentheses: `#(expr)`, `?*(u8)`, `T <: !(Runtime)`
 - Dynamic field access with unquote must keep grouping after the dot: `value.(#(field_expr))`, not `value.#(field_expr)`.
@@ -140,6 +150,8 @@ impl(Counter,
 ```
 
 - No space between a function type and its body: `(fn(...) -> T)(...)`
+- Top-level aliases for function types need parentheses too:
+  `Callback :: (fn(x : i32) -> i32);`, not `Callback :: fn(x : i32) -> i32;`
 - Use `Self` in method signatures and in type definitions for recursive references (the type name is not available during its own definition)
 - `Self` also works inside generic type constructors — it refers to the current instantiation (e.g., `Tree(T)` inside `Tree`). Use `recur(args)` only when type arguments differ from the current instantiation.
 - Use `struct(...)` for record and effect-record types. The legacy `module(...)`,
@@ -168,12 +180,12 @@ create_user(name: `Bob`, age: 30);
 - Named arguments must keep the same order as the definition
 - Default values use `?=` and must be compile-time known
 
-### Implicit parameters (`using` / `given`)
+### Effect parameters (explicit)
 
 ```rust
-Raise :: (fn(msg : String) -> i32);
+Raise :: (ctl(msg : String) -> i32);
 
-safe_divide :: (fn(x : i32, y : i32, using(raise : Raise)) -> i32)(
+safe_divide :: (fn(x : i32, y : i32, raise : Raise) -> i32)(
   cond(
     (y == i32(0)) => raise(`divide by zero`),
     true => (x / y)
@@ -181,18 +193,20 @@ safe_divide :: (fn(x : i32, y : i32, using(raise : Raise)) -> i32)(
 );
 
 caller :: (fn() -> i32)({
-  (given(raise) : Raise) = (fn(msg : String) -> i32)({
-    return(i32(0));
+  // Handler value bound to a local. Lambdas on the RHS of `=` need outer parens.
+  (raise : Raise) = ((msg) -> {
+    unwind(i32(0));
   });
 
-  safe_divide(i32(10), i32(0))
+  safe_divide(i32(10), i32(0), raise)
 });
 ```
 
-- `using(name : Type)` declares an implicit parameter (effect)
-- `given(name) := Type(fields...)` installs a handler in the caller's scope
-- Effects are matched by **type**, not by name
-- The handler is auto-resolved at call sites; pass explicitly with `using(name)`
+- Effect handlers are regular parameters — pass them explicitly at the call site.
+- `ctl(args) -> R` types a handler that may `unwind` (discard the continuation).
+  Use plain `fn(args) -> R` for handlers that always resume.
+- Bundle multiple effects into a struct (`Ctx :: struct(raise : Raise, log : Log)`)
+  and pass one parameter when there are many.
 
 ### Closures and anonymous functions
 
@@ -250,15 +264,28 @@ text := match(value,
 Three destructuring shapes for arms (mix freely across arms):
 
 ```rust
-Shape :: enum(Circle(radius : i32), Rectangle(width : i32, height : i32));
+Shape :: enum(
+  Circle(radius : i32),
+  Rectangle(width : i32, height : i32),
+  Triangle(base : i32, height : i32, label : str)
+);
 
 match(s,
-  .Circle(r)                       => (r * r),         // positional
-  .Rectangle(width: w, height: h)  => (w * h),         // labeled
-  .Rectangle({width, height: h})   => (width * h)      // curly shorthand
+  // ✅ Preferred — curly shorthand names only the fields you use.
+  .Triangle({base, height: h})  => (base * h),
+
+  // Also OK — labeled (label : var) pairs; order-free, partial matches OK.
+  .Circle(radius: r)             => (r * r),
+
+  // ⚠️ Avoid for 2+ field variants — positional with `_` is brittle when
+  //    a field is added and harder to read (each `_` requires counting).
+  //    OK when the variant has one field, or when every field is named.
+  .Rectangle(w, h)               => (w * h)
 )
 ```
 
+**Preferred form**: `.Variant({label, label: alias})`. Names only the fields the arm binds, so adding a field to the variant later doesn't silently break every arm. `tests/match_curly.test.yo` is the spec.
+
 Curly `{a, b: c}` is sugar for `(a: a, b: c)` — order-free, supports partial matches (omit fields). Use `{label: _}` to ignore a specific field. Bare `{_}` and empty `{}` are rejected.
 
 > **Critical**: Within a single match arm, you must use **either all positional or all named** field patterns. Mixing positional and named fields in the same arm (e.g., `.Foo(x, y: z, w)`) causes C codegen to emit undeclared identifiers for the named fields. This is a parser/codegen limitation — do not mix.
@@ -553,6 +580,23 @@ Variable :: object(name : String, type : TypeValue);
 Variable :: object(name : String, ty : TypeValue);
 ```
 
+### 1-element array literals require a trailing comma
+
+`[expr]` without a trailing comma is **parsed as a Slice type** `Slice(expr)`, not an array literal. To create a 1-element array value, add a trailing comma:
+
+```rust
+// WRONG — parsed as Slice type, not array literal:
+arr := [i32(42)];
+
+// CORRECT — trailing comma makes it an array literal:
+arr := [i32(42),];
+
+// Multi-element arrays work fine (comma separator detected):
+arr2 := [i32(1), i32(2), i32(3)];  // ✓
+```
+
+This also applies inside source strings in proto-evaluator tests.
+
 ### ArrayList indexing uses call syntax
 
 ```rust
@@ -682,39 +726,38 @@ if(!cond, { do_thing(); });
 if((!cond), { do_thing(); });
 ```
 
-### `escape` requires a nested-function context
+### `unwind` requires a nested-function context
 
-`escape(value)` exits the **enclosing function** — the nearest `fn(...)` that
-wraps the current code. It requires that the code is inside a nested function
-(e.g., a closure or `given` handler lambda), NOT at the top level of a
-standalone function definition.
+`unwind(value)` exits the **install frame** — the function that bound the
+`ctl(...) -> R` value being called. It is only valid inside the body of a
+`ctl(...) -> R` value (an effect handler).
 
 ```rust
-// CORRECT — escape inside a given handler lambda (lambda has enclosing fn):
-given(exn) := Exception(throw: ((err) -> {
-  escape(result); // exits the outer function that contains this given()
-}));
-do_something(using(exn));
+Raise :: (ctl(msg : String) -> i32);
 
-// CORRECT — escape inside a closure passed as argument:
-result := match(opt, .Some(x) => x, .None => {
-  // This is NOT a nested function — use return:
-  // WRONG: escape(default_val)  // ERROR: no enclosing fn
-  return(default_val); // CORRECT: return exits the enclosing fn directly
+caller :: (fn() -> i32)({
+  // The handler is a `ctl` value bound in `caller`. `unwind` exits `caller`.
+  (raise : Raise) = ((msg) -> {
+    eprintln(msg);
+    unwind(i32(-1));
+  });
+  safe_divide(i32(10), i32(0), raise)  // call site: handler is passed explicitly
 });
 
-// WRONG — escape inside a match arm (not a nested fn):
-match(opt,
-  .Some(x) => { escape(x); }  // ERROR: "can only be used inside a function that has an enclosing function"
+// WRONG — `unwind` in a regular `fn` body (no install frame here) is rejected.
+bad :: (fn() -> unit)({
+  unwind(());  // ERROR: unwind requires a ctl(...) body
+});
+
+// WRONG — capturing a `ctl` value into a closure is rejected (closures escape).
+make_closure :: (fn(raise : Raise) -> Impl(Fn() -> unit))(
+  () => { raise(`x`); }  // ERROR: closure captures a control-bound value
 );
 ```
 
-**Rule of thumb**: Use `escape` only inside lambdas passed to `given()` handlers.
-In all other contexts (match arms, if blocks, begin blocks, top-level fn bodies),
-use `return` for early exit.
-
-`return` inside a lambda exits that lambda only; `escape` exits the OUTER function
-(the one that installed the `given` handler).
+**Rule of thumb**: `unwind` belongs only inside the lambda bound to a
+`ctl(...) -> R` handler. From any other position, use `return` to exit the
+current `fn`.
 
 ### Parameter reassignment
 
@@ -769,19 +812,19 @@ fn_taking_str((`prefix_${value}`).as_str());
 
 These features are powerful but less commonly used. Consult the linked docs for full details.
 
-| Feature                | Syntax hint                                              | Documentation                                                                                                          |
-| ---------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
-| Higher-Kinded Types    | `forall(F : (fn(comptime(T) : Type) -> comptime(Type)))` | [DESIGN.md § HKT](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#higher-kinded-types-hkt)           |
-| GADTs                  | `enum(IntVal(i : i32) -> recur(i32))`                    | [GADTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/GADTS.md)                                           |
-| Derive traits          | `derive(MyType, Eq, Hash, Clone, Ord, ToString)`         | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md)                           |
-| Type reflection        | `Type.get_info(T)` returns `TypeInfo`                    | [TYPE_REFLECTION.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/TYPE_REFLECTION.md)                       |
-| Inline assembly        | `asm("mov {0}, #42", out(reg, i32))`                     | [INLINE_ASSEMBLY.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/INLINE_ASSEMBLY.md)                       |
-| Metaprogramming        | `quote(...)`, `unquote(...)`, `unquote_splicing(...)`    | [DESIGN.md § Meta](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#meta-programming)                 |
-| Effect row variables   | `forall(...(E))` with `using(...(E))`                    | [ALGEBRAIC_EFFECTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ALGEBRAIC_EFFECTS.md)                   |
-| Custom derive rules    | `derive_rule(MyTrait, (fn(...) -> unquote(Expr)){...})`  | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md#user-defined-derive-rules) |
-| Isolated types         | `Iso(T)` for data-race-free parallelism                  | [ISOLATED.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ISOLATED.md)                                     |
-| Arc (atomic ref count) | `arc(value)`, `shared.(*)` for cross-thread sharing      | [ARC.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ARC.md)                                               |
-| Parallelism            | Thread pool, `io.spawn` for parallel work                | [PARALLELISM.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/PARALLELISM.md)                               |
+| Feature                    | Syntax hint                                              | Documentation                                                                                                          |
+| -------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Higher-Kinded Types        | `forall(F : (fn(comptime(T) : Type) -> comptime(Type)))` | [DESIGN.md § HKT](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#higher-kinded-types-hkt)           |
+| GADTs                      | `enum(IntVal(i : i32) -> recur(i32))`                    | [GADTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/GADTS.md)                                           |
+| Derive traits              | `derive(MyType, Eq, Hash, Clone, Ord, ToString)`         | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md)                           |
+| Type reflection            | `Type.get_info(T)` returns `TypeInfo`                    | [TYPE_REFLECTION.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/TYPE_REFLECTION.md)                       |
+| Inline assembly            | `asm("mov {0}, #42", out(reg, i32))`                     | [INLINE_ASSEMBLY.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/INLINE_ASSEMBLY.md)                       |
+| Metaprogramming            | `quote(...)`, `unquote(...)`, `unquote_splicing(...)`    | [DESIGN.md § Meta](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DESIGN.md#meta-programming)                 |
+| Effect bundle polymorphism | `forall(E : Type.Struct)` over a bundle struct           | [ALGEBRAIC_EFFECTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ALGEBRAIC_EFFECTS.md)                   |
+| Custom derive rules        | `derive_rule(MyTrait, (fn(...) -> unquote(Expr)){...})`  | [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md#user-defined-derive-rules) |
+| Isolated types             | `Iso(T)` for data-race-free parallelism                  | [ISOLATED.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ISOLATED.md)                                     |
+| Arc (atomic ref count)     | `arc(value)`, `shared.(*)` for cross-thread sharing      | [ARC.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ARC.md)                                               |
+| Parallelism                | Thread pool, `io.spawn` for parallel work                | [PARALLELISM.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/PARALLELISM.md)                               |
 
 ---
 
@@ -948,26 +991,6 @@ Always merge them into a single destructuring import:
 { Foo, Bar } :: import("../../mod.yo");
 ```
 
-### Implicit (`using`) parameters cannot be used with `:=` assignment
-
-Implicit effect parameters introduced via `using(name : Type)` cannot be bound
-to a discarded variable with `:= name`. They can only be passed via `using()`.
-To suppress "unused parameter" warnings for an implicit param, simply omit the
-discard assignment — implicit params never trigger unused-variable errors.
-
-```rust
-// WRONG — implicit variable cannot be used in assignment:
-foo :: (fn(using(exn : Exception)) -> unit)({
-  _ := exn;   // ERROR: Cannot use implicit variable "exn" in assignment
-  ()
-});
-
-// CORRECT — just omit the discard line:
-foo :: (fn(using(exn : Exception)) -> unit)({
-  ()
-});
-```
-
 ### Nested `Option` patterns require staging
 
 `match` does not support nested destructuring patterns like `.Some(.TypeVal(x))`.
@@ -1036,3 +1059,102 @@ match(outer_val,
   .None => { fallback() } // ← outer .None arm
 )                          // ← closes outer match
 ```
+
+### Nested enum patterns in match are NOT supported
+
+Yo does **not** support nested enum patterns inside a single match arm.
+You cannot write `.Some(.IntLit(n))` — this is a parser error.
+
+```rust
+// ❌ WRONG — nested enum pattern, parser error:
+match(v.get(usize(0)),
+  .Some(.IntLit(n)) => assert(n.as_str() == "3", "ok"),
+  _ => assert(false, "err")
+)
+
+// ✅ CORRECT — two-level match:
+match(v.get(usize(0)),
+  .Some(x) => match(x, .IntLit(n) => assert(n.as_str() == "3", "ok"), _ => assert(false, "err")),
+  .None => assert(false, "err")
+)
+```
+
+This applies to ALL nested enum patterns: `.Some(.BoolVal(b))`, `.Some(.ArrayVal(arr))`, etc. — always use a two-level match.
+
+### `get_callee()` returns ExprVal directly, not an Option-wrapped EnumVal
+
+In the proto-evaluator source strings (`evaluate_module_body`), `ExprVal.get_callee()` on a FnCall returns the callee `ExprVal` directly — NOT wrapped in an `Option` EnumVal. Chaining `.is_some()` fails with SIGABRT because `is_some()` requires an `EnumVal` receiver.
+
+```rust
+// ❌ SIGABRT — get_callee() returns ExprVal, not Option(EnumVal)
+result := quote(foo(i64(1))).get_callee().is_some();
+
+// ✅ Chain .is_atom() or .is_fn_call() on the returned ExprVal
+result := quote(foo(i64(1))).get_callee().is_atom();   // true: callee "foo" is an atom
+result := quote(foo(i64(1))).get_callee().is_fn_call(); // false: callee "foo" is not a fn call
+```
+
+Similarly, calling `get_callee()` on an Atom causes the overall evaluation to fail — do not test the Atom case via `get_callee()` in source strings.
+
+### Source-string evaluation pitfalls (proto-evaluator tests)
+
+When writing source strings passed to `evaluate_module_body` in proto-evaluator tests:
+
+**`cond` form**: Always use the `cond(condition => value, true => fallback)` form, NOT `cond(condition, value, fallback)`. The 3-arg form does NOT work inside lambdas or recursive functions in source strings.
+
+```
+// ❌ WRONG — crashes inside lambdas and recursive functions
+cond((n <= i32(1)), i32(1), (n * recur((n - i32(1)))))
+
+// ✅ CORRECT
+cond((n <= i32(1)) => i32(1), true => (n * recur((n - i32(1)))))
+```
+
+**Recursive functions**: Use `recur(...)` for self-recursion inside named `::` functions. Never call the function by name from inside its own body.
+
+**Chaining function calls with operators**: `f(a) + f(b) + f(c)` throws an exception. Use fold over an array instead:
+
+```
+// ❌ WRONG — exception in source strings
+result := abs_val(i32(3)) + abs_val(i32(1)) + abs_val(i32(4));
+
+// ✅ CORRECT
+arr := [i32(3), i32(1), i32(4)];
+result := arr.fold(i32(0), (fn(acc : i32, x : i32) -> i32)((acc + abs_val(x))));
+```
+
+**Empty array `[]` in cond branches**: `cond(condition => [x], true => [])` crashes because the empty array type is unknown. Avoid empty array literals in conditional branches inside `flat_map` lambdas.
+
+**Option types**: Must use `Option(T).Some(val)` not `Option.Some(val)`. `Option(T).None` with a type annotation crashes — use `r := Option(i32).None` without annotation. `.is_none()` is not supported; use `!(r.is_some())`. `and_then(f)` returns the raw value (not wrapped in Option), so calling `.unwrap_or()` on the result crashes.
+
+**Number literals**: `i32(-3)` crashes — use `(i32(0) - i32(3))`. `i32.as_usize()` / `usize.as_i32()` not supported.
+
+**Fibonacci without tmp variable**: `b = (a + b); a = (b - a)` computes fib correctly without a temp variable. After N iterations, `a` holds fib(N) and `b` holds fib(N+1).
+
+**3-term multiplication in source strings**: `(x * x * x)` causes an exception in evaluated source strings. Break it into a block:
+
+```
+// ❌ WRONG — causes exception
+cubes := arr.map((fn(x : i32) -> i32)((x * x * x)));
+
+// ✅ CORRECT — use a block with a local binding
+cubes := arr.map((fn(x : i32) -> i32)({
+  sq := (x * x);
+  (sq * x)
+}));
+```
+
+**3-term sum in fold on tuples**: `(acc + p.0 + p.1)` inside a fold lambda on tuple pairs crashes. Always map pairs to scalars first, then fold:
+
+```
+// ❌ WRONG — crashes in fold on (i32, i32) tuples
+total := pairs.fold(i32(0), (fn(acc : i32, p : (i32, i32)) -> i32)((acc + p.0 + p.1)));
+
+// ✅ CORRECT — map to scalars first, then fold
+sums := pairs.map((fn(p : (i32, i32)) -> i32)((p.0 + p.1)));
+total := sums.fold(i32(0), (fn(acc : i32, x : i32) -> i32)((acc + x)));
+```
+
+**`&&` in `cond` conditions inside `while` body**: Crashes. Avoid by restructuring (e.g., start loop at 1 instead of 0 to eliminate the `&& (i > 0)` guard).
+
+**Test API format**: Use `evaluate_module_body(exprs, &(env))` (reference syntax, returns `Option`). Match with function-style `match(result, .None => ..., .Some(m) => ...)`. Do NOT use block-style `match(result) { ... }` — it causes a parse error ("Paren-less function and operator calls are not supported").

package/README.md

@@ -8,6 +8,8 @@
 
 https://shd101wyy.github.io/Yo
 
+**LLM-friendly to write, human-friendly to read.**
+
 A multi-paradigm, general-purpose, compiled programming language.
 Yo aims to be **Simple** and **Fast** (around 0% - 15% slower than C).