feat(lang): extension functions on types — mapper Type.method(...)

Add a method to any type (primitive or user-defined) by qualifying the name:

    mapper Integer.double() -> Integer => this * 2
    mapper Person.fullName() -> String { return this.name + " " + this.family }

- parser: `Type.method` -> function `<TypeName>__method` with the receiver
  prepended as a `this` parameter (typed via primKindToCtype/identToCtype), so
  `this` / `this.field` work through ordinary codegen; emission unchanged.
- codegen: postfix dispatch `recv.method(args)` resolves to the extension when
  `<recvXtype>__method` exists, passing the receiver as the first arg. Keyed on
  the xtype (the type name, e.g. "Integer"/"Person"), so it matches receivers and
  chains (`n.double().plus(1)`). Any function kind works.

Verified on primitives, String, user types, predicates, args, chaining;
self-hosting fixpoint byte-identical; adds examples/extensions_test.xi.

Author: code-by-sia

compiler/impl/codegen/postfix.xi

@@ -10,6 +10,17 @@ mapper genPostfix(toks: Token[], pos: Integer, ctx: GCtx) -> ExprRes {
     let cont = true
     while cont {
         let k = gkind(toks, p)
+        // extension function call: recv.method(args) -> xc_<typ>__<method>(recv, args)
+        if (k == 107 or k == 129) and gkind(toks, p + 2) == 100 and isFuncNameC(ctx.prog, typ + "__" + gtext(toks, p + 1)) {
+            let ext = typ + "__" + gtext(toks, p + 1)
+            let al = genArgs(toks, p + 2, ctx)
+            let callArgs = code
+            if string_len(al.code) > 0 { callArgs = code + ", " + al.code }
+            code = "xc_" + ext + "(" + callArgs + ")"
+            typ = funcRetXType(ctx.prog, ext)
+            p = al.pos
+            continue
+        }
         if k == 107 or k == 129 {
             let fld = gtext(toks, p + 1)
             if isListXType(typ) and fld == "asSequence" {

compiler/impl/parser/decl_parser.xi

@@ -41,9 +41,21 @@ mapper parseFunc(ps: PState, isAsync: Bool, isCreator: Bool) -> FuncResult {
         }
     }
 
-    // name
+    // name — may be an extension function `Type.method`, e.g. `Integer.double`
+    // or `Person.fullName`. The receiver is passed as a `this` parameter, and the
+    // function is named `<recvSuffix>__<method>` (e.g. integer__double).
     let nameTok = peek(ps2)
     ps2 = advance(ps2)
+    let fname = nameTok.text
+    let extThis = ""
+    if peek(ps2).kind == 107 {                 // '.'  -> extension on a type
+        let recvCtype = identToCtype(nameTok.text)
+        if nameTok.kind >= 260 and nameTok.kind <= 269 { recvCtype = primKindToCtype(nameTok.kind) }
+        ps2 = advance(ps2)                     // '.'
+        fname = nameTok.text + "__" + peek(ps2).text   // keyed by xtype (the type name)
+        ps2 = advance(ps2)                     // method name
+        extThis = recvCtype + " this"
+    }
 
     // (params) — table-form decisions have none (columns are declared in the body)
     let pr = ParamResult { params: "", ps: ps2 }
@@ -53,6 +65,11 @@ mapper parseFunc(ps: PState, isAsync: Bool, isCreator: Bool) -> FuncResult {
         ps2 = pr.ps
         if peek(ps2).kind == 101 { ps2 = advance(ps2) }  // )
     }
+    // extension: prepend the receiver as `this` (so `this`/`this.field` just work)
+    if string_len(extThis) > 0 {
+        if string_len(pr.params) > 0 { pr = ParamResult { params: extThis + ", " + pr.params, ps: pr.ps } }
+        else { pr = ParamResult { params: extThis, ps: pr.ps } }
+    }
 
     // -> rettype
     let rr = parseRetType(ps2)
@@ -145,7 +162,7 @@ mapper parseFunc(ps: PState, isAsync: Bool, isCreator: Bool) -> FuncResult {
         isCreator: isCreator,
         isAsync: isAsync,
         kind: kindStr,
-        name: nameTok.text,
+        name: fname,
         params: pr.params,
         retCtype: retCtype,
         bodyTokens: br.bodyTokens,

docs/language-guide.md

@@ -291,6 +291,28 @@ Infix functions bind at low precedence (looser than arithmetic, like `to`), so
 `predicate`, `creator`, …); the `infix` modifier goes first, before `async` and
 the kind. See `examples/infix_demo.xi`.
 
+## Extension functions — `mapper Type.method(...)`
+
+Add a method to **any type** — a primitive or your own — by qualifying the name
+with the receiver type. Inside the body, `this` is the receiver:
+
+```x
+mapper Integer.double() -> Integer => this * 2
+
+type Person = { name: String, family: String }
+mapper Person.fullName() -> String { return this.name + " " + this.family }
+
+let n = 21
+n.double()                                  // 42
+Person { name: "Ada", family: "Lovelace" }.fullName()   // "Ada Lovelace"
+```
+
+Call them with the usual `receiver.method(args)` syntax. Extensions take regular
+parameters after the receiver, return like any function, and **chain**
+(`n.double().plus(1)`). Any function kind works (`mapper`, `predicate`, …). They
+desugar to a plain function taking the receiver as a `this` parameter, so there's
+no runtime cost. See `examples/extensions_test.xi`.
+
 ## `capture` — name a sub-expression's value
 
 `EXPR capture name: Type` evaluates `EXPR`, binds its value to `name` (of the

docs/skill.md

@@ -198,6 +198,15 @@ infix mapper plus(a: Integer, b: Integer) -> Integer { return a + b }
 5 plus 3            // 8
 ```
 
+**Extension functions** — qualify the name with a receiver type (primitive or
+user-defined) to add a method; `this` is the receiver. Chains like a method:
+
+```x
+mapper Integer.double() -> Integer => this * 2          // 21.double() ... use (21).double()
+type Person = { name: String, family: String }
+mapper Person.fullName() -> String { return this.name + " " + this.family }
+```
+
 **`capture`** — `EXPR capture name: Type` binds a sub-expression's value (the
 type annotation is required) and still yields it; the name is usable for the rest
 of the function (works in functions, methods, entry — not inside a `where` guard):

examples/extensions_test.xi

@@ -0,0 +1,27 @@
+// Feature: extension functions on types — `mapper Type.method(...)` with `this`.
+mapper Integer.double() -> Integer => this * 2
+mapper Integer.plus(n: Integer) -> Integer { return this + n }
+mapper String.shout() -> String { return this + "!" }
+type Pt = { x: Integer, y: Integer }
+mapper Pt.sum() -> Integer { return this.x + this.y }
+predicate Pt.isOrigin() { return this.x == 0 and this.y == 0 }
+
+test "extension on a primitive (Integer)" {
+    let n: Integer = 21
+    assertEq(n.double(), 42)
+    assertEq(n.plus(9), 30)
+}
+test "extension on String" {
+    let s = "hi"
+    assertEq(s.shout(), "hi!")
+}
+test "extension on a user type" {
+    let p = Pt { x: 3, y: 4 }
+    assertEq(p.sum(), 7)
+    assert not p.isOrigin()
+    assert Pt { x: 0, y: 0 }.isOrigin()
+}
+test "chained extension calls" {
+    let n: Integer = 5
+    assertEq(n.double().plus(1), 11)
+}