Skip to content

6. 高级特性与最佳实践

6.1 项目配置 (TransPyC.toml)

每个翻译项目通过 TransPyC.toml 配置：

name = "my_project"
output = "target"

[[files]]
input = "*.py"

[[files]]
input = "subdir/*.py"
output = "subdir/target"

6.1.1 CLI 用法

# 初始化新项目
trans_py_c init                  # 当前目录
trans_py_c init my_project       # 指定路径

# 翻译（读取 TransPyC.toml）
trans_py_c -c examples/example1
trans_py_c -c examples/example1 -v

# 直接翻译文件（无需配置）
trans_py_c main.py -o out/
trans_py_c "src/*.py" -o gen/    # glob 模式

# 调试
trans_py_c main.py --debug

6.2 文件组织

推荐的项目结构：

my_project/
├── TransPyC.toml       # 项目配置
├── main.py             # 入口
├── types.py            # 结构体定义
├── utils.py            # 工具函数
├── target/             # 生成的 C 文件 (gitignore)
│   ├── main.c
│   └── ...
└── c_headers/          # 手写 C 头文件
    ├── kernel.h
    └── types.h

target/ 目录由翻译器自动创建，建议加入 .gitignore。

6.3 与 C 代码互操作

6.3.1 手写 C 头文件

结构体定义可以写在 .h 文件中而不是 .py 中：

// types.h
struct TASK {
    int pid;
    char* name;
    struct TASK* next;
};

然后在 Python 中用 import 包含：

import types     # → #include "types.h"

task: struct TASK

6.3.2 翻译器理解的头文件

翻译器的符号表在第一遍扫描时只收集 .py 文件中的定义。手写 C 头文件中的类型信息需要你在 Python 端通过类型注解告知翻译器（指针/non-pointer），以便 . / -> 正确选择。

6.4 调试技巧

6.4.1 --debug 模式

trans_py_c main.py --debug

输出翻译器内部日志：

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

6.4.2 常见问题

Q: 生成的 C 编译报错

  1. 检查类型注解是否正确（特别是指针 vs 非指针）
  2. 用 --debug 查看翻译器日志
  3. 检查头文件是否在正确路径

Q: 结构体成员访问用了 . 而不是 ->

翻译器自动选择运算符，但需要符号表中有正确的类型信息。确保： - 指针变量在声明时使用了 class_name | t.CPtr 或 struct Type* - 类定义在函数定义之前

Q: 怎么表示 void*？

import t
ptr: t.CPtr | None            # void*

6.5 当前不支持的特性

  • 类继承、装饰器、生成器、异常处理
  • 联合体（union）、枚举（enum）
  • switch / goto
  • 函数指针、位域
  • 可变参数函数
  • 条件编译（#ifdef）

6.6 下一步

  • 详细 API 参考见 概述与原理
  • 完整示例见 examples/ 目录
  • 源码见 src/core/ (函数级文档在每个文件头部)