# 06 - 面向对象与运算符重载

Viper 中的 `class` 有两种语义：**数据布局**（结构体/联合体/枚举，见 [05-classes.md](05-classes.md)）和**面向对象**。OOP 能力由**类内是否存在方法**自动判定（`StructEntry.IsOOP`）；多态用 `virtual`，非多态继承（C++ 风格，无 vtable 开销）用 `novirtual`。

> `@t.Object` 装饰器默认**不需要写、也尽量避免使用**——OOP 由「类内是否有方法」自动判定，写与不写行为一致。这是本文唯一一次提及，新代码请直接省略。

## 类修饰符（`virtual` / `novirtual`）

`virtual` / `novirtual` 是前置软关键字，**类级与方法级都可用**：

```python
virtual class Shape:            # 类级：默认该类所有方法都进虚表
    def area(self) -> float: ...
    novirtual def helper(self) -> int: ...   # 只有 helper 被排除出虚表

novirtual class Node:           # 类级：默认该类所有方法都非虚
    def plain(self) -> int: ...
    virtual def hooked(self) -> int: ...     # 只有 hooked 进虚表
```

- `virtual class` / `novirtual class`：**类级**修饰符——默认该类**所有方法**都采用这个级别；
- `virtual def` / `novirtual def`：**方法级**修饰符——只改变**单个方法**、覆盖类级默认，只能直接写在类体内；
- 例：`novirtual` 类里某个方法想进虚表，写 `novirtual class C:` + `virtual def m(self)`；反之 `virtual` 类里把某方法排除出虚表，写 `virtual class C:` + `novirtual def m(self)`；
- 非法形态（修饰符位置错误、`virtual virtual` 等）编译期 fail-fast。

## 面向对象（OOP）

类内定义成员方法即拥有面向对象支持（成员方法、运算符重载、属性装饰器等）；编译器根据「结构体内是否有函数定义」自动判定 OOP 行为。

### 基本定义

```python
class ViperKernel:
    BootInfo: bootinfo*
    VGA: vga._VGAScreenDriver*
    VGA_drv: vga._VGAScreenDriver

    def __init__(self):
        self.BootInfo = BootInfo
        serial.init()
        serial.puts("ViperOS VKernel Test\n")
```

避免在 `__init__` 中使用 `return`，虽然不会报错，但是你永远无法获得 `return` 的结果，如果需要提前结束代码流，`return` 也不失为一种办法。

### 成员方法

```python
class Sheet:
    id: int
    x: int
    y: int
    w: int
    h: int

    def __init__(self, x: int, y: int, w: int, h: int):
        self.x = x
        self.y = y
        self.w = w
        self.h = h

    def MoveTo(self, nx: int, ny: int):
        self.x = nx
        self.y = ny

    def Resize(self, nw: int, nh: int):
        self.w = nw
        self.h = nh
```

### 方法调用

```python
sheet: Sheet = Sheet(0, 0, 640, 480)
sheet.MoveTo(100, 100)
sheet.Resize(800, 600)
```

### 属性装饰器

支持 Python 的 `@property` 和 `@xxx.setter` 装饰器：

> `@xxx.setter` 和自定义装饰器正在试验阶段，尽可能不要使用

```python
class MyObj:
    _value: int

    @property
    def value(self) -> int:
        return self._value

    @value.setter
    def value(self, v: int):
        self._value = v
```

### 静态方法

```python
@staticmethod
def _yield():
    pass
```

### 对象指针与解引用

对象类实例通常通过指针操作：

```python
obj_ptr: MyClass* = &MyClass()
obj: MyClass = *obj_ptr
```

### 成员访问

通过 `self` 访问成员变量和方法：

```python
def method(self) -> void:
    self.x = 10
    y: int = self.y
    self.DoSomething()
```

### 内嵌对象

对象类可以包含其他对象实例（非指针）：

