pandoc 回归测试 #8665 剖析DocBook 表格转 AsciiDoc 时特殊字符的转义与 passthrough 机制【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本篇技术指南围绕 pandoc 仓库中的命令回归测试 test/command/8665.md 展开该用例验证了从 DocBook 的informaltable表格转换到 AsciiDoc 格式时表格单元格内特殊字符|、、#、*、{}、[]等必须被正确转义否则会破坏 AsciiDoc 表格语法。阅读本文后你将掌握 pandoc AsciiDoc writer 的...passthrough 转义状态机、表格上下文InTable下{vbar}/{plus}属性引用的使用规则以及 pandoc 命令测试golden test的编写与运行机制。一、测试用例速览一段 29 行的完整转义验证test/command/8665.md 是一个典型的 pandoc 命令测试command test全文是一个代码块分为三部分命令行、stdin 输入、期望输出。其原始内容如下% pandoc -f docbook -t asciidoc informaltable frameall rowsep1 colsep1 tgroup cols1 thead row entry alignleft valigntoph1/entry entry alignleft valigntoph2/entry /row /thead tbody row entry alignleft valigntop simpara!#$%^amp;*(){}|~?-,.lt;gt;[]\/simpara /entry entry alignleft valigntop simparacol 2/simpara /entry /row /tbody /tgroup /informaltable ^D [cols,,optionsheader,] | |h1 |h2 |!#$%^*(){}{vbar}~?{plus}-,.[]\ |col 2 |各部分含义第 1 行%开头要执行的命令即pandoc -f docbook -t asciidoc——从 DocBook XML 读取输出 AsciiDoc第 2 行至^D之前作为 stdin 传给 pandoc 的输入文档即一个不含标题的 DocBook 表格informaltable其数据单元格simpara中包含经过 XML 实体转义的一大串特殊字符 !#$%^*(){}|~?-,.[]^D之后期望在 stdout 上得到的 AsciiDoc 输出。该用例的验证重点非常明确表格单元格中的特殊字符必须被转义为合法的 AsciiDoc 输出。注意数据单元格的期望输出|!#$%^*(){}{vbar}~?{plus}-,.[]\而普通文本单元格col 2则原样输出为|col 2。两者对比即可看出转义逻辑的存在。二、测试背后的历史问题#8665 与 changelog 证据该测试文件名8665对应 pandoc 仓库的 issue/PR 编号 #8665。在 changelog.md 中可以直接找到对应的修复记录Asciidoc writer: Properly escape | in table cells (#8665).这句话说明该测试验证的正是 AsciiDoc writer 对表格单元格内竖线|的转义修复。在 AsciiDoc 表格语法中|是单元格分隔符直接出现在单元格内容中会导致表格列被错误切分因此必须以{vbar}属性引用形式输出。这个测试用例就是该修复的回归保障一旦未来某次改动破坏了转义逻辑golden test 就会比对失败并报错。三、转义规则逐字符拆解escapeString与 passthrough 状态机AsciiDoc writer 的转义核心实现在 src/Text/Pandoc/Writers/AsciiDoc.hs 中的escapeString函数。它接收一个EscContextNormal或InTable和一段文本返回转义后的输出。3.1 需要转义的字符集函数内部定义了needsEscape谓词见 AsciiDoc.hs以下字符在 AsciiDoc 中具有特殊语法含义必须被转义字符在 AsciiDoc 中的含义转义方式{属性引用起始{passthrough 定界符 / 加粗标记{plus}行内代码定界符passthrough 包裹*粗体标记passthrough 包裹#交叉引用/锚点标记passthrough 包裹_斜体标记passthrough 包裹块/替换标记起始passthrough 包裹[]属性列表定界符passthrough 包裹\转义字符本身passthrough 包裹|表格单元格分隔符{vbar}仅在InTable上下文值得注意的是$、%、^、、!、、(、)、~、?、-、、,、.、、}等字符不在needsEscape列表中因此原样输出——这正是期望输出中!、$%^、()、~?、-,.得以保留的原因。3.2 passthrough 状态机的折叠逻辑escapeString使用T.foldl对整个字符串做一次左折叠折叠状态(Bool, Text)中的Bool标记当前是否处于...passthrough 上下文内。核心分支如下见 AsciiDoc.hs处于 passthrough 内遇到先输出关闭上下文再输出{plus}处于 passthrough 内遇到|且上下文为InTable先输出关闭上下文再输出{vbar}处于 passthrough 内遇到其他需要转义的字符原样保留它已被保护处于 passthrough 内遇到不需要转义的字符输出关闭上下文再输出该字符处于普通上下文遇到需要转义的字符输出进入 passthrough再输出该字符处于普通上下文遇到不需要转义的字符原样输出。折叠结束后若仍处于 passthrough 状态则自动补一个闭合见 AsciiDoc.hs。3.3 对测试单元格的逐字符验证用上述状态机逐字符分析测试数据单元格 !#$%^*(){}|~?-,.[]可以得到与期望输出完全一致的转义结果! → 原样输出非特殊字符 # → # 进入/退出 passthrough $%^ → 原样输出 * → * 进入/退出 passthrough () → 原样输出 { → { 进入/退出 passthrough } → 原样输出} 不在 needsEscape 中 | → {vbar} InTable 上下文表格分隔符 ~? → 原样输出 → {plus} 是 passthrough 定界符 -,. → 原样输出 []\ → []\ 连续特殊字符共用一个 passthrough末尾补 闭合最终拼接即!#$%^*(){}{vbar}~?{plus}-,.[]\与测试期望完全吻合。这一逐字符推导也直观验证了状态机中同一段 passthrough 内连续保留多个特殊字符、仅在遇到普通字符或字符串结束时才闭合的设计。四、表格上下文InTable的特殊处理|与EscContext数据类型定义于 AsciiDoc.hsdata EscContext Normal | InTable deriving (Show, Eq)|和在表格上下文中的处理与普通上下文不同原因如下|必须变成{vbar}AsciiDoc 表格中|是单元格分隔符。即使把|放进...passthrough表格解析器仍可能将其识别为列分隔符导致表格结构损坏因此必须使用属性引用{vbar}渲染时恢复为|。这正是 changelog 中 #8665 修复的核心点。从源码结构看go函数中对|的两个分支都带上了context InTable守卫见 AsciiDoc.hs即只有在表格内|才被替换必须变成{plus}本身是 passthrough 的定界符在转义过程中若直接输出会干扰的配对。代码的做法是无论是否处于 passthrough遇到一律以{plus}输出AsciiDoc.hs与|的处理思路一致。对比测试输出可以确认数据单元格中的|被替换为{vbar}、被替换为{plus}而#、*、{}、[]\ 等则用 passthrough 包裹。这也解释了为什么表头单元格h1、h2 无需任何转义——它们不含特殊字符。五、AsciiDoc 表格的完整输出结构理解了转义规则后再看期望输出中的表格骨架就能还原整个 AsciiDoc 表格的生成过程相关逻辑集中在 AsciiDoc.hs 的表格输出部分5.1 表格规格行[cols,,optionsheader,]cols,列规格。每列由对齐操作符 宽度组成两列均无显式宽度因此得到,源码见 AsciiDoc.hs 的colspec与alignmentOperatoroptionsheader声明首行为表头。源码中由optionSpecForRows headers header生成AsciiDoc.hs仅当表头行非空时才输出该选项行尾多出的逗号并非笔误而是tablespec的拼接结果[ 宽度规格为空 cols..., 选项规格 ]见 AsciiDoc.hs。5.2 分隔符与单元格前缀|顶层表格使用|作为表格开始/结束分隔符源码中separator |、border separator 见 AsciiDoc.hs。每个单元格输出以|开头其中来自对齐操作符AlignLeft映射为见 AsciiDoc.hs|是顶层表格的单元格分隔符。测试输入中entry alignleft声明了左对齐因此表头与数据单元格均带有前缀。若对齐为居中/右对齐则分别对应^与。5.3 单行单元格的渲染路径makeCell对单段文本单元格走[Plain x]分支AsciiDoc.hs输出分隔符 去尾空白的块内容。多段落单元格在嵌套层级为 2 时会被跳过并报告BlockNotRenderedAsciiDoc.hs——这也是 AsciiDoc 本身对表格单元格内块级内容表达能力有限所致。六、命令测试如何运行golden test 基础设施test/command/8665.md 属于 pandoc 的命令测试command tests其格式规范定义在 test/Tests/Command.hs 的文件头注释中第一行以%开头是要执行的命令可带参数与管道之后若干行作为 stdin 传给命令stdin 以单独一行的^D结束^D之后是期望的 stdout 输出若期望 stderr 输出需放在 stdout 之前且每行以2前缀开头若期望非零退出码最后一行写 退出码。测试加载逻辑位于 Command.hs测试运行时会扫描command目录下所有.md文件将每个文件解析为 (命令, 输入, 期望输出) 三元组通过execTest用真实 shell 执行命令并与期望输出做 golden 比对。注意 pandocToEmulate 会把命令中的pandoc替换为test-pandoc --emulate即用测试专用可执行文件模拟 CLI 行为保证测试环境可控。因此若要在本地验证本用例只需确保能构建测试套件并运行命令测试分组例如通过 cabal 运行test-pandoc的Command:测试组8665即为其中的一个 golden case。七、完整链路从 DocBook XML 到 AsciiDoc 输出整个转换发生在 pandoc 的统一 ASTPandoc 中间表示之上链路为DocBook XML ──reader──▶ Pandoc AST ──writer──▶ AsciiDocDocBook reader负责解析informaltable无标题表格见 src/Text/Pandoc/Readers/DocBook.hs 的元素支持清单与entry表格单元格见 DocBook.hs将其映射为 Pandoc 的Table块AsciiDoc writer再将Table块转换为前文分析的[cols...]| 单元格行结构单元格内的行内内容在写入前经过escapeString InTable转义测试输入中simpara内的amp;、lt;是 XML 实体reader 解码后即为字面、因此 writer 侧拿到的文本与测试期望中的转义目标一一对应。八、延伸价值如何利用该用例排查自己的转换问题遇到 AsciiDoc 表格列错乱优先检查单元格内容中是否含有未转义的|。按 #8665 的修复方式应输出{vbar}而非|遇到配对错乱检查文本中是否混入了字符它必须替换为{plus}否则会意外打开/关闭 passthrough 上下文编写类似回归测试参照 test/command/8665.md 的格式将最小复现输入与期望输出固化为.md命令测试即可为 AsciiDoc或任意格式writer 的转义逻辑建立持久回归保障避免修复被后续改动重新引入。小结test/command/8665.md 虽然只有 29 行却完整覆盖了 pandoc AsciiDoc writer 转义机制的核心EscContext区分普通与表格上下文、escapeString的 passthrough 状态机、{vbar}与{plus}属性引用、以及表格规格行与单元格前缀的生成规则。结合 AsciiDoc.hs 的源码与 changelog.md 中的 #8665 修复记录读者可以完整理解这一回归测试的设计意图并可将同样的转义策略迁移到自己的 AsciiDoc 生成工具中。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考