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

Viper 中的 `class` 有两种语义：**数据布局**（结构体/联合体/枚举，见 [05-classes.md](05-classes.md)）和**面向对象**。面向对象特性通过 `@t.Object` 装饰器启用，多态通过 `@t.CVTable` 装饰器启用，非多态继承（C++ 风格，无 vtable 开销）通过 `@t.NoVTable` 装饰器启用。

## `@t.Object` 面向对象

使用 `@t.Object` 装饰器启用面向对象特性，类将拥有成员方法、运算符重载、属性装饰器等 OOP 支持。编译器也会自动识别：如果结构体内有函数定义，会自动使用 `@t.Object` 行为，但在实际工程中更推荐明确标记，避免未定义行为。

### 基本定义

```python
@t.Object
class ViperKernel:
    BootInfo: bootinfo | t.CPtr
    VGA: vga._VGAScreenDriver | t.CPtr
    VGA_drv: vga._VGAScreenDriver

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

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

### 成员方法

```python
@t.Object
class Sheet:
    id: t.CInt
    x: t.CInt
    y: t.CInt
    w: t.CInt
    h: t.CInt

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

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

    def Resize(self, nw: t.CInt, nh: t.CInt):
        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
@t.Object
class MyObj:
    _value: t.CInt

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

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

### 静态方法

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

### 对象指针与解引用

`@t.Object` 的实例通常通过指针操作：

```python
obj_ptr: MyClass | t.CPtr = c.Addr(MyClass())
obj: MyClass = c.Deref(obj_ptr)
```

### 成员访问

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

```python
def method(self) -> t.CVoid:
    self.x = 10
    y: t.CInt = self.y
    self.DoSomething()
```

### 内嵌对象

`@t.Object` 可以包含其他对象实例（非指针）：

```python
@t.Object
class Sheet:
    _surf_obj: gfx.Surface
    _renderer_obj: gfx.Renderer
    surf: gfx.Surface | t.CPtr
    renderer: gfx.Renderer | t.CPtr

    def __init__(self, fb: UINT32PTR, zb: float | t.CPtr, w: t.CInt, h: t.CInt):
        self._surf_obj = gfx.Surface(fb, zb, w, h)
        self.surf = c.Addr(self._surf_obj)
        self._renderer_obj = gfx.Renderer(self.surf)
        self.renderer = c.Addr(self._renderer_obj)
```

### `__before_init__` 方法

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

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

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

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

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

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

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

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

## `@t.NoVTable` 非多态继承

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

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

### 基本定义

```python
@t.NoVTable
class LinkedNode:
    next: "LinkedNode" | t.CPtr
    prev: "LinkedNode" | t.CPtr
    def append(self, node: "LinkedNode" | t.CPtr): ...

@t.NoVTable
class GNode(LinkedNode):    # 非多态继承
    value: t.CInt
```

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

### 方法继承机制

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

### 跨模块继承

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

### 向下转型

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

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

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

## `@t.CVTable` 虚函数表与多态

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

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

使用 `@t.CVTable` 装饰器可以启用虚函数表支持。启用后，结构体第一个成员自动插入 `i8*` 类型的 vtable 指针。`@t.CVTable` 的操作必须配合 `@t.Object`，但有时编译器会自动识别是否存在结构体内函数，自动使用 `@t.Object`。

### 基本定义

```python
@t.Object
@t.CVTable
class Base:
    def __init__(self):
        pass
    def method(self) -> t.CInt:
        return 0
```

在 LLVM IR 中，`@t.CVTable` 类的结构体类型自动插入 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
@t.Object
@t.CVTable
class Base:
    def __init__(self):
        pass
    def method(self) -> t.CInt:
        return 0

@t.Object
@t.CVTable
class M1(Base):
    def method(self) -> t.CInt:
        return 1
```

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

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

### VTable 运行时修改

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

```python
@t.Object
@t.CVTable
class Base:
    def __init__(self):
        pass
    def method(self) -> t.CInt:
        return 0

def __method1(self) -> t.CInt:
    return 1

def main() -> t.CInt | t.CExport:
    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. 间接调用

### 方法级虚表开关

类级装饰器 `@t.CVTable`/`@t.NoVTable` 决定类级默认策略，方法级装饰器可覆盖类级默认：

- `@t.NoVTable` 类中单独标注 `@t.CVTable` 的方法进入虚表
- `@t.CVTable` 类中单独标注 `@t.NoVTable` 的方法被排除在虚表之外

以上行为由 `func_vtable_test` 实证。

### super()

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

```python
@t.Object
@t.CVTable
class Base:
    def method(self) -> t.CVoid:
        pass

@t.Object
@t.CVTable
class Derived(Base):
    def method(self) -> t.CVoid:
        super().method()   # 静态调用父类实现
```

## 继承

### 结构体成员继承

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

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

```python
@t.Object
class Animal:
    name: t.CArray[t.CChar, 32]
    age: t.CInt

    def __init__(self, age: t.CInt):
        self.age = age

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

@t.Object
class Dog(Animal):
    breed: t.CInt

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

### 异常类继承

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

```python
class MyError(Exception):
    pass