```python
class Sheet:
    _surf_obj: gfx.Surface
    _renderer_obj: gfx.Renderer
    surf: gfx.Surface*
    renderer: gfx.Renderer*

    def __init__(self, fb: uint32*, zb: float*, w: int, h: int):
        self._surf_obj = gfx.Surface(fb, zb, w, h)
        self.surf = &self._surf_obj
        self._renderer_obj = gfx.Renderer(self.surf)
        self.renderer = &self._renderer_obj
```

### `__before_init__` 方法

仅当类内含方法或继承虚方法时才生成 `__before_init__` 方法（纯数据 `class` 不生成）。它在 `__init__` 之前**自动填充成员默认值**，并对 `virtual` 类初始化 vtable：

```llvm
define void @"<SHA1>.ClassName.__before_init__"(%"<SHA1>.ClassName"* %self) {
entry:
  ; 对 virtual 类：存储 vtable 指针到 slot 0
  ; 遍历所有成员：若有默认值则 store 默认值，否则 store 零值
  ret void
}
```

**职责**：
- 填充类定义中声明的成员默认值（如 `x: int = 0` 中的 `0`）
- 对无默认值的成员填充类型零值
- 对 `virtual` 类额外初始化 vtable 指针

**调用时机**（由编译器在构造时自动插入）：
1. 不存在 `__new__` 时：在 `alloca` 分配之后调用一次，随后进入 `__init__`
2. 存在 `__new__` 时：在 `__new__` 之后对**最终存储指针**调用一次，随后进入 `__init__`

**关于 `__new__`**：
- `__new__` 返回 `self` 时使用默认的 `alloca` 存储
- `__new__` 的签名可与 `__init__` 不同
- `__new__` 与 `virtual` 兼容
- `__new__` 本身不入虚表

**就地构造**：用户也可手动调用 `__before_init__` 实现就地构造（placement new 语义），典型用法见 `mpool.alloc_buf`：

```python
buf: Buf* = pool.alloc(Buf.__sizeof__())
buf.__before_init__()          # 填充默认值
buf.__init__(args)             # 用户初始化逻辑
```

跨模块导入类时，导入侧也会声明 `__before_init__`，保证跨模块构造行为一致。

## `novirtual` 非多态继承

`novirtual` 启用 C++ 风格的非多态继承（对应 `struct A : B {}` 无 virtual）。与 `virtual` 的区别：

| 特性 | `novirtual` | `virtual` |
|------|---------------|--------------|
| vtable 指针 | ❌ 无 | ✅ 自动插入 slot 0 |
| 虚派发 | ❌ 无 | ✅ 支持 |
| 方法继承 | ✅ 调用点解析直调父类 | ✅ 通过 vtable |
| 字段展平 | ✅ 父类字段前置嵌入 | ✅ 父类字段前置嵌入（vtable 之后） |
| 运行时开销 | 零 | 每次虚调用一次间接跳转 |

### 基本定义

```python
novirtual class LinkedNode:
    next: LinkedNode*
    prev: LinkedNode*
    def append(self, node: LinkedNode*): ...

novirtual class GNode(LinkedNode):    # 非多态继承
    value: int
```

子类 `GNode` 的结构体布局为 `{next, prev, value}`（父类字段前置，无 vtable 指针）。

### 方法继承机制

子类调用父类方法时，实际机制为**调用点解析**：编译器沿 MRO（方法解析顺序）定位到**定义该方法**的父类，按字节偏移调整 `this` 指针后 `bitcast`，在调用点**直接调用**父类实现（无 wrapper 生成、无尾调用）。

> 这里的 MRO 为「深度优先 + 声明顺序 + 去重」（含自身），**不是** Python 的 C3 线性化；详见 [14-multiple-inheritance.md](14-multiple-inheritance.md)。

### 跨模块继承

跨模块父类（如 `linkedlist.LinkedNode`）的 `novirtual` 标记会在导入时被检测并记录，子类继承时同样跳过 vtable 插入。

