@shd101wyy/yo 0.1.16 → 0.1.18

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

@@ -0,0 +1,48 @@
+---
+name: yo-async-effects
+description: Write Yo async code and algebraic effect handlers. Use this when working with IO, Future, JoinHandle, using/given, io.async, io.await, io.spawn, return, and escape.
+argument-hint: "[async task, effect, or API]"
+---
+
+# Yo Async and Effects
+
+Use this skill for single-threaded async workflows and algebraic-effect-based APIs in Yo.
+
+If a repository wraps these primitives, keep the same semantics and verify whether the wrapper changes naming only or behavior too.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- write functions with `using(io : IO)`
+- return or consume `Future(...)` values
+- run tasks with `io.async`, `io.await`, or `io.spawn`
+- define or handle effects via `using(...)` and `given(...)`
+- reason about `return` versus `escape` in handlers
+
+## Workflow
+
+1. Decide whether the task needs sequential async, concurrent async on one thread, or true parallelism.
+2. Add the necessary `using(...)` parameters to function signatures and call sites.
+3. Use the [async and effects recipes](./async-effects-recipes.md) for working patterns.
+4. Re-check handler semantics before finalizing:
+   - `return value` resumes the continuation
+   - `escape expr` discards it
+
+## High-signal rules
+
+- `io.async(fn)` creates a lazy future; it does not start until awaited or spawned.
+- `io.await(future)` runs or waits for the future and returns its result.
+- `io.spawn(future)` starts it without waiting and returns `JoinHandle(T)`.
+- `handle.await(using(io))` returns `Option(T)`; `.None` means the task aborted via `escape`.
+- Future types include their effects: `Future(ResultType, IO, Effect...)`.
+- Effects are matched by type, not variable name.
+- `using(name : Type)` declares an implicit effect parameter; `given(name) := Type(...)` installs the handler.
+- `return value` inside a handler resumes the continuation; `escape expr` discards it.
+- `Exception` — non-resumable; handler calls `escape` to exit. `ResumableException(T)` — handler calls `return` to resume.
+- Effect handlers are standalone, not closures; pass state explicitly.
+- Yo async is single-threaded concurrency, not multithreaded parallelism.
+
+## Resource
+
+- [Yo async and effects recipes](./async-effects-recipes.md)

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

