1. 概述与原理

1.1 项目概述

TransPyC 是一个将 Python 子集代码翻译为 C 代码的源到源编译器，面向操作系统内核等底层开发场景。用 Python 的简洁语法写 C 代码——省去花括号、分号细节，但保留 C 的性能和控制力。

当前版本使用 Rust 实现，核心翻译器约 1500 行。

1.2 设计目标

简洁性 — Python 语法、C 性能
类型安全 — 通过 Python 类型注解提供完整类型系统
性能等同 — 生成的 C 代码与手写 C 性能一致
底层友好 — 内置内联汇编、指针、宏等底层操作

1.3 项目结构

TransPyC/
├── src/
│   ├── main.rs                # CLI 入口
│   ├── lib.rs                 # 模块声明
│   ├── cli/mod.rs             # 命令行解析 + TOML 配置
│   ├── core/
│   │   ├── translator.rs      # Translator 主结构体 + 翻译流程
│   │   ├── expressions.rs     # 表达式处理 (handle_expr)
│   │   ├── type_name.rs       # 类型名称解析 (get_type_name)
│   │   └── types.rs           # 符号表 / 作用域
│   ├── includes/
│   │   ├── gramma.rs          # c 模块: Asm, Memory, Macro, ...
│   │   └── types.rs           # t 模块: CInt, CPtr, CStruct, ...
│   └── constants/             # 运算符映射
├── examples/                  # 翻译样例 (每个子目录一个项目)
├── tests/                     # Rust 测试 (18 单元 + 8 文件)
└── docs/                      # 文档

1.4 翻译流程

Python 源码 (.py)
       ↓
   rustpython-parser 解析 → AST
       ↓
   第一遍: 收集符号 (collect_symbols)
   - class    → 结构体定义 + 成员类型
   - def      → 函数名
   - x: type  → 变量类型
       ↓
   第二遍: 按序生成 C (generate_c_code)
   - import      → #include
   - class       → struct
   - AnnAssign   → 类型声明
   - FunctionDef → C 函数
       ↓
C 源码 (.c)

1.5 核心组件

1.5.1 Translator (`core/translator.rs`)

翻译流程的总控制器。持有符号表、作用域栈等状态，提供 generate_c_code() 入口。约 600 行。

1.5.2 表达式处理器 (`core/expressions.rs`)

将 Python 表达式 AST 节点转换为 C 代码字符串。处理常量、变量、运算、比较、调用、属性访问等。也是 c.* 和 t.* 特殊调用的分发中心。约 500 行。

1.5.3 类型名称解析 (`core/type_name.rs`)

递归遍历 Python 类型注解 AST 节点（t.CInt | t.CPtr 等），输出 C 类型字符串。约 200 行。

1.5.4 c 模块 (`includes/gramma.rs`)

c.Asm() → __asm__ volatile、c.Memory() → ((void *)addr) 等。每个 c.* 调用对应一个纯函数。

1.5.5 t 模块 (`includes/types.rs`)

Python 类型名到 C 类型名的映射表。t.CInt → "int"、t.CPtr → "*" 等。

1.6 类型系统

1.6.1 基本类型映射

Python 类型	C 类型	说明
`int`	`int`	整数
`float`	`float`	32位浮点
`str`	`char*`	字符串指针
`bool`	`bool`	布尔

1.6.2 t 模块类型

Python	C
`t.CChar`	`char`
`t.CInt`	`int`
`t.CLong`	`long`
`t.CFloat`	`float`
`t.CDouble`	`double`
`t.CVoid`	`void`
`t.CPtr`	`*`
`t.CStatic`	`static`
`t.CExtern`	`extern`
`t.CConst`	`const`

1.6.3 类型组合 (`|` 运算符)

ptr: t.CInt | t.CPtr                     # int*
arr: t.CChar[16]                          # char[16]
counter: t.CStatic | t.CInt              # static int
task: t.CPtr | t.CStruct(name="TASK")    # struct TASK*

1.7 符号表

翻译器维护一个全局符号表，第一遍扫描 AST 时填充：

"MyStruct" → Struct {
    members: {
        "field1": { type: "int", is_pointer: false },
        "ptr":    { type: "struct Other*", is_pointer: true }
    }
}
"my_func"  → Function
"global_x" → Variable { declared_type: "int", is_pointer: false }

主要用途：变量声明时判断是新声明还是已存在、成员访问时判定 . 还是 ->、类型推断。

1.8 作用域管理

栈结构，每进入一个函数 push 一层，每退出 pop 一层。

[ { global vars },              ← 全局作用域
  { param1: "int", ... },        ← 函数参数
  { local_var: "char" } ]        ← 局部变量

1.9 `.` vs `->` 运算符选择

翻译器根据变量类型自动选择：

Python	C	原因
`s.field`	`s.field`	s 不是指针
`self.field`	`self->field`	self 总是指针
`ps.field`	`ps->field`	ps 声明为指针
`arr[i].field`	`arr[i].field`	数组元素非指针

1.10 调试

cargo run -- main.py --debug

输出示例：

[SCOPE] Enter function 'add', depth=1
[ENTER] HandleReturn [Return]
[EXIT] HandleReturn -> 1 lines
[SCOPE] Exit function 'add', depth=0

1.11 限制

不支持 Python 高级特性：类继承、异常、生成器、装饰器、动态类型
需要显式类型注解：变量、参数、返回值
内存管理：需要手动管理内存（malloc/free）
标准库：不支持 Python 标准库，使用 C 标准库