### 向下转型

父类指针→子类指针需显式转型（生成 bitcast IR）：

```python
root: Node = Node()                    # Node 继承 LinkedNode
child: LinkedNode* = root.child
# child 是 LinkedNode*，需要转回 Node*：
node: Node* = (Node*)(child)
```

隐式转型仅向上（子→父）。

## `virtual` 虚函数表与多态

> **规划**：将引入 `T1 & T2`（TypeIntersection）表达 object（尤其是带 vtable 的 object）的交集类型，作为多态对象组合的静态类型手段（详见 02-type-system.md 类型组合规划演进，尚未实现）。

> 尽可能避免使用 `self[0]` 来获取结构体成员，其不稳定，也不要手动操作虚表。

用 `virtual`（类级）启用虚函数表支持。启用后，结构体第一个成员自动插入 `i8*` 类型的 vtable 指针。类内需有方法（OOP 行为由「结构体内是否有函数」自动判定）。

### 基本定义

```python
virtual class Base:
    def __init__(self):
        pass
    def method(self) -> int:
        return 0
```

在 LLVM IR 中，`virtual` 类的结构体类型自动插入 vtable 指针：

```llvm
%"<SHA1>.Base" = type { i8*, i32 }
```

同时，编译器会生成全局 vtable 变量。vtable 实为 `internal constant struct{ n x i8* }`——即含 n 个 `i8*` 函数指针成员的结构体常量（成员为带 `bitcast` 的初始化文本），变量名为 `<sha1>.Class.vtable`，并非 `[1 x i8*] zeroinitializer`：

```llvm
@"<sha1>.Base.vtable" = internal constant { i8* } {
  i8* bitcast (i32 (%"<sha1>.Base"*)* @"<sha1>.Base.method" to i8*)
}
```

### 继承与多态

虚表可以帮你使用继承语法实现多态：

```python
virtual class Base:
    def __init__(self):
        pass
    def method(self) -> int:
        return 0

virtual class M1(Base):
    def method(self) -> int:
        return 1
```

当 M1 被初始化时，VTable 会自动修改，这点和 C++ 相同，尽可能避免直接操作 VTable。

继承时，子类会自动继承父类的成员变量和方法。子类重写父类方法时，vtable 中对应位置的函数指针被子类方法替换，实现多态。

### VTable 运行时修改

如果需要临时构造一个额外的 `Base` 结构体，还可以使用：

```python
virtual class Base:
    def __init__(self):
        pass
    def method(self) -> int:
        return 0

def __method1(self) -> int:
    return 1

export def main() -> int:
    b: Base = Base()
    b.method = __method1
```

启用 `VTable` 的表中，允许直接修改内部函数为函数指针，在底层，此操作将修改 `VTable` 来达成目的。编译器会检测当前 vtable 是否与类 vtable 相同，如果相同则创建 vtable 的副本（memcpy），避免修改影响所有实例。

### 虚方法调度机制

虚方法调用的核心流程：

1. 从对象指针 GEP 获取第 0 个 slot（vtable 指针）
2. 加载 vtable 指针
3. bitcast 为 `[N x i8*]*` 类型
4. GEP 获取方法索引处的函数指针
5. 加载函数指针
6. bitcast 为正确的函数指针类型
7. 间接调用

### 方法级虚表开关

类级 `virtual` / `novirtual` 决定**该类所有方法的默认级别**；要单独改变**某一个方法**，就在该方法上加相反的方法级修饰符：

- `novirtual` 类中单独标注 `virtual def` 的方法进入虚表；
- `virtual` 类中单独标注 `novirtual def` 的方法被排除在虚表之外。

```python
novirtual class Node:                     # 默认：所有方法都非虚
    def plain(self) -> int: ...               # 跟随类级 → 非虚
    virtual def hooked(self) -> int: ...      # 仅 hooked 进虚表

virtual class Shape:                      # 默认：所有方法都进虚表
    def area(self) -> float: ...              # 跟随类级 → 虚
    novirtual def helper(self) -> int: ...    # 仅 helper 排除出虚表
```

