- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
8.4 KiB
Executable File
markup, import
| markup | import | ||
|---|---|---|---|
| occlusion |
|
通过渲染器共用的 Markdown 解析器读取文档结构。结构变换为纯函数,读取表值通过原生文件能力加载指定数据。
不执行内容地读取与变换 Markdown 结构。
能力与边界:复用 Markdown 解析器并识别 YAML 前置信息;区间是原始 UTF-8 字节偏移。不执行文档。重复章节名失败;替换保留周围源码,持久化使用校验后写。
本文件就是调用和开发手册:直接导入此文件,或用 marqdo call 按下面的函数标题调用。参数表说明类型和默认值;未填默认值的参数必须提供。返回表是渐进契约,后文说明失败与边界。
实现入口:src/host/document.rs
开发时保持中英文语义一致,先组合公开库;仅在 OS 或算法边界添加宿主原语并声明效应。修改后运行 marqdo check --narrative-ratio 本文件,并执行 tests/stdlib_tasks.rs 的真实任务。
章节列表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 本操作读取、转换或输出的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 列出标题、原始 UTF-8 字节区间和正文;章节结束于下一个同级或更高级标题。不执行文档。 |
这里使用内容。
调用效应:pure。
直接调用此函数:
marqdo call lib/文档.mq.md 章节列表 '内容="# Notes"' --effects none --json
列出标题、原始 UTF-8 字节区间和正文;章节结束于下一个同级或更高级标题。不执行文档。
完成后返回*[列出标题、原始 UTF-8 字节区间和正文;章节结束于下一个同级或更高级标题](> host_document_sections text=内容)*。
读取章节
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 本操作读取、转换或输出的文本 |
| 标题 | text | 必填 | 精确且唯一的 Markdown 标题文字 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | text | 按完整标题读取正文;缺失或重复标题失败。 |
这里使用内容、标题。
调用效应:pure。
按完整标题读取正文;缺失或重复标题失败。
完成后返回*[按完整标题读取正文;缺失或重复标题失败](> host_document_section text=内容 title=标题)*。
替换章节
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 本操作读取、转换或输出的文本 |
| 标题 | text | 必填 | 精确且唯一的 Markdown 标题文字 |
| 正文 | text | 必填 | 请求正文;文档操作中为替换正文 |
| 预期摘要 | any | None | 前次精确文本的摘要;操作允许时 None 表示不检查 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 返回替换章节正文的结果记录,保留标题和周围源码;可校验整份来源摘要。这是纯转换,持久化使用文件库校验后写。 |
这里使用内容、标题、正文、预期摘要=None。
调用效应:pure。
返回替换章节正文的结果记录,保留标题和周围源码;可校验整份来源摘要。这是纯转换,持久化使用文件库校验后写。
完成后返回*[返回替换章节正文的结果记录,保留标题和周围源码;可校验整份来源摘要](> host_document_replace_section text=内容 title=标题 body=正文 expected_sha256=预期摘要)*。
表格列表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 本操作读取、转换或输出的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 提取惰性的 GFM 表头、单元格文本和原始字节区间;不求值单元格。 |
这里使用内容。
调用效应:pure。
提取惰性的 GFM 表头、单元格文本和原始字节区间;不求值单元格。
完成后返回*[提取惰性的 GFM 表头、单元格文本和原始字节区间;不求值单元格](> host_document_tables text=内容)*。
替换表格
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 本操作读取、转换或输出的文本 |
| 序号 | number | 必填 | 按源码顺序排列的表格下标,从零开始 |
| 表头 | list | 必填 | 按列顺序排列的表头文本列表 |
| 行 | list | 必填 | 单元格文本列表组成的行列表;每行宽度必须与表头一致 |
| 预期摘要 | any | None | 前次精确文本的摘要;操作允许时 None 表示不检查 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | map | 按从零起的表序号,用文本表头和行替换表格,保留周围源码;返回结果记录。 |
这里使用内容、序号、表头、行、预期摘要=None。
调用效应:pure。
按从零起的表序号,用文本表头和行替换表格,保留周围源码;返回结果记录。
完成后返回*[按从零起的表序号,用文本表头和行替换表格,保留周围源码;返回结果记录](> host_document_replace_table text=内容 index=序号 headers=表头 rows=行 expected_sha256=预期摘要)*。
链接列表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 本操作读取、转换或输出的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 列出 Markdown 链接描述、目标和字节区间;不访问或执行链接。 |
这里使用内容。
调用效应:pure。
列出 Markdown 链接描述、目标和字节区间;不访问或执行链接。
完成后返回*[列出 Markdown 链接描述、目标和字节区间;不访问或执行链接](> host_document_links text=内容)*。
代码块列表
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 本操作读取、转换或输出的文本 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | list | 列出代码块语言、字面源码和字节区间;不运行其中的外联或 Marqdo 代码。 |
这里使用内容。
调用效应:pure。
列出代码块语言、字面源码和字节区间;不运行其中的外联或 Marqdo 代码。
完成后返回*[列出代码块语言、字面源码和字节区间;不运行其中的外联或 Marqdo 代码](> host_document_code_blocks text=内容)*。
表值
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 内容 | text | 必填 | 含字面 GFM 数据表的 Markdown |
| 标题 | any | None | 精确且唯一的章节名;None 表示整篇 |
| 索引 | number | 0 | 所选章节中从零开始的表格序号 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 与 Marqdo 字面表相同形态和类型的实际数据 |
这里使用内容、标题=None和索引=0。常量表中的布尔、数值、空值和引号文本保留原生类型;@、行或 row 首列产生记录列表,单列产生普通列表,其余表保留原有映射形态。定位使用渲染器共用的 Markdown 解析器,会跳过围栏内示例。重复标题、表头冲突、列数不齐和非法索引会给出诊断。变量引用、插值和可执行表达式不能作为数据读取;正文、导入和外联围栏也不会执行。这样可以把模式、种子和样式常量拆成 Markdown 数据叶子,同时让调用函数说明实际用途。
完成后返回*[按原生字面规则读取表值](document.table(text=内容, title=标题, index=索引))*.
读取表值
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| 路径 | text | 必填 | 文件根内的 UTF-8 Markdown 数据文件 |
| 标题 | any | None | 精确且唯一的章节名;None 表示整篇 |
| 索引 | number | 0 | 所选章节中从零开始的表格序号 |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | 通过原生 fs.read 加载的字面表数据 |
这里使用路径、标题=None和索引=0,授权 fs.read 后读取数据叶子。文件读取检查根目录与 UTF-8,表值选择保留字面类型及实际结构。文件可以把字段说明、示例和数据写在一起,读取过程不会运行其中的语句、导入或其他语言围栏。文件缺失、标题重复、单元格动态引用和列数不齐均保留诊断。此函数只读,调用者再按数据库、样式或其他领域的真实契约使用返回值。
完成后返回*[原生读取并选择 Markdown 数据](document.read_table(path=路径, title=标题, index=索引))*.