Pandoc AsciiDoc 输出中的特殊字符转义机制以命令测试 2337 为例【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本篇文章以 pandoc 仓库中的命令测试用例 test/command/2337.md 为核心深入剖析 Pandoc 将 HTML 转换为 AsciiDoc 时如何处理链接文本中的特殊字符[、]、等并溯源到 src/Text/Pandoc/Writers/AsciiDoc.hs 中escapeString的 passthrough 状态机实现。读完本文你将理解 AsciiDoc 宏语法的转义规则、Pandoc 为何用...包裹特殊文本以及如何运行与扩展这套命令测试。一、测试用例全景一个 8 行的回归测试test/command/2337.md全文是一个 fenced code block其内容符合 pandoc 命令测试command test的统一格式。整个文件只有一段输入/输出规格% pandoc -t asciidoc -f html a hrefhttp://example.com][/a ^D http://example.com[][]这一小段文本实际上蕴含了 pandoc 测试体系中三类核心信息命令定义以%开头声明要执行的命令为pandoc -t asciidoc -f html即从 HTML 读取、向 AsciiDoc 写出标准输入stdin%之后到^D之间的行会被作为输入文本传给命令本例中是一段包含超链接的 HTML 片段a hrefhttp://example.com][/a期望输出^D之后的行是 stdout 上的期望输出即http://example.com[][]。这套格式的完整语法在 test/Tests/Command.hs 的模块注释中有明确规定第一行%后跟要运行的命令随后是若干行 stdin输入以^D单独一行结束后续行是期望的 stdout 输出若期望 stderr则需在 stdout 之前用2前缀逐行标注若期望非零退出码则在最后一行以前缀标注。2337.md只涉及最简单的 stdin stdout 情形因此得以用如此紧凑的形式表达一个完整的回归场景。二、问题本质为什么链接文本][会破坏 AsciiDoc要理解这个测试先要认识 AsciiDoc 的链接宏语法。在 AsciiDoc 中带显示文本的链接通常写作http://example.com[显示文本]其宏语法为目标URL[属性或文本]方括号内是链接显示文本也可以进一步包含角色、ID 等属性。问题随之而来如果显示文本本身包含[或]就会与宏的属性括号产生歧义。本测试的输入正是极端情况——HTML 链接文本恰好是][输入a hrefhttp://example.com][/a一个指向 example.com、文本为][的链接若不加处理直接输出http://example.com[][][]AsciiDoc 处理器将无法确定属性括号的边界][会被误解析轻则链接文本错乱重则整行语法失效。Pandoc 给出的答案是passthrough 转义把特殊文本放进...中输出为http://example.com[][]AsciiDoc 将...视为“透传”区域其中的内容按字面原样呈现不参与宏语法解析。这样][既不会干扰外层链接宏的结构又能在最终渲染时精确显示为][。这正是本测试期望输出的由来。从变更历史看这一行为并非偶然在 changelog.md 中记录着 AsciiDoc writer 的 “Improve escaping (#10385, #2337, #6424)” 条目说明2337就是当年为修复/改进此类转义问题而引入的回归测试与另外两个编号#10385、#6424同属一次转义逻辑的集中改进。三、源码实现escapeString的 passthrough 状态机测试用例断言了输出结果而真正产生这一结果的逻辑位于 src/Text/Pandoc/Writers/AsciiDoc.hs 的escapeString函数。它是 Pandoc AsciiDoc writer 处理普通文本Str节点的核心转义入口escapeString :: EscContext - Text - Doc Text escapeString context t | T.any needsEscape t literal $ case T.foldl go (False, mempty) t of (True, x) - x -- close passthrough context (False, x) - x | otherwise literal t3.1 需要转义的字符集合needsEscape决定哪些字符必须转义needsEscape { True needsEscape True needsEscape True needsEscape * True needsEscape # True needsEscape _ True needsEscape True needsEscape True needsEscape [ True needsEscape ] True needsEscape \\ True needsEscape | True needsEscape _ False{、、、*、#、_、、、[、]、\、|都是 AsciiDoc 中的语法敏感字符*/_用于强调、用于行内代码、[/]用于属性括号、{用于属性引用、|用于表格列分隔。本例中的][正是命中了[与]两项。3.2 折叠过程与...的进入/退出函数用一个二元组(Bool, Text)作为折叠状态布尔值表示“当前是否处于passthrough 上下文内”其状态迁移逻辑如下go (True, x) (False, x {plus}) -- close context go (False, x) (False, x {plus}) go (True, x) | | context InTable (False, x {vbar}) -- close context go (False, x) | | context InTable (False, x {vbar}) go (True, x) c | needsEscape c (True, T.snoc x c) | otherwise (False, T.snoc (x ) c) go (False, x) c | needsEscape c (True, x T.singleton c) | otherwise (False, T.snoc x c)对照输入][走一遍状态机初始状态(False, )遇到[needsEscape [ True进入 passthrough 上下文并追加字符 →(True, [)遇到]needsEscape ] True且当前已在 passthrough 中因此不再重复输出直接追加 →(True, ][)折叠结束状态为(True, ][)函数尾部的模式匹配自动补上闭合的→ 最终得到][。这正是期望输出http://example.com[][]中链接文本部分的由来。从源码可以清晰看出这套设计的精妙之处连续的多个特殊字符共享同一个...区域避免出现[][]式的冗余输出passthrough 内部遇到普通字符go (True, x) c且needsEscape c False会先闭合、再输出普通字符把透传区域压缩到最短字符本身不能放进 passthrough 里否则会与外层的定界符冲突所以无论是否在 passthrough 中都用属性引用{plus}代替——这是 AsciiDoc 中输出字面的标准手法|字符在表格上下文中EscContext为InTable同样输出为{vbar}避免破坏表格列分隔。四、链接生成路径inlineToAsciiDoc的 Link 分支escapeString只负责文本转义而把转义结果装配成完整链接的是inlineToAsciiDoc对Link节点的处理位于 src/Text/Pandoc/Writers/AsciiDoc.hs。相关逻辑可概括为linktext - inlineListToAsciiDoc opts $ walk (concatMap fixCommas) txt let needsLinkPrefix case parseURI (T.unpack src) of Just u - uriScheme u notElem [http:,https:, ftp:, irc:, mailto:] _ - True let needsPassthrough -- T.isInfixOf src let prefix if needsLinkPrefix then text link: else empty let srcSuffix fromMaybe src (T.stripPrefix mailto: src) let useAuto case txt of [Str s] | escapeURI s srcSuffix - True _ - False return $ if needsPassthrough then if useAuto then link: literal srcSuffix [] else link: literal src [ linktext ] else if useAuto then literal srcSuffix else prefix literal src [ linktext ]对照本测试输入a hrefhttp://example.com][/aPandoc 解析后得到一个Link节点目标地址为http://example.com链接文本为单个Str ][needsLinkPrefix为Falsehttp://属于http:scheme无需link:前缀needsPassthrough为FalseURL 中不含--URL 中的--会被 AsciiDoc 误读为范围分隔符故单独触发另一条 passthrough 分支useAuto为False链接文本][与转义后的 URL 并不相等无法退化为自动链接autolink形式于是走prefix literal src [ linktext ]分支URL 原样输出linktext部分则是由inlineListToAsciiDoc递归调用escapeString产出的][最终拼出http://example.com[][]。从这段源码还可以引申出两条与转义配套的细节当链接文本与 URL 一致时useAuto TruePandoc 会输出纯 URL 的自动链接形式连方括号都省略当 URL 中带--时会改用link:URL[文本]的形态确保 URL 本身不被 AsciiDoc 的--语义破坏——这是与2337同属一次转义改进见 changelog 中 #10385、#6424的另一类边界场景。五、转义体系的更多成员{empty}与段落起始保护2337.md测试的是链接文本内的转义而同一套 writer 中还有两个相邻的转义机制值得一并理解它们共同构成 AsciiDoc 输出的防御体系。5.1 段落起始的needsEscaping在 src/Text/Pandoc/Writers/AsciiDoc.hs 中needsEscaping检查一段文本是否会被 AsciiDoc 误读为特殊结构needsEscaping :: Text - Bool needsEscaping s beginsWithOrderedListMarker s || isBracketed s它利用 Pandoc 自带的anyOrderedListMarker解析器判断段落是否以有序列表标记开头或是否整体被方括号包围isBracketed。一旦命中blockToAsciiDoc处理Para节点时就会在段落前插入{empty}属性引用见 AsciiDoc.hs用不可见字符“占位”避免段落被 AsciiDoc 误判为列表项或宏。这与escapeString形成互补一个守护段落开头一个守护行内文本。5.2 行内代码与表格上下文escapeString并非只服务于普通文本inlineToAsciiDoc处理Code节点时也复用了它见 AsciiDoc.hs在非 legacy 模式下代码内容同样经过escapeString并按tableNestingLevel决定使用Normal还是InTable上下文EscContext数据类型定义于 AsciiDoc.hs。这意味着表格单元格中的代码/文本会把|安全地输出为{vbar}从而避免破坏表格列结构——这解释了escapeString为何要把表格上下文作为显式参数贯穿整个状态机。六、如何运行与扩展这条测试test/command/2337.md属于 pandoc 的 golden 命令测试套件由 test/Tests/Command.hs 驱动。其执行模型在模块注释中有完整说明execTest会把%后的命令、stdin 输入组装成一次真实子进程调用再将 stdout/stderr 与^D后的期望输出做比对具体实现见 Tests/Command.hs 起的execTest函数。你可以手动复现该用例以观察实际行为前提是环境中已构建好 pandoc 可执行文件printf a hrefhttp://example.com][/a\n | pandoc -t asciidoc -f html预期输出与测试文件一致http://example.com[][]如果想在项目内运行整套命令测试可执行make test或直接运行cabal test调用测试套件测试入口为 test/test-pandoc.hs。新增类似用例时只需参照 Tests/Command.hs 的格式新建test/command/NNNN.md文件用%声明命令、^D分隔输入输出即可框架会自动将其纳入回归集合。七、小结一个测试文件背后的工程价值从外部看test/command/2337.md只是 8 行文本但从工程角度看它是一份可执行、可回归、可追溯的行为契约可执行%命令 stdin ^D 期望输出的格式让测试框架能直接驱动真实 pandoc 进程做逐字节比对可回归它在 changelog.md 中被明确关联到 “Improve escaping (#10385, #2337, #6424)” 的改进项锁定的是转义行为不被未来改动破坏可追溯结合 src/Text/Pandoc/Writers/AsciiDoc.hs 的escapeString状态机与 AsciiDoc.hs 的链接生成分支可以精确还原][每一步的产生过程。理解这个用例也就理解了 Pandoc AsciiDoc writer 处理特殊字符时的整体设计哲学能退化为自动链接就退化为自动链接能用最短 passthrough 就绝不多输出一个字符遇到与定界符冲突的字符如、表格中的|则用{plus}、{vbar}这类属性引用兜底。这套机制保证了任意来源的 HTML 文本在转换成 AsciiDoc 后既能通过语法校验又能保持原文的字面语义。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc AsciiDoc 输出中的特殊字符转义机制：以命令测试 2337 为例
Pandoc AsciiDoc 输出中的特殊字符转义机制以命令测试 2337 为例【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本篇文章以 pandoc 仓库中的命令测试用例 test/command/2337.md 为核心深入剖析 Pandoc 将 HTML 转换为 AsciiDoc 时如何处理链接文本中的特殊字符[、]、等并溯源到 src/Text/Pandoc/Writers/AsciiDoc.hs 中escapeString的 passthrough 状态机实现。读完本文你将理解 AsciiDoc 宏语法的转义规则、Pandoc 为何用...包裹特殊文本以及如何运行与扩展这套命令测试。一、测试用例全景一个 8 行的回归测试test/command/2337.md全文是一个 fenced code block其内容符合 pandoc 命令测试command test的统一格式。整个文件只有一段输入/输出规格% pandoc -t asciidoc -f html a hrefhttp://example.com][/a ^D http://example.com[][]这一小段文本实际上蕴含了 pandoc 测试体系中三类核心信息命令定义以%开头声明要执行的命令为pandoc -t asciidoc -f html即从 HTML 读取、向 AsciiDoc 写出标准输入stdin%之后到^D之间的行会被作为输入文本传给命令本例中是一段包含超链接的 HTML 片段a hrefhttp://example.com][/a期望输出^D之后的行是 stdout 上的期望输出即http://example.com[][]。这套格式的完整语法在 test/Tests/Command.hs 的模块注释中有明确规定第一行%后跟要运行的命令随后是若干行 stdin输入以^D单独一行结束后续行是期望的 stdout 输出若期望 stderr则需在 stdout 之前用2前缀逐行标注若期望非零退出码则在最后一行以前缀标注。2337.md只涉及最简单的 stdin stdout 情形因此得以用如此紧凑的形式表达一个完整的回归场景。二、问题本质为什么链接文本][会破坏 AsciiDoc要理解这个测试先要认识 AsciiDoc 的链接宏语法。在 AsciiDoc 中带显示文本的链接通常写作http://example.com[显示文本]其宏语法为目标URL[属性或文本]方括号内是链接显示文本也可以进一步包含角色、ID 等属性。问题随之而来如果显示文本本身包含[或]就会与宏的属性括号产生歧义。本测试的输入正是极端情况——HTML 链接文本恰好是][输入a hrefhttp://example.com][/a一个指向 example.com、文本为][的链接若不加处理直接输出http://example.com[][][]AsciiDoc 处理器将无法确定属性括号的边界][会被误解析轻则链接文本错乱重则整行语法失效。Pandoc 给出的答案是passthrough 转义把特殊文本放进...中输出为http://example.com[][]AsciiDoc 将...视为“透传”区域其中的内容按字面原样呈现不参与宏语法解析。这样][既不会干扰外层链接宏的结构又能在最终渲染时精确显示为][。这正是本测试期望输出的由来。从变更历史看这一行为并非偶然在 changelog.md 中记录着 AsciiDoc writer 的 “Improve escaping (#10385, #2337, #6424)” 条目说明2337就是当年为修复/改进此类转义问题而引入的回归测试与另外两个编号#10385、#6424同属一次转义逻辑的集中改进。三、源码实现escapeString的 passthrough 状态机测试用例断言了输出结果而真正产生这一结果的逻辑位于 src/Text/Pandoc/Writers/AsciiDoc.hs 的escapeString函数。它是 Pandoc AsciiDoc writer 处理普通文本Str节点的核心转义入口escapeString :: EscContext - Text - Doc Text escapeString context t | T.any needsEscape t literal $ case T.foldl go (False, mempty) t of (True, x) - x -- close passthrough context (False, x) - x | otherwise literal t3.1 需要转义的字符集合needsEscape决定哪些字符必须转义needsEscape { True needsEscape True needsEscape True needsEscape * True needsEscape # True needsEscape _ True needsEscape True needsEscape True needsEscape [ True needsEscape ] True needsEscape \\ True needsEscape | True needsEscape _ False{、、、*、#、_、、、[、]、\、|都是 AsciiDoc 中的语法敏感字符*/_用于强调、用于行内代码、[/]用于属性括号、{用于属性引用、|用于表格列分隔。本例中的][正是命中了[与]两项。3.2 折叠过程与...的进入/退出函数用一个二元组(Bool, Text)作为折叠状态布尔值表示“当前是否处于passthrough 上下文内”其状态迁移逻辑如下go (True, x) (False, x {plus}) -- close context go (False, x) (False, x {plus}) go (True, x) | | context InTable (False, x {vbar}) -- close context go (False, x) | | context InTable (False, x {vbar}) go (True, x) c | needsEscape c (True, T.snoc x c) | otherwise (False, T.snoc (x ) c) go (False, x) c | needsEscape c (True, x T.singleton c) | otherwise (False, T.snoc x c)对照输入][走一遍状态机初始状态(False, )遇到[needsEscape [ True进入 passthrough 上下文并追加字符 →(True, [)遇到]needsEscape ] True且当前已在 passthrough 中因此不再重复输出直接追加 →(True, ][)折叠结束状态为(True, ][)函数尾部的模式匹配自动补上闭合的→ 最终得到][。这正是期望输出http://example.com[][]中链接文本部分的由来。从源码可以清晰看出这套设计的精妙之处连续的多个特殊字符共享同一个...区域避免出现[][]式的冗余输出passthrough 内部遇到普通字符go (True, x) c且needsEscape c False会先闭合、再输出普通字符把透传区域压缩到最短字符本身不能放进 passthrough 里否则会与外层的定界符冲突所以无论是否在 passthrough 中都用属性引用{plus}代替——这是 AsciiDoc 中输出字面的标准手法|字符在表格上下文中EscContext为InTable同样输出为{vbar}避免破坏表格列分隔。四、链接生成路径inlineToAsciiDoc的 Link 分支escapeString只负责文本转义而把转义结果装配成完整链接的是inlineToAsciiDoc对Link节点的处理位于 src/Text/Pandoc/Writers/AsciiDoc.hs。相关逻辑可概括为linktext - inlineListToAsciiDoc opts $ walk (concatMap fixCommas) txt let needsLinkPrefix case parseURI (T.unpack src) of Just u - uriScheme u notElem [http:,https:, ftp:, irc:, mailto:] _ - True let needsPassthrough -- T.isInfixOf src let prefix if needsLinkPrefix then text link: else empty let srcSuffix fromMaybe src (T.stripPrefix mailto: src) let useAuto case txt of [Str s] | escapeURI s srcSuffix - True _ - False return $ if needsPassthrough then if useAuto then link: literal srcSuffix [] else link: literal src [ linktext ] else if useAuto then literal srcSuffix else prefix literal src [ linktext ]对照本测试输入a hrefhttp://example.com][/aPandoc 解析后得到一个Link节点目标地址为http://example.com链接文本为单个Str ][needsLinkPrefix为Falsehttp://属于http:scheme无需link:前缀needsPassthrough为FalseURL 中不含--URL 中的--会被 AsciiDoc 误读为范围分隔符故单独触发另一条 passthrough 分支useAuto为False链接文本][与转义后的 URL 并不相等无法退化为自动链接autolink形式于是走prefix literal src [ linktext ]分支URL 原样输出linktext部分则是由inlineListToAsciiDoc递归调用escapeString产出的][最终拼出http://example.com[][]。从这段源码还可以引申出两条与转义配套的细节当链接文本与 URL 一致时useAuto TruePandoc 会输出纯 URL 的自动链接形式连方括号都省略当 URL 中带--时会改用link:URL[文本]的形态确保 URL 本身不被 AsciiDoc 的--语义破坏——这是与2337同属一次转义改进见 changelog 中 #10385、#6424的另一类边界场景。五、转义体系的更多成员{empty}与段落起始保护2337.md测试的是链接文本内的转义而同一套 writer 中还有两个相邻的转义机制值得一并理解它们共同构成 AsciiDoc 输出的防御体系。5.1 段落起始的needsEscaping在 src/Text/Pandoc/Writers/AsciiDoc.hs 中needsEscaping检查一段文本是否会被 AsciiDoc 误读为特殊结构needsEscaping :: Text - Bool needsEscaping s beginsWithOrderedListMarker s || isBracketed s它利用 Pandoc 自带的anyOrderedListMarker解析器判断段落是否以有序列表标记开头或是否整体被方括号包围isBracketed。一旦命中blockToAsciiDoc处理Para节点时就会在段落前插入{empty}属性引用见 AsciiDoc.hs用不可见字符“占位”避免段落被 AsciiDoc 误判为列表项或宏。这与escapeString形成互补一个守护段落开头一个守护行内文本。5.2 行内代码与表格上下文escapeString并非只服务于普通文本inlineToAsciiDoc处理Code节点时也复用了它见 AsciiDoc.hs在非 legacy 模式下代码内容同样经过escapeString并按tableNestingLevel决定使用Normal还是InTable上下文EscContext数据类型定义于 AsciiDoc.hs。这意味着表格单元格中的代码/文本会把|安全地输出为{vbar}从而避免破坏表格列结构——这解释了escapeString为何要把表格上下文作为显式参数贯穿整个状态机。六、如何运行与扩展这条测试test/command/2337.md属于 pandoc 的 golden 命令测试套件由 test/Tests/Command.hs 驱动。其执行模型在模块注释中有完整说明execTest会把%后的命令、stdin 输入组装成一次真实子进程调用再将 stdout/stderr 与^D后的期望输出做比对具体实现见 Tests/Command.hs 起的execTest函数。你可以手动复现该用例以观察实际行为前提是环境中已构建好 pandoc 可执行文件printf a hrefhttp://example.com][/a\n | pandoc -t asciidoc -f html预期输出与测试文件一致http://example.com[][]如果想在项目内运行整套命令测试可执行make test或直接运行cabal test调用测试套件测试入口为 test/test-pandoc.hs。新增类似用例时只需参照 Tests/Command.hs 的格式新建test/command/NNNN.md文件用%声明命令、^D分隔输入输出即可框架会自动将其纳入回归集合。七、小结一个测试文件背后的工程价值从外部看test/command/2337.md只是 8 行文本但从工程角度看它是一份可执行、可回归、可追溯的行为契约可执行%命令 stdin ^D 期望输出的格式让测试框架能直接驱动真实 pandoc 进程做逐字节比对可回归它在 changelog.md 中被明确关联到 “Improve escaping (#10385, #2337, #6424)” 的改进项锁定的是转义行为不被未来改动破坏可追溯结合 src/Text/Pandoc/Writers/AsciiDoc.hs 的escapeString状态机与 AsciiDoc.hs 的链接生成分支可以精确还原][每一步的产生过程。理解这个用例也就理解了 Pandoc AsciiDoc writer 处理特殊字符时的整体设计哲学能退化为自动链接就退化为自动链接能用最短 passthrough 就绝不多输出一个字符遇到与定界符冲突的字符如、表格中的|则用{plus}、{vbar}这类属性引用兜底。这套机制保证了任意来源的 HTML 文本在转换成 AsciiDoc 后既能通过语法校验又能保持原文的字面语义。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考