以上行为由 `func_vtable_test` 实证。

### super()

`super().method(...)` 形态被编译为**静态父类方法调用**（仅该形态被支持），不经过 vtable 动态派发：

```python
virtual class Base:
    def method(self) -> void:
        pass

virtual class Derived(Base):
    def method(self) -> void:
        super().method()   # 静态调用父类实现
```

## 继承

### 结构体成员继承

当子类继承父类（父类在 `Gen.class_members` 中存在）时：

- 父类的成员变量被继承到子类（排在子类成员之前）
- 父类的默认值也被继承
- 父类的方法被继承（重命名为 `子类名.方法名`）

```python
class Animal:
    name: [32]char
    age: int

    def __init__(self, age: int):
        self.age = age

    def Speak(self) -> void:
        serial.puts("...\n")

class Dog(Animal):
    breed: int

    def Speak(self) -> void:
        serial.puts("Woof!\n")
```

### 异常类继承

Viper 支持异常类的继承，用于 `try/except` 的异常匹配：

```python
class MyError(Exception):
    pass

class SpecificError(MyError):
    pass
```

详见 [09-exceptions.md](09-exceptions.md)。

## 运算符重载

对象类支持运算符重载。编译器在遇到运算符时，先尝试**左操作数**的 dunder 方法；左操作数无对应方法时，回退**右操作数的反向 dunder**（`a + b` → 先 `a.__add__(b)`，缺失再 `b.__radd__(a)`）。TPC 与 VPC 两端行为一致。

### 算术运算符重载

| 运算符 | Dunder 方法 | 示例 |
|--------|------------|------|
| `+` | `__add__` | `a + b` → `a.__add__(b)` |
| `-` | `__sub__` | `a - b` → `a.__sub__(b)` |
| `*` | `__mul__` | `a * b` → `a.__mul__(b)` |
| `/` | `__truediv__` | `a / b` → `a.__truediv__(b)` |
| `//` | `__floordiv__` | `a // b` → `a.__floordiv__(b)` |
| `%` | `__mod__` | `a % b` → `a.__mod__(b)` |
| `**` | `__pow__` | `a ** b` → `a.__pow__(b)` |
| `&` | `__and__` | `a & b` → `a.__and__(b)` |
| `\|` | `__or__` | `a \| b` → `a.__or__(b)` |
| `^` | `__xor__` | `a ^ b` → `a.__xor__(b)` |
| `<<` | `__lshift__` | `a << b` → `a.__lshift__(b)` |
| `>>` | `__rshift__` | `a >> b` → `a.__rshift__(b)` |

> 基础类型（整数/浮点）的 `**` 由编译器直接 lower 为 `llvm.pow`：整数结果在指数为非负整数常量时回写为左操作数类型，其余为浮点结果。自定义类型的 `**` 走 `__pow__` 重载。

示例：

```python
class Vec2:
    x: float
    y: float

    def __init__(self, x: float, y: float):
        self.x = x
        self.y = y

    def __add__(self, other: Vec2) -> Vec2:
        result: Vec2 = Vec2(0.0, 0.0)
        result.x = self.x + other.x
        result.y = self.y + other.y
        return result

    def __mul__(self, scalar: float) -> Vec2:
        result: Vec2 = Vec2(0.0, 0.0)
        result.x = self.x * scalar
        result.y = self.y * scalar
        return result
```

### 增量赋值运算符重载

增量赋值先调度对象的**增量 dunder**（`+=` → `__iadd__`），该类无增量 dunder 时回退对应普通 dunder（`__add__`）；基础类型走原生运算。两端支持：

