Pandoc推出Lua过滤器支持文档自定义转换

背景

Pandoc 是一个流行的文档格式转换工具，支持读取多种标记格式（如 Markdown、HTML、LaTeX 等）并输出为另一种格式。为了实现高度可定制的转换，Pandoc 长期以来支持通过“过滤器”（filters）来操作文档的抽象语法树（AST）。传统过滤器基于 JSON：Pandoc 将 AST 序列化为 JSON 输出到 stdout，过滤器读取 stdin 中的 JSON，处理后写回 stdout，再被 Pandoc 反序列化。这种方式虽然灵活，但存在两个主要缺点：一是通过管道读写 JSON 带来了显著的性能开销；二是过滤器依赖外部环境（如特定的编程语言解释器和 JSON 处理库），用户无法直接分享一个可在任意 Pandoc 版本下运行的过滤器。

核心内容

从 Pandoc 2.0 开始，内置了 Lua 解释器（版本 5.4）和用于创建过滤器的 Lua 库，从而无需任何外部依赖即可编写 Lua 过滤器。Pandoc 数据类型的 Lua 绑定直接通过内存进行 marshal，避免了 JSON 序列化/反序列化的开销。

Lua 过滤器示例

以下 Lua 过滤器将粗体（Strong）转换为小型大写（SmallCaps）：

return {
  Strong = function(elem)
    return pandoc.SmallCaps(elem.content)
  end,
}

或等价写法：

function Strong(elem)
  return pandoc.SmallCaps(elem.content)
end

该过滤器遍历 AST，遇到 Strong 元素时将其替换为内容相同的 SmallCaps 元素。将上述代码保存为 smallcaps.lua，然后通过 --lua-filter=smallcaps.lua 选项运行 Pandoc。

性能对比

原文用 Pandoc 手册（MANUAL.txt）转换为 HTML，对比了相同功能的 JSON 过滤器（分别用编译型 Haskell 和解释型 Python 实现）与 Lua 过滤器的性能。结果显示，Lua 过滤器避免了通过管道 marshal JSON 的巨大开销。

Lua 过滤器结构

• 定义方式：过滤器是一个以元素类型名（如 Str、Para、Meta、Pandoc）为键、函数为值的 Lua 表。
• 使用方式：通过 --lua-filter=文件名.lua 多次指定多个 Lua 过滤器，Pandoc 按命令行顺序依次应用（与 JSON 过滤器交替执行）。
• 默认收集：若 Lua 脚本不显式返回一个过滤器表，Pandoc 会收集顶层函数中名称与 Pandoc 元素类型匹配的函数，自动组合成一个过滤器。
• 返回列表（已不推荐）：早期支持返回一个函数列表，但现已不推荐，应使用 walk 方法顺序处理。

过滤函数的行为

每个文档元素被遍历时，若过滤器中存在对应名称的函数，则该函数被调用，输入为当前元素。返回值为以下之一：

• nil：元素保持不变。
• 一个 Pandoc 对象：类型必须与输入相同，替换原对象。
• 一个 Pandoc 对象列表：替换原对象，并与相邻元素合并（空列表则删除对象）。若返回单个元素（而非列表），对块列表或内联列表的过滤函数会报错。

若未找到精确匹配的函数，Pandoc 会查找通用的回退函数 Inline 或 Block，分别匹配所有内联元素或块元素。仍未匹配则保持原样。

元素序列过滤器

有时需要知道元素在文档中的顺序，例如处理连续的内联列表或块列表。从 Pandoc 2.9.2 开始，支持两种特殊函数名：

• Inlines (inlines)：应用于所有内联元素列表（如段落的内容、图像的描述）。参数 inlines 是 List 类型的 Inline 元素。返回值必须为 nil 或相同类型的列表。
• Blocks (blocks)：应用于所有块元素列表（如元数据块、列表项、文档主要内容）。参数是 List 类型的 Block 元素。返回值要求同上。

注意：不允许返回单个元素，因为单个元素在此上下文中通常暗示 bug。

遍历顺序

从 Pandoc 2.17 开始，可通过设置 traverse 键（值为 'topdown' 或 'typewise'）选择遍历方式，默认 'typewise'。

• Typewise（类型优先）：按固定顺序调用过滤器函数：Inline 元素函数 → Inlines 函数 → Block 元素函数 → Blocks 函数 → Meta 函数 → Pandoc 函数。跳过缺失的函数。也可通过 walk 方法手动强制改变顺序。
• Topdown（深度优先）：从根向下深度优先遍历，在一个运行中按顺序尝试。例如块列表 [Plain [Str "a"], Para [Str "b"]] 将依次尝试 Blocks、Plain、Inlines、Str、Para、Inlines、Str。可通过返回 false 作为第二个值来中止对子元素的处理（例如排除脚注内容）。

全局变量

Pandoc 会在 Lua 过滤器中设置全局变量 FORMAT，其值为当前 Pandoc 使用的 writer 格式（如 "html"、"latex" 等）。用户可在过滤器中直接读取该变量。

关键要点

• 性能优势：Lua 过滤器避免了 JSON 序列化/反序列化的管道开销，比传统 JSON 过滤器快得多。
• 零外部依赖：Lua 解释器和 Lua 库内置于 Pandoc 可执行文件中，用户无需安装额外软件或库。
• 过滤器本质：Lua 过滤器是一个返回表或收集顶层函数的脚本，表中键为元素类型名，值为处理函数。
• 三种返回值：nil 保持不变、同类型对象替换、同类型对象列表替换/插入/删除。
• 元素序列处理：通过 Inlines 和 Blocks 函数可操作整个内联/块列表，返回值必须为列表或 nil。
• 遍历顺序可定制：typewise 按元素类型分组调用，topdown 深度优先且支持通过返回 false 剪枝。
• 全局变量：FORMAT 提供当前输出格式，可用于条件性处理。
• 向下兼容：旧版返回函数列表的方式仍可使用，但官方鼓励使用 walk 方法。

意义与影响

Pandoc 内置 Lua 过滤器机制极大地降低了文档转换定制化的门槛和性能成本。传统 JSON 过滤器虽然支持任意语言，但部署复杂（需要解释器、库、环境变量等），且因管道传输 JSON 导致较大性能损失。Lua 过滤器将执行环境压缩为一个单一二进制文件（Pandoc 本身），用户只需分享一个 .lua 文件即可与他人协作，大幅提升了可移植性和易用性。

此外，Lua 过滤器的设计兼顾灵活性与安全性：支持多种返回值实现替换、插入和删除；提供元素序列过滤和自定义遍历顺序；允许通过 false 剪枝实现精细控制。这些特性使得复杂的文档处理（如元素统计、格式转换、元数据操作）变得简单高效。

该特性自 Pandoc 2.0 发布以来持续演进，已成为 Pandoc 生态中不可或缺的一部分。对于技术写作者、出版业者和需要批量文档转换的用户而言，Lua 过滤器提供了一种轻量级、可复用且性能优异的解决方案，进一步巩固了 Pandoc 作为文档转换瑞士军刀的地位。