class SpecificError(MyError):
    pass
```

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

## 运算符重载

`@t.Object` 类支持运算符重载。编译器在遇到运算符时，首先检查左操作数是否为结构体类型，如果是则尝试调用对应的 dunder 方法。

### 算术运算符重载

| 运算符 | 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)`（期望实现） |

> **注意**：binop 的 `**` 未调度——基础类型 `**` 编译失败；自定义类型走 `__pow__` 重载也属期望实现。

示例：

```python
@t.Object
class Vec2:
    x: t.CFloat
    y: t.CFloat

    def __init__(self, x: t.CFloat, y: t.CFloat):
        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: t.CFloat) -> Vec2:
        result: Vec2 = Vec2(0.0, 0.0)
        result.x = self.x * scalar
        result.y = self.y * scalar
        return result
```

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

> **期望实现**：当前 `AugAssign`（增量赋值）一律按原生运算符展开（`+=`→`add`、`//=`→`sdiv` …），不调用 `__iadd__`，也没有回退到普通版本（如 `__add__`）的机制。`__iadd__` 等增量 dunder 方法均属期望实现。

### 比较运算符重载

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

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

### 反向运算符重载

> **实验性**：以下反向运算符 dunder 方法在编译器中被识别，但尚未实现自动调度。

| Dunder 方法 | 预期语义 | 状态 |
|------------|---------|------|
| `__radd__` | 右操作数加法 | 仅类型推断识别 |
| `__rsub__` | 右操作数减法 | 仅类型推断识别 |
| `__rmul__` | 右操作数乘法 | 仅类型推断识别 |
| `__rtruediv__` | 右操作数真除法 | 仅类型推断识别 |
| `__rfloordiv__` | 右操作数整除 | 仅类型推断识别 |
| `__rmod__` | 右操作数取模 | 仅类型推断识别 |
| `__rpow__` | 右操作数幂运算 | 仅类型推断识别 |

### 一元运算符重载

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

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

## 可调用对象 `__call__`

> **期望实现**：当前未调度 `__call__`，`obj(args)` 不会自动分发到该方法。

```python
@t.Object
class Counter:
    value: t.CInt

    def __init__(self):
        self.value = 0

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

c: Counter = Counter()
x: t.CInt = c()   # x = 1
y: t.CInt = c()   # y = 2
```

## 下标访问重载

### `__getitem__` — 读取

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

### `__setitem__` — 赋值

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

### `__delitem__` — 删除

```python
def __delitem__(self, key: t.CInt):
    pass
```

## 布尔转换 `__bool__`

> **期望实现**：当前条件真值对 struct 值恒真/指针判非空，不调度 `__bool__`。

```python
@t.Object
class Buffer:
    size: t.CInt
    data: t.CArray[t.CChar, 1024]

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

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

## 长度 `__len__`

```python
@t.Object
class Buffer:
    size: t.CInt

    def __len__(self) -> t.CInt:
        return self.size

buf: Buffer = Buffer()
n: t.CInt = len(buf)
```

## 字符串转换 `__str__`

> **期望实现**：`print` 是类型感知格式化（`str`/`%s`、`int`、`float`、`struct` 输出占位符），当前**不调度** `__str__`。

```python
@t.Object
class Point:
    x: t.CInt
    y: t.CInt

    def __str__(self) -> t.CConst | t.CChar | t.CPtr:
        return "Point"

p: Point = Point(1, 2)
print(p)          # 类型感知格式化：不调用 p.__str__()
```

## 绝对值 `__abs__`

> **期望实现**：当前 `abs()` 不调度 `__abs__`（`abs` 为 C 库裸名调用/TPC 内建，见 11-builtins.md）。

```python
@t.Object
class SignedValue:
    val: t.CInt

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

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

## 迭代器协议

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

### `__iter__` 和 `__next__`

```python
@t.Object
class IntRange:
    start: t.CInt
    end: t.CInt
    current: t.CInt

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

    def __iter__(self):
        return self

    def __next__(self, __stop_iter_flag__) -> t.CInt:  # 编译器注入的隐藏 i1* 参数
        if self.current >= self.end:
            raise StopIteration
        val: t.CInt = 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
@t.Object
class File:
    fd: t.CInt
    path: t.CConst | t.CChar | t.CPtr

    def __init__(self, path: t.CConst | t.CChar | t.CPtr, flags: t.CInt):
        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) -> t.CInt:
        return fat32.read(self.fd)
```

使用方式：

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

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

## 析构 `__del__` / `__delete__`

> **期望实现**：当前 `del obj` 不调度 `__del__`/`__delete__`；已实现的是 `del obj.attr`（property deleter）与 `del obj[key]`（`__delitem__`）。

```python
del obj        # 期望：调用 obj.__del__() 或 obj.__delete__()（尚未实现）
del arr[idx]   # 调用 arr.__delitem__(idx)
```

## 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__` | 右操作数幂运算 | 尚未调度 |