| 运算符 | 增量 Dunder | 回退 Dunder |
|--------|------------|------------|
| `+=` | `__iadd__` | `__add__` |
| `-=` | `__isub__` | `__sub__` |
| `*=` | `__imul__` | `__mul__` |
| `/=` | `__itruediv__` | `__truediv__` |
| `//=` | `__ifloordiv__` | `__floordiv__` |
| `%=` | `__imod__` | `__mod__` |
| `**=` | `__ipow__` | `__pow__` |
| `&=` | `__iand__` | `__and__` |
| `\|=` | `__ior__` | `__or__` |
| `^=` | `__ixor__` | `__xor__` |
| `<<=` | `__ilshift__` | `__lshift__` |
| `>>=` | `__irshift__` | `__rshift__` |

> 调度范围与 TPC 一致：仅**局部变量**目标调度增量 dunder（全局 / `nonlocal` 目标不调度）。重载返回值须与目标变量类型兼容（VPC 侧不兼容时编译期 fail-fast）。

### 比较运算符重载

`__eq__`/`__ne__`/`__lt__`/`__le__`/`__gt__`/`__ge__` 已自动调度（映射与调用点自动调度，`opovl_test` 覆盖）；未定义 `__eq__` 时比较回退为默认身份比较。

| 运算符 | Dunder 方法 | 状态 |
|--------|------------|------|
| `==` | `__eq__` | 已自动调度 |
| `!=` | `__ne__` | 已自动调度 |
| `<` | `__lt__` | 已自动调度 |
| `<=` | `__le__` | 已自动调度 |
| `>` | `__gt__` | 已自动调度 |
| `>=` | `__ge__` | 已自动调度 |

### 反向运算符重载

左操作数无对应普通 dunder 时，自动调度右操作数的反向 dunder（`a + b` → `b.__radd__(a)`）。两端支持：

| Dunder 方法 | 语义 |
|------------|------|
| `__radd__` | 右操作数加法 |
| `__rsub__` | 右操作数减法 |
| `__rmul__` | 右操作数乘法 |
| `__rtruediv__` | 右操作数真除法 |
| `__rfloordiv__` | 右操作数整除 |
| `__rmod__` | 右操作数取模 |
| `__rpow__` | 右操作数幂运算 |
| `__rand__` | 右操作数按位与 |
| `__ror__` | 右操作数按位或 |
| `__rxor__` | 右操作数按位异或 |
| `__rlshift__` | 右操作数左移 |
| `__rrshift__` | 右操作数右移 |

### 一元运算符重载

`__neg__`/`__pos__`/`__invert__` 已自动调度。

| 运算符 | Dunder 方法 | 状态 |
|--------|------------|------|
| `-a` | `__neg__` | 已自动调度 |
| `+a` | `__pos__` | 已自动调度 |
| `~a` | `__invert__` | 已自动调度 |

## 可调用对象 `__call__`

对象类定义了 `__call__` 时，`obj(args)` 自动分发到 `obj.__call__(args)`（两端已调度）。

```python
class Counter:
    value: int

    def __init__(self):
        self.value = 0

    def __call__(self) -> int:
        self.value += 1
        return self.value

c: Counter = Counter()
x: int = c()   # x = 1
y: int = c()   # y = 2
```

## 下标访问重载

### `__getitem__` — 读取

```python
def __getitem__(self, key: int) -> int:
    return self.data[key]
```

### `__setitem__` — 赋值

```python
def __setitem__(self, key: int, value: int):
    self.data[key] = value
```

### `__delitem__` — 删除

```python
def __delitem__(self, key: int):
    pass
```

## 布尔转换 `__bool__`

对象类定义了 `__bool__` 时，条件位置自动调度（两端已调度）：`if`/`elif`/`while` 条件、`and`/`or`/`not` 操作数、三元表达式条件。

```python
class Buffer:
    size: int
    data: [1024]char

    def __bool__(self) -> bool:
        return self.size > 0

buf: Buffer = Buffer()
if buf:
    serial.puts("buffer is not empty\n")
```

