Pandoc Lua 过滤器 - 调试过滤器

调试 Lua 过滤器

William Lupton 编写了一个 Lua 模块，其中包含了一些调试 Lua 过滤器的便捷函数，包括能够以美观格式打印由过滤器操作的 Pandoc AST 元素的函数：这个模块可以在 https://github.com/wlupton/pandoc-lua-logging 找到。

可以使用调试接口来暂停执行并逐行跟踪 Lua 过滤器在其在 Pandoc 内部运行时的过程。这是通过使用 mobdebug 包的远程调试接口实现的。虽然 mobdebug 可以从终端运行，但在捐赠版的 Lua 编辑器和集成开发环境 ZeroBrane Studio 中运行更为有用。ZeroBrane 提供了一个 REPL 控制台和用户界面，可以逐步执行并查看所有变量和状态。

ZeroBrane 并不捆绑 Lua 5.4，但它可以对其进行调试，因此你应该安装 Lua 5.4，并使用 luarocks 安装 mobdebug 及其依赖 luasocket 。ZeroBrane 可以通过在设置文件中添加 path.lua = "/path/to/your/lua" 来使用你的 Lua 5.4 安装。接下来，在 ZeroBrane 中打开你的 Lua 过滤器，并在你想设置断点的地方添加 require('mobdebug').start()。然后确保项目 > Lua 解释器设置为你在设置中添加的 “Lua”，并启用 “启动调试服务器” 在这里查看详细说明 。按照常规方式运行 Pandoc，ZeroBrane 应该会在正确的行中断。

常见陷阱

• AST 元素未更新

  过滤后的元素只有当过滤函数返回一个新的元素来替换它时才会更新。像下面这样的函数没有效果，因为它没有返回任何值：

  function Str(str)
    str.text = string.upper(str.text)
  end
  

  正确的版本应该是：

  function Str(str)
    str.text = string.upper(str.text)
    return str
  end
  

• 模式行为依赖于区域设置

  Lua 的模式库中的字符类依赖于当前的区域设置：例如，字符 © 在 CP-1252 区域设置中会被视为标点符号，并由模式 %p 匹配，但在使用 UTF-8 区域设置的系统上则不会。为了确保模式和字符类的统一处理，可以在 Lua 脚本的顶部添加 os.setlocale 'C' 来使用 “C” 区域设置。

• 字符串库不支持 Unicode

  Lua 的 string 库将每个字节视为一个单独的字符。像 string.upper 这样的函数在应用于包含非 ASCII 字符的单词时不会有预期的效果。同样地，像 [☃] 这样的模式会匹配任何字节 \240、\159、\154 和 \178，但 不会 匹配 “snowman” Unicode 字符。

  使用 pandoc.text 模块来进行支持 Unicode 的转换，并考虑使用 lpeg 或 re 库来进行模式匹配。