@shd101wyy/yo 0.1.23 → 0.1.25

package/.github/skills/yo-async-effects/async-effects-recipes.md

@@ -26,6 +26,17 @@ pause_then_answer :: (fn(using(io : IO)) -> Impl(Future(i32, IO)))(
 
 - `io.async(...)` is lazy
 - If a function uses `using(io : IO)` and returns a future, include `IO` in the `Future(...)` type
+- **Type annotations can be omitted** in the lambda's `using` params — the compiler infers types from the `Future(T, IO, Raise, ...)` return type. You can even rename the params:
+
+```rust
+// Equivalent — types inferred from Future(i32, IO, Raise) in the return type
+work :: (fn(using(io : IO, raise : Raise)) -> Impl(Future(i32, IO, Raise)))(
+  io.async((using(my_io, my_raise)) => {    // ← any names, no type annotations needed
+    my_io.await(yield());
+    my_raise("error")
+  })
+);
+```
 
 ## Sequential await
 
@@ -128,12 +139,50 @@ work :: (fn(using(io : IO, raise : Raise)) -> Impl(Future(i32, IO, Raise)))(
 - Every effect used by the future should appear in the `Future(...)` type
 - Effects propagate through `using(...)` just like other contextual parameters
 
+## Async recursion — use an iterative worklist instead
+
+`recur` does **not** work inside an `io.async` lambda — it refers to the lambda's own signature, not the outer function, so the argument types will not match. Calling the outer function by name is also forbidden in Yo. Attempting either will produce a compile-time error.
+
+**Solution**: replace async recursion with an iterative worklist using `ArrayList` as a stack:
+
+```rust
+{ read_dir, DirEntry } :: import "std/fs/dir";
+
+process_dir :: (fn(root: Path, using(io: IO, exn: Exception)) -> Impl(Future(unit, IO, Exception)))(
+  io.async((using(io, exn)) => {
+    stack := ArrayList(Path).new();
+    { stack.push(root); };
+
+    while runtime((stack.len() > usize(0))), {
+      cur := match(stack.pop(), .Some(p) => p, .None => return ());
+      entries := io.await(read_dir(cur));
+      // process `entries`, push subdirectories to `stack`
+      n := entries.len();
+      i := usize(0);
+      while runtime((i < n)), {
+        match(entries.get(i),
+          .None => (),
+          .Some(e) => {
+            match(e.file_type,
+              .Directory => { stack.push(cur.join(Path.new(e.name))); },
+              _ => ()   // handle files here
+            );
+          }
+        );
+        i = (i + usize(1));
+      };
+    };
+  })
+);
+```
+
 ## Common pitfalls
 
 - `io.async(...)` does not run immediately
 - `escape` inside async aborts the future instead of completing it normally
 - `io.await(...)` on an aborted future can panic; `JoinHandle.await(...)` converts abort into `.None`
 - Handler functions cannot capture outer variables like closures; pass required state explicitly
+- **`recur` inside `io.async` calls the lambda, not the outer function** — use an iterative worklist for async recursion
 
 ## Exception (non-resumable)
 
@@ -176,7 +225,31 @@ export main;
 - Handler uses `escape` to discard the continuation and exit the enclosing function
 - Code after the escaped call is never reached
 
-## ResumableException
+### Swallowing exceptions with a fallback value (return in Exception handler)
+
+When an exception is thrown inside an async operation (e.g., `cmd.status()` or `cmd.output()`), you can **swallow the error and resume with a fallback value** by using `return` in the handler (not `escape`). The `ResumeType` is the return type of the operation that would have thrown.
+
+```rust
+{ Command, ExitStatus, Output } :: import "std/process/command";
+
+// Check if a tool is available — returns false if it throws (e.g., not found)
+given(try_exn) := Exception(throw: ((err) -> {
+  return ExitStatus(raw: i32(1));  // resume with "failed" exit status
+}));
+status := io.await(cmd.status(using(io, try_exn)));
+available := status.success();  // false if exception was swallowed
+
+// For cmd.output(), resume with a failed Output:
+given(out_exn) := Exception(throw: ((err) -> {
+  return Output(status: ExitStatus(raw: i32(1)), stdout: ArrayList(u8).new(), stderr: ArrayList(u8).new());
+}));
+out := io.await(cmd.output(using(io, out_exn)));
+if((!(out.status.success())), { return (); });  // handle failure
+```
+
+Key: the `return` inside the handler resumes the _effect invocation site_ with the provided value. The calling code then sees the fallback as if the operation returned normally. Use `escape` only when the enclosing function returns `unit` (e.g., test bodies).
+
+**`escape T_value` constraint**: `escape T_value` inside an `Exception` handler requires that the enclosing `io.async` closure's return type matches `T_value`. Due to forward type inference, the evaluator may not know the closure's return type at the point where `given` is declared. This causes a "Expected: unit" error when `escape non_unit` is used in a handler declared before the final return expression. Prefer `return fallback_value` (resume) when possible.
 
 `ResumableException(ResumeType)` is a module effect for resumable error handling. The handler uses `return` to resume with a recovery value:
 

package/.github/skills/yo-core-patterns/core-patterns-cheatsheet.md

@@ -33,6 +33,7 @@ Key rules:
 - In **runtime** code, `"hello"` is always `str`. Mixing literal and variable branches in `cond`/`match` works fine.
 - In **comptime** functions (return type `comptime(...)`), `"hello"` is `comptime_string`. It does NOT auto-convert to `str`. Use `str.from_raw_parts(*(u8)("..."), usize(N))` if a comptime function needs to return `str`.
 - For `String` constants, prefer `` `hello` `` over `String.from("hello")`.
+- **PITFALL:** Never write `String.from(`hello`)` — backtick strings are already `String`, not `str`. `String.from` takes `str`, so wrapping a backtick in `String.from` causes a type error ("Cannot unify String and str"). Only use `String.from(str_expr)` for actual `str` values.
 
 ## Import patterns
 
@@ -88,6 +89,22 @@ numbers := ArrayList(i32).new();
 numbers.push(i32(1));
 numbers.push(i32(2));
 
+// Index via call syntax (Index trait) — returns the value directly:
+first := numbers(usize(0));  // → i32  (value)
+
+// Mutate in place — direct assignment syntax:
+numbers(usize(0)) = i32(99);
+
+// When you need the pointer explicitly:
+ptr := &(numbers(usize(0)));  // → *(i32)
+ptr.* = i32(100);
+
+// Safe access:
+match(numbers.get(usize(0)),
+  .Some(v) => println(`${v}`),
+  .None => ()
+);
+
 counts := HashMap(String, i32).new();
 counts.set(`yo`, i32(1));
 ```
@@ -126,6 +143,20 @@ counter.* = (counter.* + i32(1));
 - Use `Box(T)` or `box(value)` for owned heap allocation
 - Use `*(T)` for raw pointers
 - Model nullable pointers as `Option(*(T))` or `?*(T)`, not sentinel integers
+- Constructor syntax: `Box(T)(value)` — NOT `Box(T).new(value)`
+- For self-referential `object` types, use `Box(Self)` to break the recursive cycle:
+
+```rust
+Node :: object(
+  value : i32,
+  next  : Option(Box(Self))   // Box(Self) breaks the recursive type cycle
+);
+
+n := Node(value: i32(1), next: Option(Box(Node)).None);
+// Constructing a Box:
+child := Box(Node)(Node(value: i32(2), next: Option(Box(Node)).None));
+parent := Node(value: i32(1), next: Option(Box(Node)).Some(child));
+```
 
 ## Unicode and platform checks
 
@@ -225,6 +256,75 @@ println(p1.to_string());
 - Works for both structs and enums
 - Custom derives can be registered with `derive_rule`; see [DERIVE_TRAITS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/DERIVE_TRAITS.md)
 
+### ⚠️ Circular derive trap: recursive enum with `ArrayList`
+
+`derive(T, Eq)` and `derive(T, Clone)` fail when any field's type requires the derived trait to be already registered:
+
+```rust
+// PROBLEM: derive expansion generates `fields_l == fields_r` (ArrayList(Node) needs
+// Eq(Node)), but Eq(Node) isn't registered yet — compile error.
+Node :: enum(Leaf, Branch(children : ArrayList(Self)));
+derive(Node, Eq);  // ← ERROR: "No matching call found for __lhs_children == __rhs_children"
+```
+
+**Fix**: skip `derive`, write a manual recursive equality function with `recur`:
+
+```rust
+node_eq :: (fn(a : Node, b : Node) -> bool)(
+  match(a,
+    .Leaf => match(b, .Leaf => true, _ => false),
+    .Branch(acs) =>
+      match(b,
+        .Branch(bcs) => {
+          cond(
+            (acs.len() != bcs.len()) => false,
+            true => {
+              (i : usize) = usize(0);
+              (ok : bool) = true;
+              while runtime(((i < acs.len()) && ok)), {
+                match(acs.get(i),
+                  .Some(ac) => match(bcs.get(i),
+                    .Some(bc) => { ok = recur(ac, bc); },
+                    .None     => { ok = false; }
+                  ),
+                  .None => { ok = false; }
+                );
+                i = (i + usize(1));
+              };
+              ok
+            }
+          )
+        },
+        _ => false
+      )
+  )
+);
+
+impl(Node, Eq(Node)(
+  (==) : (fn(a : Self, b : Self) -> bool)(node_eq(a, b))
+));
+```
+
+Same issue applies to `Clone` when fields contain `ArrayList(Self)`.
+Yo's reference counting handles shallow copies automatically (no `Clone` trait call needed);
+the `Clone` trait is only for deep cloning and has the same circularity problem.
+In practice, passing `EvalValue`-like types by value works fine without a `Clone` impl.
+
+### Comparing complex enum types
+
+Complex enum types (structs/enums with nested fields) do not support `==`/`!=` unless `Eq` is
+derived or implemented. For **tag-only equality** (checking which variant), use a tag function:
+
+```rust
+// WRONG — TypeValue enum doesn't support !=
+if(my_type != t_unit(), { ... });
+
+// CORRECT — compare tags instead
+{ type_value_tag } :: import "../../types/type.yo";
+{ TypeTag }        :: import "../../types/tags.yo";
+if((type_value_tag(my_type) != TypeTag.TUnit), { ... });
+```
+
 ## Error handling
 
 ```rust
@@ -318,3 +418,18 @@ result := my_module.helper(i32(5));
 
 - `impl { ... }` creates a module namespace
 - Only `::` (compile-time) bindings are allowed inside
+
+## yo-self API: String vs str parameter gotchas
+
+Several `yo-self/` APIs take `String` (not `str`) parameters even when the argument is conceptually a name:
+
+- `get_variables_from_env(env, name: String)` — pass the `String` directly, do NOT call `.as_str()` first
+- Most other env/value/type lookup functions follow the same convention
+
+```rust
+// ❌ Wrong — .as_str() converts String → str but the param is String
+vars := get_variables_from_env(env, prop_name_su.as_str());
+
+// ✅ Correct — pass the String directly
+vars := get_variables_from_env(env, prop_name_su);
+```