Pandoc 命令回归测试 10537Pod 读取器encoding指令后空白行的正确消费【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本指南以 pandoc 仓库中的命令测试文件 test/command/10537.md 为研究对象剖析 Pod 读取器Pod Reader在处理encoding指令后的空白行时的行为以及 pandoc 命令测试框架的工作方式。读完本文你将掌握如何通过命令测试command test验证 pandoc 对特定输入格式的解析行为理解 Pod 读取器的实现细节并能独立阅读和编写同类回归测试用例。测试文件是什么test/command/10537.md 是 pandoc 仓库中用于回归测试的一个命令测试文件。整个文件由两个独立的代码块组成每个代码块都是一个完整的测试用例先给出一条需要执行的 pandoc 命令行再给出喂给该命令的标准输入stdin最后是期望的标准输出stdout。测试内容encoding后空白行的两种写法第一个测试用例% pandoc -f pod -t html encoding utf8 head1 NAME Test document ^D h1NAME/h1 pTest document/p第二个测试用例与第一个几乎相同唯一区别在于encoding utf8之后紧跟着两个空行即head1 NAME之前有一个额外的空行% pandoc -f pod -t html encoding utf8 head1 NAME Test document ^D h1NAME/h1 pTest document/p两个用例的期望输出完全一致h1NAME/h1和pTest document/p。这表明无论encoding utf8指令之后跟一个还是多个空白行pandoc 的 Pod 读取器都应正确跳过这些空白行并正常解析后续内容。这个测试对应 GitHub issue #10537 的修复在 Pod 读取器中消费encoding之后的空白行见 changelog.md 中的记载Consume blanks after encoding in pod reader (#10537, Evan Silberman)。命令测试文件的格式规范要理解这份测试文件需要先了解 pandoc 的命令测试格式。其格式说明位于 test/Tests/Command.hs要点如下代码块第一行以%开头后面是要执行的命令行之后是若干行文本作为标准输入传给命令标准输入以单独一行^D结束^D之后的行是期望的标准输出若期望标准错误输出则需放在最前面并以2前缀标记每行若期望非零退出码则最后一行应包含后跟退出码。对应地test/Tests/Command.hs 中的runCommandTest函数负责解析上述格式它用break (^D)切分输入与期望输出通过execTest真正执行命令并将实际输出与期望输出做 golden 比对。测试通过unsafePerformIO扫描test/command/目录下所有.md文件test/Tests/Command.hs因此每个命令测试文件都会自动注册为一个测试组文件中的每个代码块按序号成为一个独立的 golden 测试用例。Pod 读取器如何处理encodingencoding指令的解析实现在 src/Text/Pandoc/Readers/Pod.hsencoding :: PandocMonad m PodParser m Blocks encoding do cmd encoding anyLine optional blanklines logMessage $ IgnoredElement encoding; Pandoc requires UTF-8 input return mempty这段代码揭示了三层含义匹配encoding指令名后anyLine消费指令参数行即utf8这一行optional blanklines可选地消费随后的空白行——这正是 #10537 修复的关键所在。由于使用了optional无论encoding utf8之后是紧跟head1还是存在一个/多个空行解析器都能正常继续logMessage $ IgnoredElement encoding; Pandoc requires UTF-8 input会记录一条已忽略元素的日志说明 pandoc 始终要求 UTF-8 输入encoding指令本身不被转换为任何文档结构返回mempty空块。这就是为什么测试期望输出中完全没有encoding的痕迹该指令被读取器静默忽略只产生一条日志信息。从源码结构看encoding属于command组合子src/Text/Pandoc/Readers/Pod.hs所解析的 Pod 命令集合header、pod、cut、over、for、begin、encoding之一。回归测试要防止的回归这个测试文件的价值在于防止未来重构引入行为退化。具体而言回归风险点encoding指令后的空白行处理逻辑若被改写例如把optional blanklines误删或在别处要求严格一个空行带有多个空行的 Pod 文档就可能解析失败或输出异常双重覆盖测试同时给出一个空行和两个空行两种变体确保optional的语义被完整锁定而非只覆盖了恰好一个空行的情况命令层面验证测试走的是完整 CLI 路径pandoc -f pod -t html而非直接调用 Haskell 内部 API因此能捕获参数解析、输入读取等环节的问题。如何运行与验证在仓库根目录使用 cabal 或 stack 构建后可手动复现测试行为# 直接以命令行方式验证与测试用例 1 等价 printf encoding utf8\n\nhead1 NAME\n\nTest document\n | pandoc -f pod -t html # 运行整个命令测试套件 cabal test pandoc --test-options-p Command其中-p Command是 tasty 测试框架的 pattern 选项用于只运行命令测试组。测试通过test-pandoc --emulate见 test/Tests/Command.hs模拟真实 CLI 行为将每条% pandoc ...命令替换为对测试可执行文件的调用从而在测试环境内完成端到端验证。补充Pod 读取器的整体能力背景作为补充背景encoding只是 Pod 读取器支持的众多指令之一。完整的 Pod 支持范围可在综合测试 test/pod-reader.pod 及其期望的 native 输出 test/pod-reader.native 中看到覆盖了head1到head6各级标题、over/item/back列表项目符号列表、有序列表、定义列表可嵌套、cut切换非 Pod 区域、begin/end/for的格式化扩展区域以:class形式映射为 Div以格式名形式映射为 RawBlock等。若希望深入 Pod 读取器的其他指令解析逻辑可继续阅读 src/Text/Pandoc/Readers/Pod.hs 中的header、over、list、begin、for等解析器。小结test/command/10537.md 是一个小而精的回归测试标本它用两个仅差一个空行的用例锁定了 Pod 读取器消费encoding后的空白行这一行为其背后是 src/Text/Pandoc/Readers/Pod.hs 中optional blanklines的实现以及 test/Tests/Command.hs 所定义的命令测试框架。理解这份文件既有助于你读懂 pandoc 的回归测试体系也为编写针对特定输入格式的解析行为测试提供了可直接套用的模板。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考