## 长度 `__len__`

```python
class Buffer:
    size: int

    def __len__(self) -> int:
        return self.size

buf: Buffer = Buffer()
n: int = len(buf)
```

## 字符串转换 `__str__`

对象类定义了 `__str__` 时，`str(obj)`、`print(obj)` 与 f-string（`f"{obj}"`，未指定格式说明符）自动调度该方法，取其返回的字符串（`const char*`）输出（两端已调度）。

```python
class Point:
    x: int
    y: int

    def __str__(self) -> const char*:
        return "Point"

p: Point = Point(1, 2)
print(p)          # 调用 p.__str__() → 输出 "Point"
```

## 绝对值 `__abs__`

对象类定义了 `__abs__` 时，`abs(obj)` 自动调度该方法（两端已调度）；基础类型仍走内建/C 库 `abs`（`labs`），见 [11-builtins.md](11-builtins.md)。

```python
class SignedValue:
    val: int

    def __abs__(self) -> int:
        if self.val < 0:
            return -self.val
        return self.val

sv: SignedValue = SignedValue()
sv.val = -42
a: int = abs(sv)   # a = 42
```

## 迭代器协议

Viper 的迭代器协议与 Python 相同。`__next__` 带编译器注入的隐藏 `i1*` 参数 `__stop_iter_flag__`：方法内 `raise StopIteration` 会将该参数置位并返回默认值以结束迭代。

### `__iter__` 和 `__next__`

```python
class IntRange:
    start: int
    end: int
    current: int

    def __init__(self, start: int, end: int):
        self.start = start
        self.end = end
        self.current = start

    def __iter__(self):
        return self

    def __next__(self, __stop_iter_flag__) -> int:  # 编译器注入的隐藏 i1* 参数
        if self.current >= self.end:
            raise StopIteration
        val: int = self.current
        self.current += 1
        return val
```

### for 循环使用

```python
r: IntRange = IntRange(0, 10)
for i in r:
    print(i)
```

编译器生成的等价逻辑：

```c
IntRange r = IntRange_init(0, 10);
IntRange iter = IntRange___iter__(&r);
while (1) {
    i1 __stop_iter_flag__ = 0;   /* 编译器注入的隐藏 i1* 参数 */
    int i = IntRange___next__(&iter, &__stop_iter_flag__);
    if (__stop_iter_flag__ == 1) break;
    print_int(i);
}
```

## 上下文管理器

`with` 语句要求对象实现 `__enter__` 和 `__exit__` 方法：

```python
class File:
    fd: int
    path: const char*

    def __init__(self, path: const char*, flags: int):
        self.path = path
        self.fd = -1

    def __enter__(self):
        self.fd = fat32.open(self.path, self.flags)
        return self

    def __exit__(self):
        fat32.close(self.fd)

    def read(self) -> int:
        return fat32.read(self.fd)
```

使用方式：

```python
with File("/test.txt", FA_READ) as f:
    data: int = f.read()
```

编译器会自动保证 `__exit__` 在 `with` 块结束时被调用。

## 析构 `__del__` / `__delete__`

`del` 的目标形态决定调度的 dunder（两端一致）：

| 语句 | 调度 |
|------|------|
| `del obj` | `obj.__delete__()`（类未定义则静默无操作） |
| `del obj.attr` | property deleter（`@attr.deleter`）；无 deleter 时回退属性值对象的 `__del__()` |
| `del obj[key]` | `obj.__delitem__(key)` |

```python
del obj        # 调用 obj.__delete__()
del arr[idx]   # 调用 arr.__delitem__(idx)
```

## `isinstance`

`isinstance(obj, Cls)` 不是关键字，而是编译器在调用点按函数名识别的内建（返回 `i1`）。

```python
if isinstance(obj, Base):
    ...

if isinstance(obj, (A, B)):     # 元组：任一命中即为真
    ...
```

语义：