@@ -0,0 +1,262 @@
+# Yo Async and Effects Recipes
+
+These patterns cover normal Yo async code and algebraic effects.
+
+## Pick the right execution model
+
+| Need                       | Pattern                                                   |
+| -------------------------- | --------------------------------------------------------- |
+| Sequential async work      | `result := io.await(task)`                                |
+| Start work and wait later  | `handle := io.spawn(task)` then `handle.await(using(io))` |
+| Yield to other ready tasks | `io.await(yield())`                                       |
+| True multithreading        | Use thread or parallelism APIs, not `io.async` alone      |
+
+## Minimal async function
+
+```rust
+{ yield } :: import "std/async";
+
+pause_then_answer :: (fn(using(io : IO)) -> Impl(Future(i32, IO)))(
+  io.async((using(io : IO)) => {
+    io.await(yield());
+    i32(42)
+  })
+);
+```
+
+- `io.async(...)` is lazy
+- If a function uses `using(io : IO)` and returns a future, include `IO` in the `Future(...)` type
+
+## Sequential await
+
+```rust
+{ yield } :: import "std/async";
+
+main :: (fn(using(io : IO)) -> unit)({
+  task := io.async((using(io : IO)) => {
+    io.await(yield());
+    i32(1)
+  });
+
+  result := io.await(task);
+  assert((result == i32(1)), "unexpected result");
+});
+
+export main;
+```
+
+## Concurrent tasks on the same thread
+
+```rust
+{ yield } :: import "std/async";
+
+main :: (fn(using(io : IO)) -> unit)({
+  task1 := io.async((using(io : IO)) => {
+    io.await(yield());
+    i32(1)
+  });
+  task2 := io.async((using(io : IO)) => {
+    io.await(yield());
+    i32(2)
+  });
+
+  handle1 := io.spawn(task1);
+  handle2 := io.spawn(task2);
+
+  result1 := handle1.await(using(io));
+  result2 := handle2.await(using(io));
+});
+
+export main;
+```
+
+- `io.spawn(...)` begins execution without waiting
+- `handle.await(using(io))` returns `Option(T)` because a spawned task can abort via `escape`
+
+## Propagating and handling effects
+
+```rust
+open import "std/fmt";
+open import "std/string";
+
+Raise :: (fn(msg : String) -> i32);
+
+safe_divide :: (fn(x : i32, y : i32, using(raise : Raise)) -> i32)(
+  cond(
+    (y == i32(0)) => raise(`divide by zero`),
+    true => (x / y)
+  )
+);
+
+resume_example :: (fn() -> i32)({
+  (given(raise) : Raise) = (fn(msg : String) -> i32)({
+    println(msg);
+    return i32(0);
+  });
+
+  safe_divide(i32(8), i32(0))
+});
+
+escape_example :: (fn() -> i32)({
+  (given(raise) : Raise) = (fn(msg : String) -> i32)({
+    println(msg);
+    escape i32(-1);
+  });
+
+  safe_divide(i32(8), i32(0))
+});
+```
+
+| Handler action | Meaning                                      |
+| -------------- | -------------------------------------------- |
+| `return value` | Resume the continuation with `value`         |
+| `escape expr`  | Exit the function that installed the handler |
+
+## Futures with multiple effects
+
+```rust
+{ yield } :: import "std/async";
+
+work :: (fn(using(io : IO, raise : Raise)) -> Impl(Future(i32, IO, Raise)))(
+  io.async((using(io : IO, raise : Raise)) => {
+    io.await(yield());
+    safe_divide(i32(10), i32(2), using(raise))
+  })
+);
+```
+
+- Every effect used by the future should appear in the `Future(...)` type
+- Effects propagate through `using(...)` just like other contextual parameters
+
+## 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
+
+## Exception (non-resumable)
+
+`Exception` is a built-in module effect for non-resumable error handling. When the handler calls `escape`, the continuation is discarded:
+
+```rust
+open import "std/error";
+open import "std/fmt";
+
+DivError :: enum(DivByZero);
+impl(DivError, ToString(to_string : ((self) -> `division by zero`)));
+impl(DivError, Error());
+
+safe_divide :: (fn(x : i32, y : i32, using(exn : Exception)) -> i32)(
+  cond(
+    (y == i32(0)) => exn.throw(dyn(DivError.DivByZero)),
+    true => (x / y)
+  )
+);
+
+main :: (fn() -> unit)({
+  given(exn) := Exception(
+    throw : ((err) -> {
+      println(`Error: ${err}`);
+      escape ();
+    })
+  );
+
+  result := safe_divide(i32(10), i32(2));
+  println(`result: ${result}`);
+
+  safe_divide(i32(10), i32(0));
+});
+
+export main;
+```
+
+- `Exception` has a single field `throw : (fn(error : AnyError) -> T)`
+- `exn.throw(dyn(error))` calls the handler with a type-erased error
+- Handler uses `escape` to discard the continuation and exit the enclosing function
+- Code after the escaped call is never reached
+
+## ResumableException
+
+`ResumableException(ResumeType)` is a module effect for resumable error handling. The handler uses `return` to resume with a recovery value:
+
+```rust
+open import "std/error";
+open import "std/fmt";
+
+safe_divide :: (fn(x : i32, y : i32, using(exn : ResumableException(i32))) -> i32)(
+  cond(
+    (y == i32(0)) => exn.throw(dyn(`division by zero`)),
+    true => (x / y)
+  )
+);
+
+main :: (fn() -> unit)({
+  given(exn) := ResumableException(i32)(
+    throw : ((err) -> {
+      println(`Recovering from: ${err}`);
+      return i32(0);
+    })
+  );
+
+  result := safe_divide(i32(10), i32(0));
+  assert((result == i32(0)), "recovered with 0");
+});
+
+export main;
+```
+
+- Handler uses `return value` to resume the continuation with the recovery value
+- The call site receives the returned value and continues normally
+
+## Module effects vs function-type effects
+
+Effects in Yo can be plain function types or module types:
+
+```rust
+Raise :: (fn(msg : String) -> i32);
+
+Logger :: module(
+  log : (fn(level : i32, msg : String) -> unit)
+);
+```
+
+Both kinds use `using(...)` / `given(...)` with the same semantics — they compile to evidence passing (function pointers as implicit C parameters). Module effects group related operations under a single name.
+
+## Async with effects
+
+When an async future uses effects, include them in the `Future` type:
+
+```rust
+work :: (fn(using(io : IO, exn : Exception)) -> Impl(Future(i32, IO, Exception)))(
+  io.async((using(io : IO, exn : Exception)) => {
+    io.await(yield());
+    safe_divide(i32(10), i32(2), using(exn))
+  })
+);
+```
+
+To spawn a task with effects, pass them explicitly via `using`:
+
+```rust
+handle := io.spawn(task, using(io, exn));
+result := handle.await(using(io));
+match(result,
+  .Some(value) => println(`got: ${value}`),
+  .None => println("task aborted via escape")
+);
+```
+
+## Effect row variables (advanced)
+
+Functions can be polymorphic over their effects using spread parameters:
+
+```rust
+wrapper :: (fn(forall(...(E)), x : i32, using(...(E))) -> i32)(
+  safe_divide(x, i32(2))
+);
+```
+
+- `forall(...(E))` introduces an effect row variable
+- `using(...(E))` forwards whatever effects the caller provides
+- See [ALGEBRAIC_EFFECTS.md](https://github.com/shd101wyy/Yo/blob/develop/docs/en-US/ALGEBRAIC_EFFECTS.md) for the full design

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

@@ -0,0 +1,48 @@
+---
+name: yo-core-patterns
+description: Write everyday Yo application and library code. Use this when choosing Yo types, imports, strings, Option/Result, collections, traits, boxes, pointers, and standard-library modules.
+argument-hint: "[feature, data type, or module]"
+---
+
+# Yo Core Patterns
+
+Use this skill for normal Yo program structure and standard-library usage rather than compiler internals.
+
+If a repository defines local wrappers or conventions, follow them after these baseline patterns.
+
+## When to use this skill
+
+Use this skill when you need to:
+
+- pick between built-in types and standard-library types
+- choose import paths for common Yo modules
+- model optional values or recoverable errors
+- write collection-heavy, string-heavy, or trait-based code
+- handle boxes, pointers, and platform-specific branches
+
+## Workflow
+
+1. Identify whether the task is about data modeling, strings, containers, errors, or imports.
+2. Choose the smallest built-in or standard-library type that fits the job.
+3. Use the [core patterns cheatsheet](./core-patterns-cheatsheet.md) for imports, strings, `Option`/`Result`, traits, and collections.
+4. Prefer standard modules before inventing custom helpers.
+
+## High-signal rules
+
+- `"` creates `str` in runtime code; template strings create `String`. In `comptime` functions, `"hello"` is `comptime_string` (distinct from `str`).
+- Prefer template strings for constant `String` values.
+- Prefer `print`/`println` from `std/fmt` over `printf`.
+- `Option(T)` and `Result(T, E)` are the default nullable/error carriers.
+- Use `rune` for Unicode code points, not `Char`.
+- Model nullable pointers with `Option(*(T))` or `?*(T)`.
+- Use `struct` for value types, `newtype` for single-field wrappers, `object` for reference-counted types.
+- Use `forall` + `where` for generic impls; use `_` placeholder for partial application of comptime functions.
+- Use `derive(Type, Eq, Hash, Clone, Ord, ToString)` to auto-generate common trait impls.
+- Custom error types implement `ToString` + `Error`; wrap with `dyn(...)` into `AnyError`.
+- Use `(params) => expr` for closures; `Impl(Fn(...) -> T)` for the closure type.
+- Use `for collection.iter(), (item) => { ... }` for iteration.
+- Indexed modules import cleanly as `std/url`, `std/regex`, `std/http`, `std/log`, and `std/glob`; multi-module families use explicit submodules.
+
+## Resource
+
+- [Yo core patterns cheatsheet](./core-patterns-cheatsheet.md)

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

@@ -0,0 +1,318 @@
+# Yo Core Patterns Cheatsheet
+
+These patterns are aimed at everyday Yo application and library code.
+
+## Strings and output
+
+```rust
+open import "std/fmt";
+open import "std/string";
+
+(name : str) = "yo";
+greeting := `Hello ${name}`;
+
+println(greeting);
+println("plain str is also fine");
+```
+
+- `"hello"` is a `str` literal in normal runtime code
+- `` `hello ${name}` `` creates a `String`
+- Prefer template strings for constant `String` values instead of `String.from("...")`
+- Prefer `print`/`println` when a type implements `ToString`
+
+### String type disambiguation
+
+| Type              | When you see it                              | Key behavior                           |
+| ----------------- | -------------------------------------------- | -------------------------------------- |
+| `str`             | `"hello"` in runtime contexts                | Slice of bytes, no ownership           |
+| `String`          | Template strings `` `hello` ``               | Owned UTF-8, reference-counted         |
+| `comptime_string` | `"hello"` inside `comptime` functions/macros | Compile-time only, distinct from `str` |
+
+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")`.
+
+## Import patterns
+
+```rust
+{ LocalType } :: import "./local_type.yo";
+open import "std/string";
+{ ArrayList } :: import "std/collections/array_list";
+{ HashMap } :: import "std/collections/hash_map";
+{ Url } :: import "std/url";
+{ Regex } :: import "std/regex";
+{ fetch, HttpRequest } :: import "std/http";
+```
+
+| Need                           | Import pattern                                                                       |
+| ------------------------------ | ------------------------------------------------------------------------------------ |
+| Local module in same directory | `./file.yo`                                                                          |
+| Module with a clean index      | `std/url`, `std/regex`, `std/http`, `std/log`, `std/glob`                            |
+| Collections                    | `std/collections/array_list`, `std/collections/hash_map`, `std/collections/hash_set` |
+| File system                    | `std/fs/file`, `std/fs/dir`, `std/path`                                              |
+| Networking                     | `std/net/tcp`, `std/net/udp`, `std/net/dns`                                          |
+
+Do not import `std/prelude`; it is already available.
+
+## Option and Result
+
+```rust
+open import "std/string";
+
+(value : Option(i32)) = .Some(i32(21));
+doubled := value.map((x) => (x * i32(2)));
+fallback := value.unwrap_or_else(() => i32(0));
+
+(parsed : Result(i32, String)) = .Ok(i32(42));
+text := match(parsed,
+  .Ok(n) => `value=${n}`,
+  .Err(err) => err
+);
+```
+
+- Use `Option(T)` when absence is expected and ordinary
+- Use `Result(T, E)` when the caller should handle failure
+- Prefer combinators for straight-line transforms: `map`, `and_then`, `map_err`, `or_else`
+- Switch to `match(...)` when branches need different logic or side effects
+
+## Collections
+
+```rust
+{ ArrayList } :: import "std/collections/array_list";
+{ HashMap } :: import "std/collections/hash_map";
+open import "std/string";
+
+numbers := ArrayList(i32).new();
+numbers.push(i32(1));
+numbers.push(i32(2));
+
+counts := HashMap(String, i32).new();
+counts.set(`yo`, i32(1));
+```
+
+| Type             | Use when                                 |
+| ---------------- | ---------------------------------------- |
+| `ArrayList(T)`   | Ordered growable sequence                |
+| `HashMap(K, V)`  | Key/value lookup with `Eq` + `Hash` keys |
+| `HashSet(T)`     | Membership tests and deduplication       |
+| `BTreeMap(K, V)` | Ordered map with `Ord` keys              |
+| `Deque(T)`       | Push/pop on both ends                    |
+| `String`         | Owned UTF-8 text                         |
+
+## Traits and associated types
+
+```rust
+Iterator :: trait(
+  Item : Type,
+  next : (fn(self : *(Self)) -> Option(Self.Item))
+);
+```
+
+- Traits use labeled fields directly inside `trait(...)`
+- Associated types are fields like `Item : Type` or `Output : Type`
+- Wrap `fn` types in parentheses inside traits and type annotations
+
+## Boxes, pointers, and nullability
+
+```rust
+counter := box(i32(0));
+counter.* = (counter.* + i32(1));
+
+(ptr : Option(*(u8))) = .None;
+```
+
+- 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
+
+## Unicode and platform checks
+
+```rust
+{ Platform, platform } :: import "std/process";
+
+separator := cond(
+  (platform == Platform.Windows) => `\\`,
+  true => `/`
+);
+```
+
+- Use `rune` for Unicode code points
+- Branch on `platform` and `Platform` for OS-specific behavior
+
+## Type categories
+
+```rust
+Point :: struct(x : i32, y : i32);
+
+FilePermission :: newtype(mode : u32);
+
+TcpStream :: object(fd : i32, buffer : ArrayList(u8));
+```
+
+| Keyword        | Semantics                               |
+| -------------- | --------------------------------------- |
+| `struct(...)`  | Value type, copied on assignment        |
+| `newtype(...)` | Single-field value wrapper              |
+| `object(...)`  | Reference-counted, shared on assignment |
+
+- Use `newtype(...)` when the type has exactly one field
+- Use `object(...)` for types that need shared ownership
+
+## Impl blocks and generics
+
+```rust
+impl(Point,
+  distance : (fn(self : Self, other : Point) -> f64)({
+    dx := f64((self.x - other.x));
+    dy := f64((self.y - other.y));
+    sqrt(((dx * dx) + (dy * dy)))
+  })
+);
+
+impl(forall(T), where(T <: ToString), Box(T),
+  show : (fn(self : Self) -> unit)(
+    println(self.*)
+  )
+);
+```
+
+- Use `Self` inside impl method signatures
+- `forall(T)` + `where(T <: Trait)` for generic impls
+- Trait impls: `impl(MyType, MyTrait(args), : trait_field_bindings...)`
+
+## Partial application
+
+```rust
+IntResult :: Result(_, i32);
+(r : IntResult(bool)) = .Ok(true);
+
+add :: (fn(comptime(x) : i32, comptime(y) : i32) -> comptime(i32))((x + y));
+add1 :: add(i32(1), _);
+```
+
+- Use `_` placeholder in comptime function calls to partially apply
+- Works with type constructors: `Result(_, i32)` makes a one-argument type function
+- Only valid for functions with `comptime` return types
+
+## Dynamic dispatch
+
+```rust
+(value : Dyn(ToString)) = dyn(i32(42));
+println(value);
+```
+
+- `Dyn(Trait)` is a type-erased trait object
+- `dyn(expr)` wraps a concrete value into the trait object
+- `Impl(Trait)` is the static dispatch counterpart
+
+## Derive traits
+
+```rust
+Point :: struct(x : i32, y : i32);
+derive(Point, Eq, Hash, Clone, Ord, ToString);
+
+p1 := Point(1, 2);
+p2 := p1.clone();
+assert((p1 == p2), "equal after clone");
+println(p1.to_string());
+```
+
+- Built-in derivable traits: `Eq`, `Hash`, `Clone`, `Ord`, `ToString`
+- 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)
+
+## Error handling
+
+```rust
+open import "std/error";
+
+DivError :: enum(DivByZero);
+impl(DivError, ToString(to_string : ((self) -> `division by zero`)));
+impl(DivError, Error());
+
+safe_div :: (fn(a : i32, b : i32) -> Result(i32, DivError))(
+  cond(
+    (b == i32(0)) => .Err(.DivByZero),
+    true => .Ok((a / b))
+  )
+);
+```
+
+- Custom error types implement both `ToString` and `Error` traits
+- `AnyError` is `Dyn(Error)` — wraps any error: `(err : AnyError) = dyn(MyError.Foo)`
+- Use `downcast(err, MyError)` to recover the concrete type from `AnyError`
+- For exception-style control flow, see [yo-async-effects](../yo-async-effects/SKILL.md)
+
+## Closures as values
+
+```rust
+(inc : Impl(Fn(x : i32) -> i32)) = ((x) => (x + i32(1)));
+result := inc(i32(5));
+
+transform :: (fn(values : ArrayList(i32), f : Impl(Fn(x : i32) -> i32)) -> unit)({
+  for values.iter(), (ptr) => {
+    ptr.* = f(ptr.*);
+  };
+});
+```
+
+- `(params) => expr` creates a closure
+- `Impl(Fn(params) -> ReturnType)` is the closure type
+- Closures capture: value types by copy, object types by reference
+- Each closure has a unique type
+
+## Iterator and for loop
+
+```rust
+{ ArrayList } :: import "std/collections/array_list";
+
+list := ArrayList(i32).new();
+list.push(i32(1));
+list.push(i32(2));
+
+for list.iter(), (ptr) => {
+  println(ptr.*);
+};
+
+for list.into_iter(), (value) => {
+  println(value);
+};
+```
+
+| Method         | Yields | Semantics                           |
+| -------------- | ------ | ----------------------------------- |
+| `.iter()`      | `*(T)` | Borrow via pointer; yields pointers |
+| `.into_iter()` | `T`    | Takes ownership; yields values      |
+
+- Implement `Iterator` trait to make custom types iterable
+- Implement `IntoIterator` trait for collection-style iteration
+
+## Module-level mutable variables
+
+```rust
+counter := i32(0);
+
+inc :: (fn() -> unit)({
+  counter = (counter + i32(1));
+});
+```
+
+- Top-level `:=` creates a C `static` file-scope variable
+- Cannot be exported; only compile-time values can be exported
+- Not allowed inside `impl` blocks; use `::` for constants there
+
+## Anonymous modules
+
+```rust
+my_module :: impl {
+  helper :: (fn(x : i32) -> i32)((x + i32(1)));
+  export helper;
+};
+
+result := my_module.helper(i32(5));
+```
+
+- `impl { ... }` creates a module namespace
+- Only `::` (compile-time) bindings are allowed inside