本页内容

Guidedog / 文档 0.2.0

Guidedoc 引擎

Guidedoc 是转换核心，借用调用方提供的存储。它读取源文、构建语义树、执行处理阶段、测量输出，再输出字节；不打开文件，也不发布产物。

图 4 外部操作由宿主负责；文档语义由 Guidedoc 负责。

边界

核心转换不进行分配。调用方提供节点列、文本存储、诊断和输出容量。宿主准备这些缓冲区时可以分配。第三方编译器有自己的分配规则。这项保证针对转换边界，而非整个进程。

树结构

节点使用有类型的 ID。热数据列保存节点种类和子树范围；冷数据表保存各类节点需要的载荷。扁平前序表示可跳过整个子树，无需追踪堆指针链。

对节点 \(i\)，设 \(e_i\) 为不包含在子树中的结束索引。子树占据 \([i,e_i)\)。叶节点有 \(e_i=i+1\)；父节点在后代之后闭合。区间证明见 先有不变式，再谈算法。

API

核心 API 明确直接：初始化存储、转换、检查结果、重置。注册表是包含读取器、处理阶段和渲染器描述符的值。没有运行时插件发现或全局注册副作用。少量操作便于其他 Odin 程序调用。

所有权是关键规则。工作区视图在重置或复用时失效。宿主持有的结果必须拥有所有超过会话生命周期的文本。准确签名见 core；它与独立 docs/api 项目从相同 Odin 源码生成。手册 PDF 将参考合入同一本书，提供内部链接。设计记录是 docs/gds 中的 GDS 0003。