- **`virtual` 类（带 vtable）**：运行时读对象头部 vtable 指针，与「目标类**及其全部已知子类**的 vtable 地址集合」逐一比较，相等即真 ⇒ 正确覆盖多态子类（这也是运行期唯一能拿到实际类的途径）；
- **`novirtual` 类 / 未知类（无 vtable）**：回退**编译期静态 MRO 判定**（据 obj 的静态类型）——可能保守判假。

第二参数支持：裸类名 / 跨模块 `mod.Cls`（只取短名）/ 元组 `(A, B)`。**不支持** REnum 变体、`t.CEnum` 等。

限制：已知子类集合上限 64、元组上限 15；Viper 侧类型推断失败即 fail-fast（`TypeError: isinstance() 参数类型推断失败`）。

> 注意：胖节点 AST 的节点分派用的是**虚方法 `kind()`**（返回 `ASTKind`），不是 `isinstance`；文档中提到的 `vtype` 字段目前**不存在**（属迁移规划）。

## FakeDuck（伪鸭子类型）

FakeDuck 让**内建类型 `str`**（LLVM 层就是 `i8*`）也能像对象一样调用方法、读写字段——通过**扩展类**实现，**不是**关键字 / 装饰器 / 基类。

### 启用方式（命名约定 + import）

- 扩展类必须命名为 `_str`（字符串扩展方法）或 `_Type`（通用基类），定义在被 `import` 的模块中；
- 使用者 `import _fakeduck`（提供 `_str` / `_Type`）；`with` 自动注入还需 `import _withcontent`。

内置扩展类见 [includes/_fakeduck.vp](../includes/_fakeduck.vp)：`_Type.type_id()`；`_str` 提供 `upper` / `lower` / `capitalize` / `swapcase` / `title` / `casefold` / `isupper` / `islower` / `isalpha` / `isdigit` / `isalnum` / `isspace` / `isascii` / `istitle` / `split` 等。

### 扩展方法调用

```python
import _fakeduck

a: str = "Hello"
tid: int = a.type_id()      # 解析到扩展类 _Type.type_id
u: str = a.upper()          # 解析到扩展类 _str.upper
```

分派是**回退**：先走普通结构体方法，全部落空后才尝试 FakeDuck；接收者注解是 `list[...]` 时**跳过**。方法名在 `_Type` / `_str` 中查找。

### 影子字段与 with 自动注入

编译期为每个**裸 `str`** 变量额外开一个影子结构体 `<变量名>__meta__`，用来存 per-instance 字段（`__data__`、`__mbuddy__`）：

```python
a.__mbuddy__ = bd           # 语法糖，等价 a.set_mbuddy(bd)
d: str = a.__data__         # 读影子字段
```

`with` 上下文可**自动注入**字段：提供方类用类体注解 `__provides__ = ['字段名']` 声明，消费方扩展类用 `__requires__ = ['字段名']` 声明：

```python
with memhub.MemBuddy(arena, 65536) as bd:
    s: str = "WithTest"     # __mbuddy__ 自动注入，无需手动赋值
    u2: str = s.upper()
```

另有 `__require_must__`：表示该字段必须由某个外层 `with` 提供，否则编译期 fail-fast。

### 限制

- 影子结构体**只对裸 `str` 注解创建**（`bytes` / `char*` 不创建）；`_bytes` 扩展类**未实现**。
- `len()` / 下标 `[]` / `for` 迭代等**不走 FakeDuck**，而是 `list[T]` 的 dunder / 内建分派。
- `with` 注入依赖运行时 provider 栈（[includes/_withcontent.vp](../includes/_withcontent.vp)），未 import `_withcontent` 时跳过注入。

真实用例：[Test/FakeDuckTest](../Test/FakeDuckTest)。

## Dunder 方法完整参考

### 已实现自动调度的 Dunder 方法

