kopscript 0.11.1 → 0.13.0

package/LLM.md

@@ -133,8 +133,8 @@ Dog d = new Dog("Rex");
   the interface in the base list and provide matching public methods, checked at compile time.
 - No nested classes/functions.
 - No multiple inheritance (at most one class in the base list; the rest must be interfaces).
-- `class Box<T> { ... }` — a single type parameter is allowed; see Generics below for the
-  full (deliberately scoped-down) rules.
+- `class Box<T> { ... }` / `class Pair<K, V> { ... }` — one or more type parameters are
+  allowed; see Generics below for the full (deliberately scoped-down) rules.
 
 ### Interfaces
 
@@ -145,7 +145,7 @@ interface IShape {
 interface INamedShape : IShape { // interfaces can extend other interfaces (not classes)
   string GetName();
 }
-interface IContainer<T> {      // interfaces take a single type parameter too — see Generics
+interface IContainer<T> {      // interfaces take type parameters too — see Generics
   T Get();
 }
 ```
@@ -281,7 +281,7 @@ Not a use of user-declared generics (see below) — `state<T>` is one of exactly
 hardcoded parametrized forms in the type system (the other is `task<T>`), each with only
 ever one built-in meaning, unlike a real generic class/interface.
 
-## Generics — a single type parameter on classes/interfaces
+## Generics — one or more type parameters on classes/interfaces
 
 ```ks
 class Box<T> {
@@ -293,38 +293,64 @@ class Box<T> {
 Box<number> nb = new Box<number>(5);   // type argument required on both the type AND `new`
 Box<string> sb = new Box<string>("hi");
 print(nb.Get());                        // 5
+
+class Pair<K, V> {
+  public K First;
+  public V Second;
+  constructor(K k, V v) { this.First = k; this.Second = v; }
+}
+
+Pair<number, string> p = new Pair<number, string>(1, "a");
 ```
 
-One unconstrained, invariant type parameter per class/interface (real *or* `extern` — see
-the `extern` section below) — the whole feature.
+One or more unconstrained, invariant type parameters per class/interface (real *or*
+`extern` — see the `extern` section below), comma-separated: `<T>`, `<K, V>`, `<A, B, C>`,
+however many the declaration needs.
 Erased at codegen (JS has no generics either; `Box<number>` and `Box<string>` both
 compile to the exact same plain `class Box`), so there's no runtime cost and no way to
-inspect `T` at runtime.
+inspect a type parameter at runtime.
 
 **Rules:**
-- The type argument is **required everywhere** a generic type is named — on the variable
-  type (`Box<number>`) and separately on `new` (`new Box<number>(...)`); a bare `Box` (no
-  argument) is a compile error, not "any"/inferred.
-- **Invariant**: `Box<Dog>` is not assignable to `Box<Animal>` even if `Dog : Animal` —
-  type arguments must match exactly, not just be compatible.
-- Nesting works: `Box<Box<number>>`, `Box<number[]>`, `Box<number>?`, `Box<number>?[]`.
-- Inside the class/interface's own body, `T` is fully abstract — you can store it, return
-  it, pass it around, but (unconstrained) you **cannot call any member on a bare `T`
-  value** (`this.value.Foo()` is a compile error: "Cannot access member 'Foo' on type
-  'T'"). This is correct, not a bug — same as an unconstrained type parameter in
-  C#/Java/TypeScript.
+- The type argument(s) are **required everywhere** a generic type is named — on the
+  variable type (`Box<number>`) and separately on `new` (`new Box<number>(...)`); a bare
+  `Box`/`Pair` (no arguments) is a compile error, not "any"/inferred. The count must match
+  the declaration exactly — `Pair<number>` (too few) and `Pair<number, string, bool>` (too
+  many) are both arity errors, not truncated/padded.
+- **Invariant, per slot**: `Box<Dog>` is not assignable to `Box<Animal>` even if `Dog :
+  Animal`, and `Pair<number, string>` is not assignable to `Pair<string, number>` — every
+  type argument must match exactly, in the same position, not just be compatible.
+- Nesting works: `Box<Box<number>>`, `Box<number[]>`, `Box<number>?`, `Box<number>?[]`,
+  `Pair<number, Pair<string, bool>>`.
+- Inside the class/interface's own body, each type parameter is fully abstract — you can
+  store it, return it, pass it around, but (unconstrained) you **cannot call any member on
+  a bare type-parameter value** (`this.value.Foo()` where `value: T` is a compile error:
+  "Cannot access member 'Foo' on type 'T'"). This is correct, not a bug — same as an
+  unconstrained type parameter in C#/Java/TypeScript.
+
+**Generic inheritance**: a class/interface base list CAN name a generic base, with its own
+type arguments, in either direction:
+```ks
+class IntBox : Box<number> { }        // concrete — threads a fixed type through
+class Container<T> : Box<T> {          // generic — threads its OWN T through
+  public T GetAgain() { return this.Get(); }
+}
+interface INumberContainer : IContainer<number> { }   // interfaces work the same way
+```
+Member resolution (fields, methods, an inherited constructor via `base(...)` or an implicit
+default) composes substitutions correctly however many generic-base links up the chain a
+member was actually declared — `Container<number>.Get()` (declared on `Box<T>`, two links
+away in a longer chain) resolves to `number`, not the abstract `T`. **v1 limit**: at most
+one generic entry across a class/interface's *whole* base list (its superclass, or one
+implemented/extended interface — never more than one) — `class Foo<T> : Box<T>,
+IContainer<T>` is a compile error ("has more than one generic entry in its base list") even
+though either half alone would work.
 
 **Does not exist (v1 scope cuts, each deliberate)**:
 - **Generic functions.** `T Identity<T>(T x)` doesn't parse — only classes and interfaces
-  take a type parameter, not free functions/methods themselves (a method *inside* a
-  generic class can use that class's own `T` freely, same as any other member).
-- **Multiple type parameters.** No `Map<K, V>` — exactly one `<T>` or none.
+  take type parameters, not free functions/methods themselves (a method *inside* a
+  generic class can use that class's own type parameters freely, same as any other member).
 - **Constraints.** No `T : IComparable` — a type parameter is always fully unconstrained,
-  which is why you can't call members on a bare `T` (see above).
-- **Generic inheritance.** A class/interface's base list can only name a *non-generic*
-  type — `class Foo : Box<number>` and even `class Foo<T> : SomeGenericBase<T>` are both
-  compile errors ("cannot extend/implement generic type '...' — not supported in v1"). A
-  generic class/interface can still extend/implement ordinary non-generic bases normally.
+  which is why you can't call members on a bare one (see above).
 - **Variance.** No `out`/`in`/covariance/contravariance — see invariance above.
 
 ## Nullable types — `T?`
@@ -402,11 +428,13 @@ KopScript-declared name exactly. Extern class members use real JS member names v
 (camelCase, no rename mechanism). No inheritance modeling between two `extern class`
 declarations — each stands alone.
 
-`extern class` can carry `<T>` (`extern class Box<T> { constructor(T v); T Value { get; } }
-from "some-package";`) — identical rules to a real generic class (see "Generics" above:
-one unconstrained invariant parameter, erased, no base-list generics), so a generic type
-from another package instantiates and type-checks exactly like a local one
-(`Box<number>`, arity/invariance errors included).
+`extern class` can carry type parameters (`extern class Box<T> { constructor(T v); T Value
+{ get; } } from "some-package";`) — identical rules to a real generic class (see "Generics"
+above: one or more unconstrained invariant parameters, erased, generic inheritance
+included), so a generic type from another package instantiates and type-checks exactly
+like a local one (`Box<number>`, arity/invariance errors included) — and a real KopScript
+class can extend a generic `extern class` with a concrete or threaded-through type
+argument, same as extending a real generic base.
 
 **Never write `async` on an extern function/method signature** — declare its return type
 as `task`/`task<T>` directly (`task<string> text();`, not `async task<string> text();`).
@@ -493,9 +521,10 @@ Locals/params: **camelCase**. This is convention, not enforced by the compiler.
 
 ## Does not exist (don't reach for these)
 
-Generics beyond a single unconstrained type parameter (no `Map<K, V>`, no `T : IFoo`
-constraints, no generic functions, no generic inheritance, no variance — see Generics
-above for what *is* supported) · `any`/`unknown` annotations ·
+Generics beyond one or more unconstrained type parameters and single-generic-base
+inheritance (no `T : IFoo` constraints, no generic functions, no variance, no more than one
+generic entry per base list — see Generics above for what *is* supported) ·
+`any`/`unknown` annotations ·
 a `let`/`var` keyword (locals are just `Type name = value;`) · decorators/annotations ·
 reflection · type inference on declarations · ternary expression · union/tuple types ·
 **object-literal syntax** (`{ key: value }` as a value — this doesn't exist *anywhere* in

package/README.md

@@ -22,9 +22,9 @@ LLM's context, as opposed to this README's narrative explanation.
   explicit `virtual`/`override` dispatch (methods are sealed unless marked `virtual`), and a full
   `public`/`protected`/`private` access model enforced at compile time.
 - **Strongly typed**: every declaration is explicitly typed and checked at compile time.
-- **Generics**: a single, unconstrained, invariant type parameter on classes and
-  interfaces (`class Box<T> { public T Value; }`) — erased at codegen with zero runtime
-  cost, the same way `task<T>`/`state<T>` already are.
+- **Generics**: one or more unconstrained, invariant type parameters on classes and
+  interfaces (`class Box<T> { public T Value; }`, `class Pair<K, V> { ... }`) — erased at
+  codegen with zero runtime cost, the same way `task<T>`/`state<T>` already are.
 - **Nullable types with compiler-enforced null-checking**: `T?` (`string?`, `Dog?`,
   `number[]?`) — a `T?` can't be used where a `T` is expected without an `if (x != null)`
   check first (checked statically, not just at runtime), and comparing a value that can
@@ -221,7 +221,7 @@ void Announce(ISpeaker s) {
 
 ### Generics
 
-Classes and interfaces can take a single type parameter:
+Classes and interfaces can take one or more type parameters:
 
 ```ks
 class Box<T> {
@@ -233,34 +233,58 @@ class Box<T> {
 Box<number> nb = new Box<number>(5);
 Box<string> sb = new Box<string>("hi");
 print(nb.Get());   // 5
+
+class Pair<K, V> {
+  public K First;
+  public V Second;
+  constructor(K k, V v) { this.First = k; this.Second = v; }
+}
+
+Pair<number, string> p = new Pair<number, string>(1, "a");
 ```
 
-The type argument is required everywhere the generic type is named — on the variable's
+The type argument(s) are required everywhere the generic type is named — on the variable's
 declared type *and* separately on `new` (`Box<number> nb = new Box<number>(5);`, not
-just one or the other). Generics are erased at codegen exactly like `task<T>`/`state<T>`
-already are — `Box<number>` and `Box<string>` compile to the identical plain `class Box`,
-so there's no runtime cost.
-
-This is deliberately the smallest useful slice of generics, not a scaled-down promise of
-more later inside v1:
-
-- **One type parameter, invariant, unconstrained.** No `Map<K, V>` (multiple parameters),
-  no `T : ISomething` (constraints) — and because `T` is fully unconstrained, you can't
-  call any member on a bare `T` value inside the generic class's own body (that's correct
-  behavior, the same restriction C#/Java/TypeScript put on an unconstrained parameter, not
-  a bug). Invariant means `Box<Dog>` is **not** assignable to `Box<Animal>` even though
-  `Dog : Animal` — type arguments must match exactly.
+just one or the other) — and the count must match the declaration exactly (`Pair<number>`
+alone, or `Pair<number, string, bool>`, are both arity errors). Generics are erased at
+codegen exactly like `task<T>`/`state<T>` already are — `Box<number>` and `Box<string>`
+compile to the identical plain `class Box`, so there's no runtime cost.
+
+Still a deliberately small slice of generics, not a scaled-down promise of more later
+inside v1:
+
+- **Invariant, unconstrained.** No `T : ISomething` (constraints) — and because a type
+  parameter is fully unconstrained, you can't call any member on a bare `T`/`K`/`V` value
+  inside the generic class's own body (that's correct behavior, the same restriction
+  C#/Java/TypeScript put on an unconstrained parameter, not a bug). Invariant means
+  `Box<Dog>` is **not** assignable to `Box<Animal>` even though `Dog : Animal`, and
+  `Pair<number, string>` is not assignable to `Pair<string, number>` — every slot must
+  match exactly, in order.
 - **No generic functions.** `T Identity<T>(T x)` isn't supported — only classes and
-  interfaces take a type parameter. A method *inside* a generic class can still use that
-  class's own `T` freely; it's just not introducing a type parameter of its own.
-- **No generic inheritance.** A class or interface's base list can only name a
-  *non-generic* type. `class Foo : Box<number>` and `class Foo<T> : SomeBase<T>` are both
-  compile errors — a generic class can still extend/implement ordinary non-generic bases
-  normally, it just can't be the one on either side of a generic base relationship.
+  interfaces take type parameters. A method *inside* a generic class can still use that
+  class's own type parameters freely; it's just not introducing one of its own.
+
+A class or interface *can* extend/implement a generic base, type arguments and all:
+
+```ks
+class IntBox : Box<number> { }                   // concrete: threads a fixed type through
+class Container<T> : Box<T> {                     // generic: threads its OWN T through
+  public T GetAgain() { return this.Get(); }
+}
+Container<number> c = new Container<number>(5);
+print(c.GetAgain());                               // 5, and c.Value/c.Get() work too
+```
+
+Member lookup (fields, methods, an inherited constructor) resolves correctly however many
+generic-base links up the chain a member was actually declared, substituting all the way
+down. **v1 limit**: at most one generic entry across a whole base list (the superclass, or
+one implemented interface — not several at once) — `class Foo<T> : Box<T>, IContainer<T>`
+is a compile error even though each half would work alone.
 
 See `LLM.md`'s "Generics" section for the exhaustive rules if you're generating code
-against this — nested generics (`Box<Box<number>>`, `Box<number>?[]`) and generic
-interfaces used as standalone parameter types both work and are covered there.
+against this — nested generics (`Box<Box<number>>`, `Box<number>?[]`, `Pair<number,
+Pair<string, bool>>`) and generic interfaces used as standalone parameter types both work
+and are covered there.
 
 ### Enums
 
@@ -359,11 +383,11 @@ consumes `Component`/`Router` themselves via `extern class ... from "kopular/...
 proving `extern` works as a real cross-*package* boundary, not just for describing DOM
 globals within a single project.
 
-An `extern class` can carry its own type parameter, `extern class Box<T> { ... }` —
-exactly the same single-type-parameter rules as a real generic class (see "Generics"
-above: invariant, unconstrained, erased, can't appear in a base list), so a generic type
-from another package (e.g. Kopular's `FormField<T>`) can be described and instantiated
-generically, not just per concrete type:
+An `extern class` can carry its own type parameter(s), `extern class Box<T> { ... }` or
+`extern class Pair<K, V> { ... }` — exactly the same rules as a real generic class (see
+"Generics" above: invariant, unconstrained, erased, and a real class can extend it as a
+generic base), so a generic type from another package (e.g. Kopular's `FormField<T>`) can
+be described and instantiated generically, not just per concrete type:
 
 ```ks
 extern class Box<T> {