| Dunder 方法 | 触发语法 | 说明 |
|------------|---------|------|
| `__init__` | `ClassName(args)` | 构造函数 |
| `__before_init__` | 自动生成 | 填充成员默认值并初始化 vtable（类内含方法或继承虚方法时才生成），在 `__init__` 之前执行 |
| `__add__` | `a + b` | 加法 |
| `__sub__` | `a - b` | 减法 |
| `__mul__` | `a * b` | 乘法 |
| `__truediv__` | `a / b` | 真除法 |
| `__floordiv__` | `a // b` | 整除 |
| `__mod__` | `a % b` | 取模 |
| `__and__` | `a & b` | 按位与 |
| `__or__` | `a \| b` | 按位或 |
| `__xor__` | `a ^ b` | 按位异或 |
| `__lshift__` | `a << b` | 左移 |
| `__rshift__` | `a >> b` | 右移 |
| `__eq__` | `a == b` | 等于（未定义 `__eq__` 时默认身份比较） |
| `__ne__` | `a != b` | 不等于 |
| `__lt__` | `a < b` | 小于 |
| `__le__` | `a <= b` | 小于等于 |
| `__gt__` | `a > b` | 大于 |
| `__ge__` | `a >= b` | 大于等于 |
| `__neg__` | `-a` | 一元负号 |
| `__pos__` | `+a` | 一元正号 |
| `__invert__` | `~a` | 按位取反 |
| `__getitem__` | `obj[key]` | 下标读取 |
| `__setitem__` | `obj[key] = value` | 下标赋值 |
| `__delitem__` | `del obj[key]` | 下标删除 |
| `__len__` | `len(obj)` | 长度 |
| `__iter__` | `for x in obj:` | 获取迭代器 |
| `__next__` | `for x in obj:` | 取下一个值（隐藏 `i1*` 参数 `__stop_iter_flag__`，`raise StopIteration` 置位后返回默认值结束迭代） |
| `__enter__` | `with obj as x:` | 上下文管理器进入 |
| `__exit__` | `with obj as x:` | 上下文管理器退出 |

### 声明支持但未实现自动调度的 Dunder 方法

| Dunder 方法 | 预期触发语法 | 当前状态 |
|------------|------------|---------|
| `__pow__` | `a ** b` | 期望实现：binop `**` 未调度（基础类型 `**` 编译失败；自定义类型走 `__pow__` 重载亦属期望） |
| `__iadd__` | `a += b` | 期望实现：AugAssign 一律按原生运算符展开（`+=`→`add`、`//=`→`sdiv` …），不调用 `__iadd__`，也无 `__add__` 回退 |
| `__isub__` | `a -= b` | 同上 |
| `__imul__` | `a *= b` | 同上 |
| `__itruediv__` | `a /= b` | 同上 |
| `__ifloordiv__` | `a //= b` | 同上 |
| `__imod__` | `a %= b` | 同上 |
| `__ipow__` | `a **= b` | 同上 |
| `__str__` | `str(obj)` / `print(obj)` | 期望实现：`print` 为类型感知格式化（`str`/`%s`、`int`、`float`、`struct` 输出占位符），不调度 `__str__` |
| `__call__` | `obj(args)` | 期望实现：当前未调度 |
| `__bool__` | `if obj:` | 期望实现：当前未调度 |
| `__abs__` | `abs(obj)` | 期望实现：当前未调度 |
| `__del__` | `del obj` | 期望实现：当前未调度 |
| `__delete__` | `del obj` | 期望实现：当前未调度 |
| `__radd__` | 右操作数加法 | 尚未调度 |
| `__rsub__` | 右操作数减法 | 尚未调度 |
| `__rmul__` | 右操作数乘法 | 尚未调度 |
| `__rtruediv__` | 右操作数真除法 | 尚未调度 |
| `__rfloordiv__` | 右操作数整除 | 尚未调度 |
| `__rmod__` | 右操作数取模 | 尚未调度 |
| `__rpow__` | 右操作数幂运算 | 尚未调度 |