Pandoc Lua 筛选器

引言

Pandoc 一直以来都支持筛选器，它允许在解析和写入阶段之间操作 pandoc 的抽象语法树 (AST)。传统的 pandoc 筛选器接受 pandoc AST 的 JSON 表示，并产生修改后的 AST 的 JSON 表示。它们可以用任何编程语言编写，并使用 --filter 选项从 pandoc 调用。

尽管传统筛选器非常灵活，但它们也有一些缺点。首先，将 JSON 写入 stdout 和从 stdin 读取（在筛选器的两端各一次）会产生一些开销。其次，筛选器是否能正常工作将取决于用户环境的细节。筛选器可能需要可用的特定编程语言的解释器，以及用于处理 JSON 格式的 pandoc AST 的库。不能仅仅提供一个可以被拥有特定版本 pandoc 可执行文件的任何人使用的筛选器。

从 2.0 版本开始，pandoc 可以用 Lua 编写筛选器，而且完全没有任何外部依赖。一个 Lua 解释器（5.4 版本）和一个用于创建 pandoc 筛选器的 Lua 库内置于 pandoc 可执行文件中。Pandoc 数据类型直接编组到 Lua，避免了将 JSON 写入 stdout 和从 stdin 读取的开销。

下面是一个将粗体强调转换为小型大写字母的 Lua 筛选器示例

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，使用用编译型 Haskell (smallcaps) 和解释型 Python (smallcaps.py) 编写的相同 JSON 筛选器的版本

命令	时间
`pandoc`	1.01秒
`pandoc --filter ./smallcaps`	1.36秒
`pandoc --filter ./smallcaps.py`	1.40秒
`pandoc --lua-filter ./smallcaps.lua`	1.03秒

正如你所见，Lua 筛选器避免了通过管道进行 JSON 编组的巨大开销。

Lua 筛选器结构

Lua 筛选器是带有元素名称作为键，值为作用于这些元素的函数的表。

筛选器应放在单独的文件中，并通过 --lua-filter 命令行参数传递。例如，如果一个筛选器定义在文件 current-date.lua 中，那么它的应用方式如下：

pandoc --lua-filter=current-date.lua -f markdown MANUAL.txt

--lua-filter 选项可以多次提供。Pandoc 按命令行上出现的顺序应用所有筛选器（包括通过 --filter 指定的 JSON 筛选器和通过 --lua-filter 指定的 Lua 筛选器）。

Pandoc 期望每个 Lua 文件返回一个筛选器列表。该列表中的筛选器按顺序调用，每个筛选器作用于前一个筛选器的结果。如果筛选器脚本没有返回值，那么 pandoc 将尝试通过收集所有名称与 pandoc 元素名称（例如 Str、Para、Meta 或 Pandoc）对应的顶层函数来生成一个筛选器。（这就是为什么上面两个示例是等效的。）

对于每个筛选器，文档都会被遍历，每个元素都会受到筛选器的作用。对于筛选器包含条目（即同名的函数）的元素，它们将被传递给 Lua 元素筛选函数。换句话说，筛选器条目将为文档中的每个相应元素调用，并将 respective 元素作为输入。

筛选器函数必须返回以下值之一：

nil：这意味着对象应保持不变。
一个 pandoc 对象：它必须与输入类型相同，并将替换原始对象。
一个 pandoc 对象列表：它们将替换原始对象；列表将与原始对象邻近的对象合并（插入到原始对象所属的列表中）；返回一个空列表会删除该对象。

函数的输出必须生成一个与输入类型相同的元素。这意味着作用于内联元素的筛选器函数必须返回 nil、一个内联元素或一个内联元素列表，而筛选块元素的函数必须返回 nil、一个块元素或一个块元素列表。如果违反此条件，Pandoc 将抛出错误。

如果没有匹配元素节点类型的函数，则筛选系统将查找更通用的回退函数。支持两个回退函数：Inline 和 Block。每个函数匹配 respective 类型的元素。

没有匹配函数的元素将保持不变。

有关 pandoc 元素的列表，请参阅模块文档。

元素序列上的筛选器

对于某些筛选任务，了解元素在文档中出现的顺序是必要的。此时仅检查单个元素是不够的。

有两个特殊函数名，可用于定义块或内联元素列表上的筛选器。

内联元素 (inlines): 如果在筛选器中存在，此函数将在所有内联元素列表上调用，例如 Para (段落) 块的内容，或 Image 的描述。传递给函数的 inlines 参数将是每个调用 List 的 Inline 元素。
块元素 (blocks): 如果在筛选器中存在，此函数将在所有块元素列表上调用，例如 MetaBlocks 元元素块的内容，每个列表项，以及 Pandoc 文档的主内容。传递给函数的 blocks 参数将是每个调用 List 的 Block 元素。

这些筛选器函数是特殊的，因为其返回值必须是 nil（列表将保持不变），或者必须是正确类型的列表，即与输入参数相同的类型。此处不允许使用单个元素作为返回值，因为在这种情况下单个元素通常表示一个错误。

有关示例，请参阅 “在引文前删除空格”。

此功能已在 pandoc 2.9.2 中添加。

遍历顺序

可以通过将 traverse 键设置为 'topdown' 或 'typewise' 来选择筛选器的遍历顺序；默认是 'typewise'。

示例

local filter = {
  traverse = 'topdown',
  -- ... filter functions ...
}
return filter

此功能已在 pandoc 2.17 中添加；早期版本会忽略 traverse 设置。

按类型遍历

筛选器集中的元素筛选函数按固定顺序调用，跳过不存在的函数

用于 内联元素 的函数，
Inlines 筛选函数，
用于 块元素 的函数，
Blocks 筛选函数，
Meta 筛选函数，最后是
Pandoc 筛选函数。

通过显式返回多个筛选器集，仍然可以强制不同的顺序。例如，如果 Meta 的筛选器要在 Str 的筛选器之前运行，可以这样写：

-- ... filter definitions ...

return {
  { Meta = Meta },  -- (1)
  { Str = Str }     -- (2)
}

筛选器集按返回顺序应用。因此，集合 (1) 中的所有函数都将在集合 (2) 中的函数之前运行，从而导致 Meta 的筛选器函数在 Str 元素的筛选开始之前运行。

自顶向下遍历

有时从根到叶深度优先遍历文档树，并在一次运行中完成，会更自然。

例如，一个块列表 [Plain [Str "a"], Para [Str "b"]] 将按顺序尝试以下筛选器函数：Blocks、Plain、Inlines、Str、Para、Inlines、Str。

通过从筛选器函数返回 false 作为第二个值，可以截断自顶向下遍历。在这种情况下，不会处理返回元素的子元素。

例如，要排除脚注内容的处理，可以这样写：

traverse = 'topdown'
function Note (n)
  return n, false
end

全局变量

Pandoc 通过设置全局变量向 Lua 筛选器传递额外数据。

FORMAT

全局变量 FORMAT 被设置为 pandoc 写入器使用的格式（html5、latex 等），因此筛选器的行为可以根据最终输出格式进行条件设置。

PANDOC_READER_OPTIONS

提供给解析器的选项的表。（ReaderOptions）

PANDOC_WRITER_OPTIONS

将传递给写入器的选项的表。虽然对象可以修改，但这些更改将 **不会** 被 pandoc 采纳。（WriterOptions）

在 **自定义写入器** 中访问此变量是 **已弃用** 的。从 pandoc 3.0 开始，它在自定义写入器中被设置为一个占位符值（默认选项）。通过 Writer 或 ByteStringWriter 函数可以访问实际的写入器选项，这些选项作为第二个函数参数传递给它们。

自从：pandoc 2.17

PANDOC_VERSION

包含 pandoc 版本，格式为 Version 对象，该对象表现得像一个数字索引表，最高有效数字在前。例如，对于 pandoc 2.7.3，该变量的值等同于表 {2, 7, 3}。使用 tostring(PANDOC_VERSION) 可以生成版本字符串。此变量在自定义写入器中也设置。

PANDOC_API_VERSION

包含 pandoc 编译所依据的 pandoc-types API 的版本。它以数字索引表的形式给出，最高有效数字在前。例如，如果 pandoc 是根据 pandoc-types 1.17.3 编译的，那么该变量的值将表现得像表 {1, 17, 3}。使用 tostring(PANDOC_API_VERSION) 可以生成版本字符串。此变量在自定义写入器中也设置。

PANDOC_SCRIPT_FILE

用于调用筛选器的文件名。此值可用于查找相对于脚本文件的文件。此变量在自定义写入器中也设置。

PANDOC_STATE

所有读取器和写入器共享的状态。Pandoc 使用它来收集和传递信息。此变量的值是 CommonState 类型，并且是只读的。

pandoc

pandoc 模块（在下一节中介绍）可通过全局变量 pandoc 访问。此处介绍的其他模块作为子字段加载在其各自的名称下。

lpeg

此变量保存 lpeg 模块，这是一个基于解析表达式语法 (PEG) 的包。它提供了出色的解析实用程序，并在官方 LPeg 主页上进行了文档记录。Pandoc 使用该库的内置版本，除非它已被包维护者配置为依赖系统范围的安装。

请注意，require 'lpeg' 的结果不一定等于此值；require 机制优先于内置版本使用系统的 lpeg 库。

re

包含 LPeg.re 模块，该模块建立在 LPeg 之上，并提供了 regex 引擎的实现。Pandoc 使用该库的内置版本，除非它已被包维护者配置为依赖系统范围的安装。

请注意，require 're 的结果不一定等于此值；require 机制优先于内置版本使用系统的 lpeg 库。

Pandoc 模块

pandoc Lua 模块加载到筛选器的 Lua 环境中，并提供一组函数和常量，以便更容易地创建和操作元素。全局变量 pandoc 绑定到模块，通常出于此原因不应被覆盖。

该模块提供了两个主要功能：元素创建函数和对 pandoc 主要功能的一些访问。

元素创建

像 Str、Para 和 Pandoc 这样的元素创建函数旨在允许轻松创建新元素，这些元素易于使用，并且可以从 Lua 环境中读回。在内部，pandoc 使用这些函数来创建传递给元素筛选函数的 Lua 对象。这意味着通过此模块创建的元素将与通过筛选器函数参数访问的元素完全相同。

公开的 pandoc 功能

一些 pandoc 函数已在 Lua 中提供：

walk_block 和 walk_inline 允许在特定块或内联元素内部应用筛选器；
read 允许筛选器将字符串解析为 pandoc 文档；
pipe 运行外部命令，其输入和输出为字符串；
pandoc.mediabag 模块允许访问“mediabag”，它存储可能包含在最终文档中的二进制内容，例如图像；
pandoc.utils 模块包含各种实用函数。

Lua 解释器初始化

pandoc 的 Lua 解释器的初始化可以通过将文件 init.lua 放在 pandoc 的数据目录中来控制。一个常见的用例是加载额外的模块，甚至修改默认模块。

以下代码片段是在添加到 init.lua 时可能很有用的示例。该代码段将 text 模块中定义的所有 Unicode 感知函数添加到默认 string 模块中，并加上前缀 uc_。

for name, fn in pairs(require 'text') do
  string['uc_' .. name] = fn
end

这样就可以使用冒号语法（mystring:uc_upper()）将这些函数应用于字符串。

调试 Lua 筛选器

通过执行静态分析可以避免许多错误。luacheck 可用于此目的。Pandoc 筛选器的 Luacheck 配置文件可在 https://github.com/rnwst/pandoc-luacheckrc 找到。

William Lupton 编写了一个 Lua 模块，其中包含一些用于调试 Lua 筛选器的便捷函数，包括可以美化打印筛选器操作的 Pandoc AST 元素的函数：它可在 https://github.com/wlupton/pandoc-lua-logging 找到。

可以使用调试接口来暂停执行并逐行调试 Lua 筛选器，因为它在 Pandoc 中运行。这是通过 mobdebug 包的远程调试接口实现的。尽管 mobdebug 可以从终端运行，但在捐赠软件 Lua 编辑器和 IDE ZeroBrane Studio 中运行更有用。ZeroBrane 提供了一个 REPL 控制台和 UI 来单步执行并查看所有变量和状态。

ZeroBrane 不自带 Lua 5.4，但它可以调试它，所以你应该安装 Lua 5.4，然后使用 luarocks 添加 mobdebug 及其依赖项 luasocket。ZeroBrane 可以使用你的 Lua 5.4 安装，方法是在你的 ZeroBrane 设置文件中添加 path.lua = "/path/to/your/lua"。然后，在 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 区域设置的系统上则不匹配。

确保模式和字符类统一处理的可靠方法是使用“C”区域设置，方法是将 os.setlocale 'C' 添加到 Lua 脚本的顶部。

字符串库不感知 Unicode

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

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

示例

以下筛选器作为示例提供。一个有用的 Lua 筛选器仓库（也可作为好例子）可在 https://github.com/pandoc/lua-filters 找到。

宏替换

以下筛选器将字符串 {{helloworld}} 转换为强调文本“Hello, World”。

return {
  {
    Str = function (elem)
      if elem.text == "{{helloworld}}" then
        return pandoc.Emph {pandoc.Str "Hello, World"}
      else
        return elem
      end
    end,
  }
}

在 LaTeX 和 HTML 输出中居中图像

对于 LaTeX，将图像包装在 LaTeX 片段中，这些片段会导致图像水平居中。在 HTML 中，使用图像元素的 style 属性来实现居中。

-- Filter images with this function if the target format is LaTeX.
if FORMAT:match 'latex' then
  function Image (elem)
    -- Surround all images with image-centering raw LaTeX.
    return {
      pandoc.RawInline('latex', '\\hfill\\break{\\centering'),
      elem,
      pandoc.RawInline('latex', '\\par}')
    }
  end
end

-- Filter images with this function if the target format is HTML
if FORMAT:match 'html' then
  function Image (elem)
    -- Use CSS style to center image
    elem.attributes.style = 'margin:auto; display: block;'
    return elem
  end
end

在元数据中设置日期

如果文档的元数据中尚未设置日期，此筛选器会将日期设置为当前日期。

function Meta(m)
  if m.date == nil then
    m.date = os.date("%B %e, %Y")
    return m
  end
end

在引文前删除空格

此筛选器删除“文本中作者”引文之前的所有空格。在 Markdown 中，“文本中作者”引文（例如 @citekey）必须前面有一个空格。如果不需要这些空格，则必须使用筛选器将其删除。

local function is_space_before_author_in_text(spc, cite)
  return spc and spc.t == 'Space'
    and cite and cite.t == 'Cite'
    -- there must be only a single citation, and it must have
    -- mode 'AuthorInText'
    and #cite.citations == 1
    and cite.citations[1].mode == 'AuthorInText'
end

function Inlines (inlines)
  -- Go from end to start to avoid problems with shifting indices.
  for i = #inlines-1, 1, -1 do
    if is_space_before_author_in_text(inlines[i], inlines[i+1]) then
      inlines:remove(i)
    end
  end
  return inlines
end

用元数据值替换占位符

Lua 筛选器函数按以下顺序运行：

内联 → 块 → 元数据 → Pandoc.

通过使用同一个文件中的两个筛选器，仍然可以将信息从更高级别（例如元数据）传递到更低级别（例如内联）

local vars = {}

function get_vars (meta)
  for k, v in pairs(meta) do
    if pandoc.utils.type(v) == 'Inlines' then
      vars["%" .. k .. "%"] = {table.unpack(v)}
    end
  end
end

function replace (el)
  if vars[el.text] then
    return pandoc.Span(vars[el.text])
  else
    return el
  end
end

return {{Meta = get_vars}, {Str = replace}}

如果文件 occupations.md 的内容是：

---
name: Samuel Q. Smith
occupation: Professor of Oenology
---

Name

:   %name%

Occupation

:   %occupation%

然后运行 pandoc --lua-filter=meta-vars.lua occupations.md 将输出：

<dl>
<dt>Name</dt>
<dd><p><span>Samuel Q. Smith</span></p>
</dd>
<dt>Occupation</dt>
<dd><p><span>Professor of Oenology</span></p>
</dd>
</dl>

修改 pandoc 的 `MANUAL.txt` 以便生成 man 页

这是我们在将 MANUAL.txt 转换为 man 页时使用的筛选器。它将一级标题转换为大写（使用 walk 转换标题内的内联元素），删除脚注，并将链接替换为普通文本。

-- we use pandoc.text to get a UTF-8 aware 'upper' function
local text = pandoc.text

function Header(el)
    if el.level == 1 then
      return el:walk {
        Str = function(el)
            return pandoc.Str(text.upper(el.text))
        end
      }
    end
end

function Link(el)
    return el.content
end

function Note(el)
    return {}
end

从论文创建讲义

此筛选器提取文档中的所有编号示例、章节标题、块引用和图形，以及任何具有 handout 类的 div。（请注意，仅包含“外层”的块；忽略嵌套结构（如列表项）中的块。）

-- creates a handout from an article, using its headings,
-- blockquotes, numbered examples, figures, and any
-- Divs with class "handout"

function Pandoc(doc)
    local hblocks = {}
    for i,el in pairs(doc.blocks) do
        if (el.t == "Div" and el.classes[1] == "handout") or
           (el.t == "BlockQuote") or
           (el.t == "OrderedList" and el.style == "Example") or
           (el.t == "Para" and #el.c == 1 and el.c[1].t == "Image") or
           (el.t == "Header") then
           table.insert(hblocks, el)
        end
    end
    return pandoc.Pandoc(hblocks, doc.meta)
end

计算文档中的单词

此筛选器计算文档正文中的单词（省略标题和摘要等元数据），包括代码中的单词。它应该比直接在 Markdown 文档上运行 wc -w 更准确，因为后者会将标记字符，如 ATX 标题前的 #，或 HTML 文档中的标签，计为单词。要运行它，请执行 pandoc --lua-filter wordcount.lua myfile.md。

-- counts words in a document

words = 0

wordcount = {
  Str = function(el)
    -- we don't count a word if it's entirely punctuation:
    if el.text:match("%P") then
        words = words + 1
    end
  end,

  Code = function(el)
    _,n = el.text:gsub("%S+","")
    words = words + n
  end,

  CodeBlock = function(el)
    _,n = el.text:gsub("%S+","")
    words = words + n
  end
}

function Pandoc(el)
    -- skip metadata, just count body:
    el.blocks:walk(wordcount)
    print(words .. " words in body")
    os.exit(0)
end

将 ABC 代码转换为音乐符号

此筛选器通过运行 abcm2ps 和 ImageMagick 的 convert 来将类为 abc 的代码块替换为图像。（关于 ABC 符号，请参阅 https://abcnotation.com。）

图像被添加到 mediabag。对于输出到二进制格式，pandoc 将使用 mediabag 中的图像。对于文本格式，使用 --extract-media 指定一个目录，mediabag 中的文件将写入该目录，或（仅限 HTML）使用 --embed-resources。

-- Pandoc filter to process code blocks with class "abc" containing
-- ABC notation into images.
--
-- * Assumes that abcm2ps and ImageMagick's convert are in the path.
-- * For textual output formats, use --extract-media=abc-images
-- * For HTML formats, you may alternatively use --embed-resources

local filetypes = { html = {"png", "image/png"}
                  , latex = {"pdf", "application/pdf"}
                  }
local filetype = filetypes[FORMAT][1] or "png"
local mimetype = filetypes[FORMAT][2] or "image/png"

local function abc2eps(abc, filetype)
    local eps = pandoc.pipe("abcm2ps", {"-q", "-O", "-", "-"}, abc)
    local final = pandoc.pipe("convert", {"-", filetype .. ":-"}, eps)
    return final
end

function CodeBlock(block)
    if block.classes[1] == "abc" then
        local img = abc2eps(block.text, filetype)
        local fname = pandoc.sha1(img) .. "." .. filetype
        pandoc.mediabag.insert(fname, mimetype, img)
        return pandoc.Para{ pandoc.Image({pandoc.Str("abc tune")}, fname) }
    end
end

使用 TikZ 构建图像

此筛选器将原始 LaTeX TikZ 环境转换为图像。它同时适用于 PDF 和 HTML 输出。TikZ 代码使用 pdflatex 编译为图像，并使用 pdf2svg 将图像从 pdf 转换为 svg 格式，因此这两者都必须在系统路径中。转换后的图像会缓存到工作目录，并根据源的哈希值命名，这样在每次构建文档时都不需要重新生成它们。（一个更复杂的版本可能会将这些放在一个特殊的缓存目录中。）

local system = require 'pandoc.system'

local tikz_doc_template = [[
\documentclass{standalone}
\usepackage{xcolor}
\usepackage{tikz}
\begin{document}
\nopagecolor
%s
\end{document}
]]

local function tikz2image(src, filetype, outfile)
  system.with_temporary_directory('tikz2image', function (tmpdir)
    system.with_working_directory(tmpdir, function()
      local f = io.open('tikz.tex', 'w')
      f:write(tikz_doc_template:format(src))
      f:close()
      os.execute('pdflatex tikz.tex')
      if filetype == 'pdf' then
        os.rename('tikz.pdf', outfile)
      else
        os.execute('pdf2svg tikz.pdf ' .. outfile)
      end
    end)
  end)
end

extension_for = {
  html = 'svg',
  html4 = 'svg',
  html5 = 'svg',
  latex = 'pdf',
  beamer = 'pdf' }

local function file_exists(name)
  local f = io.open(name, 'r')
  if f ~= nil then
    io.close(f)
    return true
  else
    return false
  end
end

local function starts_with(start, str)
  return str:sub(1, #start) == start
end


function RawBlock(el)
  if starts_with('\\begin{tikzpicture}', el.text) then
    local filetype = extension_for[FORMAT] or 'svg'
    local fbasename = pandoc.sha1(el.text) .. '.' .. filetype
    local fname = system.get_working_directory() .. '/' .. fbasename
    if not file_exists(fname) then
      tikz2image(el.text, filetype, fname)
    end
    return pandoc.Para({pandoc.Image({}, fbasename)})
  else
   return el
  end
end

使用示例

pandoc --lua-filter tikz.lua -s -o cycle.html <<EOF
Here is a diagram of the cycle:

\begin{tikzpicture}

\def \n {5}
\def \radius {3cm}
\def \margin {8} % margin in angles, depends on the radius

\foreach \s in {1,...,\n}
{
  \node[draw, circle] at ({360/\n * (\s - 1)}:\radius) {$\s$};
  \draw[->, >=latex] ({360/\n * (\s - 1)+\margin}:\radius)
    arc ({360/\n * (\s - 1)+\margin}:{360/\n * (\s)-\margin}:\radius);
}
\end{tikzpicture}
EOF

Lua 类型参考

本节介绍 Lua 筛选器可用的对象类型。请参阅 pandoc 模块获取创建这些对象的函数。

共享属性

`clone`

clone ()

此处列出的类型的实例（除只读对象外）都可以通过 clone() 方法进行克隆。

用法

local emph = pandoc.Emph {pandoc.Str 'important'}
local cloned_emph = emph:clone()  -- note the colon

Pandoc

Pandoc 文档

此类型的值可以使用 pandoc.Pandoc 构造函数创建。Pandoc 值在 Lua 中相等当且仅当它们在 Haskell 中相等。

blocks: 文档内容（Blocks）
meta: 文档元信息（Meta 对象）

walk

walk(self, lua_filter)

将 Lua 筛选器应用于 Pandoc 元素。就像对于整个文档的筛选器一样，可以通过设置筛选器的 traverse 字段来控制遍历元素的顺序；请参阅遍历顺序部分。返回一个（深度）复制品，该复制品已应用筛选器：原始元素保持不变。

参数

self: 元素（Pandoc）
lua_filter: 筛选器函数映射（表）

结果

已筛选的文档（Pandoc）

用法

-- returns `pandoc.Pandoc{pandoc.Para{pandoc.Str 'Bye'}}`
return pandoc.Pandoc{pandoc.Para('Hi')}:walk {
  Str = function (_) return 'Bye' end,
}

MetaValue

文档元信息项。这不是一个单独的类型，而是描述了一组可在需要 MetaValue 的地方使用的类型。这些类型对应于以下 Haskell 类型构造函数：

boolean → MetaBool
string 或 number → MetaString
Inlines → MetaInlines
Blocks → MetaBlocks
List/integer 索引表 → MetaList
string 索引表 → MetaMap

相应的构造函数 pandoc.MetaBool、pandoc.MetaString、pandoc.MetaInlines、pandoc.MetaBlocks、pandoc.MetaList 和 pandoc.MetaMap 可用于确保值按预期方式处理。例如，一个空表通常被视为 MetaMap，但可以通过调用 pandoc.MetaList{} 来使其成为一个空的 MetaList。然而，通过使用泛型函数如 pandoc.List、pandoc.Inlines 或 pandoc.Blocks，也可以达到同样的效果。

使用函数 pandoc.utils.type 获取元数据值的类型。

Block

块值在 Lua 中相等当且仅当它们在 Haskell 中相等。

常用方法

walk

walk(self, lua_filter)

将 Lua 筛选器应用于块元素。就像对于整个文档的筛选器一样，可以通过设置筛选器的 traverse 字段来控制遍历元素的顺序；请参阅遍历顺序部分。返回一个（深度）复制品，该复制品已应用筛选器：原始元素保持不变。

请注意，筛选器应用于子树，但不应用于 self 块元素。其理由是，否则该元素可能会被筛选器删除，或被多个块元素替换，这可能导致可能意外的结果。

参数

self: 元素（Block）
lua_filter: 筛选器函数映射（表）

结果

已筛选的块（Block）

用法

-- returns `pandoc.Para{pandoc.Str 'Bye'}`
return pandoc.Para('Hi'):walk {
  Str = function (_) return 'Bye' end,
}

BlockQuote

块引用元素。

此类型的值可以使用 pandoc.BlockQuote 构造函数创建。

字段

content: 块内容（Blocks）
tag, t: 字面值 BlockQuote (字符串)

BulletList

项目符号列表。

此类型的值可以使用 pandoc.BulletList 构造函数创建。

字段

content: 列表项（List of items，即 List of Blocks）
tag, t: 字面值 BulletList (字符串)

CodeBlock

代码块。

此类型的值可以使用 pandoc.CodeBlock 构造函数创建。

字段

text: 代码字符串 (字符串)
attr: 元素属性（Attr）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面值 CodeBlock (字符串)

DefinitionList

定义列表，包含术语及其解释。

此类型的值可以使用 pandoc.DefinitionList 构造函数创建。

字段

content: 列表项
tag, t: 字面值 DefinitionList (字符串)

Div

带有属性的通用块容器。

此类型的值可以使用 pandoc.Div 构造函数创建。

字段

content: 块内容（Blocks）
attr: 元素属性（Attr）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面值 Div (字符串)

Figure

带有标题和任意块内容的图形。

此类型的值可以使用 pandoc.Figure 构造函数创建。

字段

content: 块内容（Blocks）
caption: 图形标题（Caption）
attr: 元素属性（Attr）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面值 Figure (字符串)

Header

创建标题元素。

此类型的值可以使用 pandoc.Header 构造函数创建。

字段

level: 标题级别 (整数)
content: 内联内容（Inlines）
attr: 元素属性（Attr）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面值 Header (字符串)

HorizontalRule

水平线。

此类型的值可以使用 pandoc.HorizontalRule 构造函数创建。

字段

tag, t: 字面值 HorizontalRule (字符串)

LineBlock

行块，即一行行的列表，每行之间由换行符分隔。

此类型的值可以使用 pandoc.LineBlock 构造函数创建。

字段

content: 内联内容（List of lines，即 List of Inlines）
tag, t: 字面值 LineBlock (字符串)

OrderedList

有序列表。

此类型的值可以使用 pandoc.OrderedList 构造函数创建。

字段

content: 列表项（List of items，即 List of Blocks）
listAttributes: 列表参数（ListAttributes）
start: listAttributes.start 的别名 (整数)
style: listAttributes.style 的别名 (字符串)
delimiter: listAttributes.delimiter 的别名 (字符串)
tag, t: 字面值 OrderedList (字符串)

Para

段落。

此类型的值可以使用 pandoc.Para 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面值 Para (字符串)

Plain

纯文本，不是段落。

此类型的值可以使用 pandoc.Plain 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面值 Plain (字符串)

RawBlock

指定格式的原始内容。

此类型的值可以使用 pandoc.RawBlock 构造函数创建。

字段

format: 内容的格式 (字符串)
text: 原始内容 (字符串)
tag, t: 字面值 RawBlock (字符串)

Table

表。

此类值可以使用 pandoc.Table 构造函数创建。

字段

attr: 表属性（Attr）
caption: 表标题（Caption）
列规格: 列规范，即对齐和宽度（List of ColSpecs）
表头: 表头（TableHead）
表体: 表体（List of TableBodys）
表脚: 表脚（TableFoot）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面量 Table（字符串）

一个表单元格是一个块的列表。

对齐方式 是一个字符串值，指示表列的水平对齐方式。AlignLeft、AlignRight 和 AlignCenter 分别使单元格内容左对齐、右对齐和居中对齐。默认对齐方式是 AlignDefault（通常等同于居中）。

块

块元素的列表，具有与通用列表相同的List方法。在用户脚本中通常不需要创建此类型的值，因为在需要此类型值的任何地方，pandoc 都可以将其他类型转换为块。

块（或块状）值的块列表（Block）被直接使用；
单个内联值（Inlines）被包装成一个Plain元素；
字符串值通过将字符串拆分成单词（请参阅 Inlines），然后将结果包装成一个 Plain 单例来转换为内联值（Inlines）。

方法

Blocks 类型的列表共享通用列表中的所有可用方法，请参阅 pandoc.List 模块。

此外，以下方法可用于 Blocks 值

walk

walk(self, lua_filter)

将 Lua 过滤器应用于 Blocks 列表。与完整文档过滤器一样，元素遍历顺序可以通过设置过滤器的 traverse 字段来控制；请参阅遍历顺序部分。返回一个已应用过滤器的（深层）副本：原始列表保持不变。

参数

self: 列表（Blocks）
lua_filter: 筛选器函数映射（表）

结果

过滤后的列表（Blocks）

用法

-- returns `pandoc.Blocks{pandoc.Para('Salve!')}`
return pandoc.Blocks{pandoc.Plain('Salve!)}:walk {
  Plain = function (p) return pandoc.Para(p.content) end,
}

内联

在 Lua 中，内联值当且仅当它们在 Haskell 中相等时才相等。

通用方法

walk

walk(self, lua_filter)

将 Lua 过滤器应用于内联元素。与完整文档过滤器一样，元素遍历顺序可以通过设置过滤器的 traverse 字段来控制；请参阅遍历顺序部分。返回一个已应用过滤器的（深层）副本：原始列表保持不变。

注意，过滤器应用于子树，但不应用于 self 内联元素。其原理是，否则该元素可能被过滤器删除，或被多个内联元素替换，这可能导致意外的结果。

参数

self: 元素（Inline）
lua_filter: 筛选器函数映射（表）

结果

过滤后的内联元素（Inline）

用法

-- returns `pandoc.SmallCaps('SPQR)`
return pandoc.SmallCaps('spqr'):walk {
  Str = function (s) return string.upper(s.text) end,
}

引用

引用。

此类值可以使用 pandoc.Cite 构造函数创建。

字段

content: （Inlines）
引用: 引用条目（List of Citations）
tag, t: 字面量 Cite（字符串）

代码

行内代码

此类值可以使用 pandoc.Code 构造函数创建。

字段

text: 代码字符串 (字符串)
attr: 属性（Attr）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面量 Code（字符串）

强调

强调的文本

此类值可以使用 pandoc.Emph 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面量 Emph（字符串）

图像

图像：alt 文本（内联列表），目标

此类值可以使用 pandoc.Image 构造函数创建。

字段

caption: 用于描述图像的文本（Inlines）
src: 图像文件的路径（字符串）
标题: 简短的图像描述（字符串）
attr: 属性（Attr）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面量 Image（字符串）

换行

硬换行

此类值可以使用 pandoc.LineBreak 构造函数创建。

字段

tag, t: 字面量 LineBreak（字符串）

链接

超链接：alt 文本（内联列表），目标

此类值可以使用 pandoc.Link 构造函数创建。

字段

attr: 属性（Attr）
content: 此链接的文本（Inlines）
目标: 链接目标（字符串）
标题: 简短的链接描述
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面量 Link（字符串）

数学

TeX 数学（字面量）

此类值可以使用 pandoc.Math 构造函数创建。

字段

数学类型: 指定数学内容是显示为行内（InlineMath）还是另起一行（DisplayMath）（字符串）
text: 数学内容（字符串）
tag, t: 字面量 Math（字符串）

注释

脚注或尾注

此类值可以使用 pandoc.Note 构造函数创建。

字段

content: （Blocks）
tag, t: 字面量 Note（字符串）

引用

引用的文本

此类值可以使用 pandoc.Quoted 构造函数创建。

字段

引用类型: 要使用的引号类型；SingleQuote 或 DoubleQuote（字符串）
content: 引用的文本（Inlines）
tag, t: 字面量 Quoted（字符串）

原始行内

此类值可以使用 pandoc.RawInline 构造函数创建。

字段

format: 内容的格式（字符串）
text: 原始内容 (字符串)
tag, t: 字面量 RawInline（字符串）

小型大写字母

小型大写字母文本

此类值可以使用 pandoc.SmallCaps 构造函数创建。

字段

content: （Inlines）
tag, t: 字面量 SmallCaps（字符串）

软换行

此类值可以使用 pandoc.SoftBreak 构造函数创建。

字段

tag, t: 字面量 SoftBreak（字符串）

空格

词间空格

此类值可以使用 pandoc.Space 构造函数创建。

字段

tag, t: 字面量 Space（字符串）

跨度

带属性的通用行内容器

此类值可以使用 pandoc.Span 构造函数创建。

字段

attr: 属性（Attr）
content: 包装的内容（Inlines）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）
tag, t: 字面量 Span（字符串）

字符串

文本

此类值可以使用 pandoc.Str 构造函数创建。

字段

text: 内容（字符串）
tag, t: 字面量 Str（字符串）

删除线

删除线文本

此类值可以使用 pandoc.Strikeout 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面量 Strikeout（字符串）

粗体

粗体强调文本

此类值可以使用 pandoc.Strong 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面量 Strong（字符串）

下标

下标文本

此类值可以使用 pandoc.Subscript 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面量 Subscript（字符串）

上标

上标文本

此类值可以使用 pandoc.Superscript 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面量 Superscript（字符串）

下划线

带下划线文本

此类值可以使用 pandoc.Underline 构造函数创建。

字段

content: 内联内容（Inlines）
tag, t: 字面量 Underline（字符串）

内联

内联元素的列表，具有与通用列表相同的List方法。在用户脚本中通常不需要创建此类型的值，因为在需要此类型值的任何地方，pandoc 都可以将其他类型转换为内联。

内联（或类似内联）值的列表（Inline）被直接使用；
单个内联值（Inline）被转换为仅包含该元素的列表；
字符串值被拆分成单词，将换行符转换为SoftBreak元素，将其他空白字符转换为Spaces。

方法

Inlines 类型的列表共享通用列表中的所有可用方法，请参阅 pandoc.List 模块。

此外，以下方法可用于 Inlines 值

walk

walk(self, lua_filter)

将 Lua 过滤器应用于 Inlines 列表。与完整文档过滤器一样，元素处理顺序为 Inline → Inlines → Block → Blocks。过滤器应用于所有列表项以及列表本身。返回一个已应用过滤器的（深层）副本：原始列表保持不变。

参数

self: 列表（Inlines）
lua_filter: 筛选器函数映射（表）

结果

过滤后的列表（Inlines）

用法

-- returns `pandoc.Inlines{pandoc.SmallCaps('SPQR')}`
return pandoc.Inlines{pandoc.Emph('spqr')}:walk {
  Str = function (s) return string.upper(s.text) end,
  Emph = function (e) return pandoc.SmallCaps(e.content) end,
}

元素组件

属性

一组元素属性。此类值可以使用 pandoc.Attr 构造函数创建。为了方便起见，如果属性是元素的一部分，通常不需要直接构造该值，只需传递一个类似 HTML 的表即可。例如，要创建一个标识符为“text”、类为“a”和“b”的 span，可以这样写：

local span = pandoc.Span('text', {id = 'text', class = 'a b'})

在使用 attr 设置器时，这同样有效

local span = pandoc.Span 'text'
span.attr = {id = 'text', class = 'a b', other_attribute = '1'}

在 Lua 中，Attr 值当且仅当它们在 Haskell 中相等时才相等。

字段

identifier: 元素标识符（字符串）
classes: 元素类（List of strings）
attributes: 键/值对集合（Attributes）

属性

键/值对列表。可以使用键作为列表表的索引来访问值。

在 Lua 中，Attributes 值当且仅当它们在 Haskell 中相等时才相等。

标题

表的标题，带有一个可选的短标题。

字段

长: 长标题（Blocks）
短: 短标题（Inlines）

单元格

一个表单元格。

字段

attr: 单元格属性
对齐方式: 单个单元格对齐方式（Alignment）。
内容: 单元格内容（Blocks）。
列跨度: 单元格跨越的列数；单元格的宽度（以列为单位）（整数）。
行跨度: 单元格跨越的行数；单元格的高度（以行为单位）（整数）。
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）

引用

单个引用条目

此类值可以使用 pandoc.Citation 构造函数创建。

在 Lua 中，Citation 值当且仅当它们在 Haskell 中相等时才相等。

字段

ID: 引用标识符，例如 bibtex 键（字符串）
模式: 引用模式，AuthorInText、SuppressAuthor 或 NormalCitation 之一（字符串）
前缀: 引用前缀（Inlines）
后缀: 引用后缀（Inlines）
注号: 注号（整数）
哈希: 哈希（整数）

列规格

单个表列的列对齐和宽度规范。

这是一个对，即一个普通表，具有以下组件：

单元格对齐方式（Alignment）。
表列宽度，表示为页面宽度的分数（数字）。

列表属性

此类值可以使用 pandoc.ListAttributes 构造函数创建。

字段

start: 第一个列表项的编号（整数）
style: 用于列表编号的样式；可能的值为 DefaultStyle、Example、Decimal、LowerRoman、UpperRoman、LowerAlpha 和 UpperAlpha（字符串）
delimiter: 列表编号的定界符；DefaultDelim、Period、OneParen 和 TwoParens 之一（字符串）

行

一个表行。

字段

attr: 元素属性（Attr）
单元格: 表单元格列表（List of Cells）

表体

表的表体，带有中间表头和指定的行标题列数。

字段

attr: 表体属性（Attr）
表体: 表体行（List of Rows）
表头: 中间表头（List of Rows）
行标题列数: TableBody 中每行的行标题所占的列数。行主体占据剩余的列。

表脚

表的表脚。

字段

attr: 元素属性（Attr）
行: 行列表（List of Rows）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）

表头

表的表头。

字段

attr: 元素属性（Attr）
行: 行列表（List of Rows）
identifier: attr.identifier 的别名 (字符串)
classes: attr.classes 的别名（List of strings）
attributes: attr.attributes 的别名（Attributes）

ReaderOptions

Pandoc 读取器选项

字段

缩写: 已知缩写的集合（字符串集合）
列数: 终端中的列数（整数）
默认图像扩展名: 图像的默认扩展名（字符串）
扩展: 语法扩展位字段的字符串表示（字符串序列）
缩进代码类: 缩进代码块的默认类（字符串列表）
独立: 输入是否是带有标头的独立文档（布尔值）
条带注释: HTML 注释被剥离而不是被解析为原始 HTML（布尔值）
制表符停止: 制表符的宽度（即等效空格数）（整数）
跟踪更改: docx 的跟踪更改设置；accept-changes、reject-changes 和 all-changes 之一（字符串）

WriterOptions

Pandoc 编写器选项

字段

块模板: 用于生成分块 HTML 文件名的模板（字符串）
引用方法: 如何打印引用——citeproc、natbib 或 biblatex 之一（字符串）
列数: 一行中的字符（用于文本换行）（整数）
dpi: 像素到英寸/厘米转换的 DPI（整数）
电子邮件混淆: 如何混淆电子邮件——none、references 或 javascript 之一（字符串）
epub 章级别: 章的标题级别，即文档如何拆分为单独的文件（整数）
epub 字体: 要嵌入的字体路径（字符串序列）
epub 元数据: 要包含在 EPUB 中的元数据（字符串|nil）
epub 子目录: OCF 中 epub 的子目录（字符串）
扩展: 可用的 Markdown 扩展（字符串序列）
高亮样式: 用于高亮的样式；有关示例结构，请参阅 pandoc --print-highlight-style=... 的输出。值为 nil 表示不使用高亮。（表|nil）
HTML 数学方法: 如何在 HTML 中打印数学；plain、mathjax、mathml、webtex、katex、gladtex 或带有 method 和 url 键的表之一。（字符串|表）
HTML 引用标签: 在 HTML 中对引用使用 <q> 标签（布尔值）
标识符前缀: HTML 和 Markdown 中脚注标记的节和注释 ID 的前缀（字符串）
增量: 如果列表应该是增量的，则为 true（布尔值）
列表: 为代码使用 listings 包（布尔值）
数字偏移量: 节、子节等开始编号（整数序列）
编号章节: 在 LaTeX 中编号章节（布尔值）
优先 ASCII: 尽可能优先使用字符的 ASCII 表示（布尔值）
参考文档: 引用的参考文档路径（字符串|nil）
参考链接: 在编写 markdown、rst 时使用参考链接（布尔值）
参考位置: 编写 markdown 时脚注和引用的位置；end-of-block、end-of-section、end-of-document 之一。设置此值时，可以省略通用前缀。（字符串）
节 div: 在 HTML 中将节放在 div 标签中（布尔值）
setext 标题: 在 markdown 中为级别 1-2 使用 setext 标题（布尔值）
幻灯片级别: 强制设置幻灯片标题级别（整数|nil）
制表符停止: 制表符停止，用于在空格和制表符之间转换（整数）
目录: 包含目录（布尔值）
模板: 使用的模板（Template|nil）
TOC 深度: TOC 中包含的级别数（整数）
顶层分区: 顶层分区的类型；top-level-part、top-level-chapter、top-level-section 或 top-level-default 之一。设置此值时，可以省略 top-level 前缀。（字符串）
变量: 在模板中设置的变量；字符串索引表（表）
换行文本: 换行文本的选项；wrap-auto、wrap-none 或 wrap-preserve 之一。设置此值时，可以省略 wrap- 前缀。（字符串）

CommonState

pandoc 用于收集信息并使其可供读取器和编写器使用的状态。

字段

输入文件: 命令行中的输入文件列表（List of strings）
输出文件: 命令行中的输出文件（字符串或 nil）
日志: 日志消息列表，顺序相反（List of LogMessages）
请求头: 要为 HTTP 请求添加的头；以头名称作为键，头内容作为值的表（表）
资源路径: 用于搜索资源（如包含的图像）的路径（List of strings）
源 URL: 第一个源文件的绝对 URL 或目录（字符串或 nil）
用户数据目录: 用于搜索数据文件的目录（字符串或 nil）
跟踪: 是否发出跟踪消息（布尔值）
详细程度: 详细程度级别；INFO、WARNING、ERROR 之一（字符串）

Doc

可重排的纯文本文档。Doc 值可以渲染并重排以适应给定的列宽。

pandoc.layout 模块可用于创建和修改 Doc 值。该模块中以 Doc 值作为第一个参数的所有函数也都可以作为 Doc 方法使用。例如，(pandoc.layout.literal 'text'):render()。

如果将字符串传递给期望 Doc 的函数，则该字符串将被视为字面值。也就是说，以下两行是等效的：

test = pandoc.layout.quotes(pandoc.layout.literal 'this')
test = pandoc.layout.quotes('this')

运算符

`..`

连接两个 Doc 元素。

`+`

连接两个 Doc，并在它们之间插入一个可重排的空格。

`/`

如果 a 和 b 是 Doc 元素，则 a / b 将 a 放在 b 上方。

`//`

如果 a 和 b 是 Doc 元素，则 a // b 将 a 放在 b 上方，并在它们之间插入一个空行。

列表

列表是任何具有整数索引的 Lua 表。索引从一开始，所以如果 alist = {'value'}，则 alist[1] == 'value'。

列表，当它们是元素的一部分，或在编组过程中生成时，为了方便起见，会被实例化为 pandoc.List 类型。pandoc.List 类型定义在 pandoc.List 模块中。请参阅那里了解可用的方法。

此类值可以使用 pandoc.List 构造函数创建，将普通的 Lua 表转换为 List。

LogMessage

一个 pandoc 日志消息。对象没有字段，但可以通过 tostring 转换为字符串。

SimpleTable

简单表是一种表结构，它类似于旧的（pandoc 2.10 之前）Table 类型。可以通过 pandoc.utils.to_simple_table 和 pandoc.utils.from_simple_table 函数与 Tables 进行双向转换。还可以使用 pandoc.SimpleTable 构造函数直接创建此类型的实例。

字段

caption: 内联
对齐方式: 列对齐方式（List of Alignments）
宽度: 列宽度；一个（List of numbers）
表头: 表头行（List of simple cells，即 List of Blocks）
行: 表行（List of rows，其中行是简单单元格的列表，即 List of Blocks）

Template

包含已编译模板的不透明类型。

Version

版本对象。它表示一个软件版本，如“2.7.3”。该对象表现得像一个数字索引表，即，如果 version 表示版本 2.7.3，则：

version[1] == 2
version[2] == 7
version[3] == 3
#version == 3   -- length

比较是逐个元素进行的，即：

Version '1.12' > Version '1.9'

此类值可以使用 pandoc.types.Version 构造函数创建。

`must_be_at_least`

must_be_at_least(actual, expected [, error_message])

如果实际版本比预期版本旧，则引发错误消息；如果 actual 等于或更新于预期版本，则不执行任何操作。

参数

实际: 实际版本说明符（Version）
预期: 最低预期版本（Version）
错误消息: 可选的错误消息模板。该字符串用作格式字符串，并将预期版本和实际版本作为参数。默认为 "expected version %s or newer, got %s"。

用法

PANDOC_VERSION:must_be_at_least '2.7.3'
PANDOC_API_VERSION:must_be_at_least(
  '1.17.4',
  'pandoc-types is too old: expected version %s, got %s'
)

Chunk

文档的一部分；通常每个块都写入一个单独的文件。

字段

标题: 标题文本（Inlines）
ID: 标识符（字符串）
level: 块中的最高级别标题（整数）
编号: 块编号（整数）
节编号: 分层节号（字符串）
路径: 此块的目标文件路径（字符串）
上: 指向包含节的链接（如果存在）（Chunk|nil）
前: 指向前一个节的链接（如果存在）（Chunk|nil）
下: 指向下一个节的链接（如果存在）（Chunk|nil）
未列出: 即使该块没有节号，是否也应在 TOC 中列出该块中的节。（布尔值）
内容: 块的内容（Blocks）

ChunkedDoc

分为块（Chunks）的 Pandoc 文档。

字段 toc 中的目录信息是玫瑰树结构，表示为一个列表。节点项始终放在索引 0 处；子条目构成列表的其余部分。每个节点项包含字段 title（Inlines）、number（字符串|nil）、id（字符串）、path（字符串）和 level（整数）。

字段

块: 构成文档的块列表（Chunks 的列表）。
meta: 文档的元数据（Meta）
TOC: 目录信息（表）

模块 pandoc

用于 pandoc 脚本的字段和函数；包括文档树元素的构造函数、以给定格式解析文本的函数以及过滤和修改子树的函数。

字段

readers

pandoc 可以解析的格式集合。此表中的所有键都可作为 pandoc.read 中的 format 值使用。（表）

writers

pandoc 可以生成的格式集合。此表中的所有键都可作为 pandoc.write 中的 format 值使用。（表）

函数

Pandoc

Pandoc (blocks[, meta])

参数

blocks: 文档内容（Blocks）
meta: 文档元数据（Meta）

新的 Pandoc 文档（Pandoc）

MetaBlocks

MetaBlocks (content)

创建一个值以用作元数据中的 MetaBlocks 值；通过 pandoc.Blocks 创建输入列表的副本，并丢弃所有非列表键。

参数

content: 块内容（Blocks）

块元素列表（Blocks）

MetaBool

MetaBool (bool)

参数

布尔值: true 或 false（布尔值）

输入，未更改（布尔值）

MetaInlines

MetaInlines (inlines)

创建一个值以用作元数据中的 MetaInlines 值；通过 pandoc.Inlines 创建输入列表的副本，并丢弃所有非列表键。

参数

内联: 内联元素（Inlines）

内联元素列表（Inlines）

MetaList

MetaList (values)

创建一个值以用作元数据中的 MetaList；通过 pandoc.List 创建输入列表的副本，并丢弃所有非列表键。

参数

值: 值，或值列表（MetaValue|{MetaValue,...}）

元值列表（List）

MetaMap

MetaMap (key_value_map)

创建一个值以用作元数据中的 MetaMap；创建输入表的副本，仅保留键为字符串的键值对，并丢弃所有其他键。

参数

键值映射: 字符串索引的元值映射（表）

元值映射（表）

MetaString

MetaString (s)

创建一个值以用作元数据中的 MetaString；这是布尔值的标识函数，仅为完整性而存在。

参数

S: 字符串值（字符串）

未更改的输入（字符串）

BlockQuote

BlockQuote (content)

创建块引用元素

参数

content: 块内容（Blocks）

BlockQuote 元素（Block）

BulletList

BulletList (items)

创建项目符号列表。

参数

项目: 列表项（{Blocks,...}）

BulletList 元素（Block）

CodeBlock

CodeBlock (text[, attr])

创建代码块元素。

参数

text: 代码字符串 (字符串)
attr: 元素属性（Attr）

CodeBlock 元素（Block）

DefinitionList

DefinitionList (content)

创建定义列表，包含术语及其解释。

参数

content: 定义项（{{Inlines, {Blocks,...}},...}）

DefinitionList 元素（Block）

Div

Div (content[, attr])

创建 div 元素

参数

content: 块内容（Blocks）
attr: 元素属性（Attr）

Div 元素（Block）

Figure

Figure (content[, caption[, attr]])

创建 Figure 元素。

参数

content: 图形块内容（Blocks）
caption: 图形标题（Caption）
attr: 元素属性（Attr）

Figure 对象（Block）

HorizontalRule

HorizontalRule ()

创建水平规则。

HorizontalRule 元素（Block）

LineBlock

LineBlock (content)

创建行块元素。

参数

content: 行（{Inlines,...}）

LineBlock 元素（Block）

OrderedList

OrderedList (items[, listAttributes])

创建有序列表。

参数

项目: 列表项（{Blocks,...}）
listAttributes: 列表参数（ListAttributes）

OrderedList 元素（Block）

Para

Para (content)

创建段落元素。

参数

content: 内联内容（Inlines）

Para 元素（Block）

Plain

Plain (content)

创建普通元素。

参数

content: 内联内容（Inlines）

Plain 元素（Block）

RawBlock

RawBlock (format, text)

创建指定格式的原始内容块。

参数

format: 内容的格式 (字符串)
text: 原始内容 (字符串)

RawBlock 元素（Block）

Table

Table (caption, colspecs, head, bodies, foot[, attr])

创建表元素。

参数

caption: 表标题（Caption）
列规格: 列对齐方式和宽度（{ColSpec,...}）
表头: 表头（TableHead）
表体: 表体（{TableBody,...}）
表脚: 表脚（TableFoot）
attr: 元素属性（Attr）

Table 元素（Block）

Blocks

Blocks (block_like_elements)

创建 Blocks 列表。

参数

类块元素: 可以被视为 Block 值的列表，或单个此类值。（Blocks）

块元素列表（Blocks）

Cite

Cite (Inlines, citations)

创建 Cite 行内元素

参数

内联: 占位符内容（content）
引用: 引用列表（{Citation,...}）

cite 元素（Inline）

Code

Code (code[, attr])

创建 Code 行内元素

参数

代码: 代码字符串 (字符串)
attr: 附加属性（Attr）

代码元素（Inline）

Emph

Emph (content)

创建表示强调文本的行内元素。

参数

content: 内联内容（Inlines）

新对象（Inline）

Image

Image (caption, src[, title[, attr]])

创建 Image 元素

参数

caption: 用于描述图像的文本（Inlines）
src: 图像文件的路径（字符串）
标题: 简短的图像描述（字符串）
attr: 图像属性（Attr）

Image 元素（Inline）

LineBreak

LineBreak ()

创建 LineBreak 行内元素

换行（Inline）

Link

Link (content, target[, title[, attr]])

创建链接行内元素，通常是超链接。

参数

content: 此链接的文本（Inlines）
目标: 链接目标（字符串）
标题: 简短的链接描述（字符串）
attr: 链接属性（Attr）

链接元素（Inline）

Math

Math (mathtype, text)

创建 Math 元素，可以是行内或显示的。

参数

数学类型: 渲染说明符（MathType）
text: 数学内容（字符串）

数学元素（Inline）

Note

Note (content)

创建 Note 行内元素

参数

content: 脚注块内容（Blocks）

注释（Inline）

Quoted

Quoted (quotetype, content)

给定引用类型和引用的内容，创建 Quoted 行内元素。

参数

引用类型: 引用类型（QuoteType）
content: 引用的内联（Inlines）

引用的元素（Inline）

RawInline

RawInline (format, text)

创建原始内联元素

参数

format: 内容的格式 (字符串)
text: content (string)

原始内联元素 (Inline)

SmallCaps

SmallCaps (content)

创建以小型大写字母渲染的文本

参数

content: 内联内容（Inlines）

新对象（Inline）

SoftBreak

SoftBreak ()

创建一个 SoftBreak 内联元素。

软换行 (Inline)

Space

Space ()

创建一个 Space 内联元素

新空格 (Inline)

Span

Span (content[, attr])

创建一个 Span 内联元素

参数

content: 内联内容（Inlines）
attr: 附加属性（Attr）

Span 对象 (Inline)

Str

Str (text)

创建一个 Str 内联元素

参数

text: (string)

Str 对象 (Inline)

Strikeout

Strikeout (content)

创建带删除线的文本。

参数

content: 内联内容（Inlines）

新对象（Inline）

Strong

Strong (content)

创建一个 Strong 元素，其文本通常以粗体显示。

参数

content: 内联内容（Inlines）

新对象（Inline）

Subscript

Subscript (content)

创建一个 Subscript 内联元素

参数

content: 内联内容（Inlines）

新对象（Inline）

Superscript

Superscript (content)

创建一个 Superscript 内联元素

参数

content: 内联内容（Inlines）

新对象（Inline）

Underline

Underline (content)

创建一个 Underline 内联元素

参数

content: 内联内容（Inlines）

新对象（Inline）

Inlines

Inlines (inline_like_elements)

将参数转换为 Inlines 列表

复制列表中的 Inline 元素到新列表中；列表中的任何字符串 s 都被视为 pandoc.Str(s)；
将单个 Inline 转换为单元素列表；
将字符串拆分为 Str 包装的单词，将单词间的空格视为 Space 或 SoftBreak。

参数

inline_like_elements: 列表，其中每个元素都可以被视为 Inline 值，或者只是一个这样的值。(Inlines)

内联元素列表 (Inlines)

Attr

Attr ([identifier[, classes[, attributes]]])

创建一个新的属性集

参数

identifier: 元素标识符 (string|table|Attr)
classes: 元素类 ({string,...})
attributes: 包含字符串键和值的表 (table|AttributeList)

新的 Attr 对象 (Attr)

Caption

Caption ([long[, short]])

创建一个新的 Caption 对象。

参数

长: 完整标题 (Blocks)
短: 简短摘要标题 (Inlines)

新的 Caption 对象 (Caption)

since: 3.6.1

Cell

Cell (blocks[, align[, rowspan[, colspan[, attr]]]])

创建一个新的表格单元格。

参数

blocks: 单元格内容 (Blocks)
align: 文本对齐方式；默认为 AlignDefault (Alignment)
rowspan: 单元格占据的行数；默认为 1 (integer)
colspan: 单元格占据的列数；默认为 1 (integer)
attr: 单元格属性 (Attr)

新的 Cell 对象 (Cell)

AttributeList

AttributeList (attribs)

参数

attribs: 属性列表 (table|AttributeList)

新的 AttributeList 对象 (AttributeList)

Citation

Citation (id, mode[, prefix[, suffix[, note_num[, hash]]]])

创建一个单独的引用。

参数

ID: 引用 ID (例如 BibTeX 键) (string)
模式: 引用渲染模式 (CitationMode)
前缀: （Inlines）
后缀: （Inlines）
注号: 注释编号 (integer)
哈希: 哈希编号 (integer)

新的引用对象 (Citation)

ListAttributes

ListAttributes ([start[, style[, delimiter]]])

创建一个新的 ListAttributes 对象。

参数

start: 第一个列表项的编号 (integer)
style: 列表编号使用的样式 (string)
delimiter: 列表编号的定界符 (string)

新的 ListAttributes 对象 (ListAttributes)

Row

Row ([cells[, attr]])

创建表格行。

参数

单元格: 此行中的表格单元格列表 ({Cell,...})
attr: 行属性 (Attr)

新的 Row 对象 (Row)

TableFoot

TableFoot ([rows[, attr]])

创建表脚注。

参数

行: 表格行列表 ({Row,...})
attr: 表脚注属性 (Attr)

新的 TableFoot 对象 (TableFoot)

TableHead

TableHead ([rows[, attr]])

创建表头。

参数

行: 表格行列表 ({Row,...})
attr: 表头属性 (Attr)

新的 TableHead 对象 (TableHead)

SimpleTable

SimpleTable (caption, align, widths, header, rows)

用法

local caption = "Overview"
local aligns = {pandoc.AlignDefault, pandoc.AlignDefault}
local widths = {0, 0} -- let pandoc determine col widths
local headers = {{pandoc.Plain({pandoc.Str "Language"})},
                 {pandoc.Plain({pandoc.Str "Typing"})}}
local rows = {
  {{pandoc.Plain "Haskell"}, {pandoc.Plain "static"}},
  {{pandoc.Plain "Lua"}, {pandoc.Plain "Dynamic"}},
}
simple_table = pandoc.SimpleTable(
  caption,
  aligns,
  widths,
  headers,
  rows
)

参数

caption: 表格标题 (Inlines)
align: 列对齐方式 ({Alignment,...})
宽度: 相对列宽 ({number,...})
header: 表格标题行 ({Blocks,...})
行: 表格行 ({{Blocks,...},...})

新的 SimpleTable 对象 (SimpleTable)

常量

AuthorInText

作者姓名在文本中提及。

另请参阅: Citation

SuppressAuthor

作者姓名被隐藏。

另请参阅: Citation

NormalCitation

使用默认的引用样式。

另请参阅: Citation

DisplayMath

数学样式标识符，标记公式应显示为“display”样式，即单独一行。

另请参阅: Math

InlineMath

数学样式标识符，标记公式应显示为行内。

另请参阅: Math

SingleQuote

与 Quoted 一起使用的引用类型，表示字符串用单引号括起来。

另请参阅: Quoted

DoubleQuote

与 Quoted 一起使用的引用类型，表示字符串用双引号括起来。

另请参阅: Quoted

AlignLeft

表格单元格左对齐。

另请参阅: Table

AlignRight

表格单元格右对齐。

另请参阅: Table

AlignCenter

表格单元格内容居中。

另请参阅: Table

AlignDefault

表格单元格对齐方式不变。

另请参阅: Table

DefaultDelim

使用默认的列表编号定界符。

另请参阅: ListAttributes

Period

列表编号以句点定界。

另请参阅: ListAttributes

OneParen

列表编号以单个括号定界。

另请参阅: ListAttributes

TwoParens

列表编号以双括号定界。

另请参阅: ListAttributes

DefaultStyle

列表按默认样式编号

另请参阅: ListAttributes

示例

列表项按示例编号。

另请参阅: ListAttributes

Decimal

列表使用十进制整数编号。

另请参阅: ListAttributes

LowerRoman

列表使用小写罗马数字编号。

另请参阅: ListAttributes

UpperRoman

列表使用大写罗马数字编号

另请参阅: ListAttributes

LowerAlpha

列表使用小写字母编号。

另请参阅: ListAttributes

UpperAlpha

列表使用大写字母编号。

另请参阅: ListAttributes

sha1

pandoc.utils.sha1 的别名 (已弃用，请使用 pandoc.utils.sha1)。

其他构造函数

`ReaderOptions (opts)`

创建一个新的 ReaderOptions 值。

参数

opts: 可以是包含 ReaderOptions 对象部分属性的表，也可以是另一个 ReaderOptions 对象。对于所有未显式指定的属性，将使用手册中指定的默认值。如果表包含 ReaderOptions 对象中不存在的属性，则会引发错误。(ReaderOptions|table)

返回: 新的 ReaderOptions 对象

用法

-- copy of the reader options that were defined on the command line.
local cli_opts = pandoc.ReaderOptions(PANDOC_READER_OPTIONS)

-- default reader options, but columns set to 66.
local short_colums_opts = pandoc.ReaderOptions {columns = 66}

`WriterOptions (opts)`

创建一个新的 WriterOptions 值。

参数

opts: 可以是包含 WriterOptions 对象部分属性的表，也可以是另一个 WriterOptions 对象。对于所有未显式指定的属性，将使用手册中指定的默认值。如果表包含 WriterOptions 对象中不存在的属性，则会引发错误。(WriterOptions|table)

返回: 新的 WriterOptions 对象

用法

-- copy of the writer options that were defined on the command line.
local cli_opts = pandoc.WriterOptions(PANDOC_WRITER_OPTIONS)

-- default writer options, but DPI set to 300.
local short_colums_opts = pandoc.WriterOptions {dpi = 300}

辅助函数

`pipe (command, args, input)`

运行命令及其参数，传递一些输入，并返回输出。

参数

command: 要运行的程序；可执行文件将使用系统默认方法解析 (string)。
args: 要传递给程序的参数列表 (string 列表)。
input: 通过 stdin 管道输入到程序的数据 (string)。

命令的输出，即打印到 stdout 的数据 (string)

Raises

如果命令以非零错误码退出，则会抛出一个包含 command、error_code 和 output 键的表。

用法

local output = pandoc.pipe("sed", {"-e","s/a/b/"}, "abc")

`walk_block (element, filter)`

在块元素内应用过滤器，遍历其内容。返回一个已应用过滤器的 (深层) 副本：原始元素保持不变。

参数

element: 块元素
filter: 要在块元素内应用的 Lua 过滤器 (函数表)

返回: 转换后的块元素

`walk_inline (element, filter)`

在内联元素内应用过滤器，遍历其内容。返回一个已应用过滤器的 (深层) 副本：原始元素保持不变。

参数

element: 内联元素
filter: 要在内联元素内应用的 Lua 过滤器 (函数表)

返回: 转换后的内联元素

`read (markup[, format[, reader_options[, read_env]]])`

将给定字符串解析为 Pandoc 文档。

解析器在读取主输入文件时使用的相同环境运行；它对文件系统和媒体包具有完全访问权限。这意味着，如果文档指定要包含的文件，如 LaTeX、reStructuredText 和 Org 等格式中可能的那样，这些文件将包含在生成的文档中。任何媒体元素都会添加到从其他已解析输入文件中检索到的元素中。使用 read_env 参数可以修改此行为。

format 参数定义了要解析的格式风格。这可以是一个字符串，使用 + 和 - 来启用和禁用扩展，或者一个具有 format (string) 和 extensions (table) 字段的表。extensions 表可以是所有已启用扩展的列表，或者一个以扩展为键、其激活状态为值的表 (true 或 'enable' 来启用扩展，false 或 'disable' 来禁用它)。

注意: reader_options 中的 extensions 字段将被忽略，因为函数将始终使用通过 format 参数指定的格式扩展。

参数

markup: 要解析的标记 (string|Sources)
format: format 规范；默认为 "markdown"。有关此参数的完整说明，请参阅上面的描述。(string|table)
reader_options: 传递给读取器的选项；可以是 ReaderOptions 对象或具有 ReaderOptions 对象部分键值对的表；默认为手册中记录的默认值。(ReaderOptions|table)
read_env: 如果未提供值或值为 nil，则使用全局环境。传递文件名列表会导致读取器在沙箱中运行。给定文件从文件系统中读取，并通过伪文件系统提供给沙箱。该表还可以包含文件名到内容的映射，用于填充伪文件系统。

返回: pandoc 文档 (Pandoc)

用法

local org_markup = "/emphasis/"  -- Input to be read
local document = pandoc.read(org_markup, "org")
-- Get the first block of the document
local block = document.blocks[1]
-- The inline element in that block is an `Emph`
assert(block.content[1].t == "Emph")

`write (doc[, format[, writer_options]])`

将文档转换为指定的输出格式。

注意: writer_options 中的 extensions 字段将被忽略，因为函数将始终使用通过 format 参数指定的格式扩展。

参数

doc: 要转换的文档 (Pandoc)
format: format 规范；默认为 "html"。有关此参数的完整说明，请参阅 pandoc.read 的文档。(string|table)
writer_options: 传递给写入器的选项；可以是 WriterOptions 对象或具有 WriterOptions 对象部分键值对的表；默认为手册中记录的默认值。(WriterOptions|table)

返回: - 转换后的文档 (string)

用法

local doc = pandoc.Pandoc(
  {pandoc.Para {pandoc.Strong 'Tea'}}
)
local html = pandoc.write(doc, 'html')
assert(html == "<p><strong>Tea</strong></p>")

`write_classic (doc[, writer_options])`

运行经典的自定义 Lua 写入器，使用当前环境中定义的函数。

参数

doc: 要转换的文档 (Pandoc)
writer_options: 传递给写入器的选项；可以是 WriterOptions 对象或包含 WriterOptions 对象部分键值对的表；默认为手册中记录的默认值。(WriterOptions|table)

返回: - 转换后的文档 (string)

用法

-- Adding this function converts a classic writer into a
-- new-style custom writer.
function Writer (doc, opts)
  PANDOC_DOCUMENT = doc
  PANDOC_WRITER_OPTIONS = opts
  loadfile(PANDOC_SCRIPT_FILE)()
  return pandoc.write_classic(doc, opts)
end

模块 pandoc.cli

命令行选项和参数解析。

字段

default_options

默认的 CLI 选项，使用类似 JSON 的表示法。(table)

函数

parse_options

parse_options (args)

将命令行参数解析为 pandoc 选项。通常，此函数将用于独立的 pandoc Lua 脚本，从全局 arg 中获取参数列表。

参数

args: 命令行参数列表 ({string,...})

解析后的选项，使用其类似 JSON 的表示法。(table)

since: 3.0

repl

repl ([env])

启动一个读-求值-打印循环 (REPL)。该函数返回最后一个已计算输入的所有值。按 Ctrl-D 或 Ctrl-C 退出 REPL；按 F1 可获取所有按键绑定的列表。

REPL 在全局命名空间中启动，除非指定了 env 参数。在这种情况下，全局命名空间将被合并到给定的表中，并将结果用作 repl 的 _ENV 值。

具体来说，局部变量无法访问，除非它们通过 env 参数显式传递；例如：

function Pandoc (doc)
  -- start repl, allow to access the `doc` parameter
  -- in the repl
  return pandoc.cli.repl{ doc = doc }
end

注意: 在 Windows 上，该函数似乎会立即退出，而不会提示用户输入。

参数

env: 额外的环境；全局环境将被合并到此表中。(table)

最后一个已计算输入的返回值，或者如果最后一个输入导致错误则为空。

since: 3.1.2

模块 pandoc.utils

此模块公开 pandoc 的内部函数和实用函数。

函数

blocks_to_inlines

blocks_to_inlines (blocks[, sep])

将块列表压缩为内联列表。

用法

local blocks = {
  pandoc.Para{ pandoc.Str 'Paragraph1' },
  pandoc.Para{ pandoc.Emph 'Paragraph2' }
}
local inlines = pandoc.utils.blocks_to_inlines(blocks)
assert(
  inlines == pandoc.Inlines {
    pandoc.Str 'Paragraph1',
    pandoc.Linebreak(),
    pandoc.Emph{ pandoc.Str 'Paragraph2' }
  }
)

参数

blocks: 要展平的 Block 元素列表。(Blocks)
sep: 在两个连续块之间插入的 Inline 元素列表；默认为 {pandoc.LineBreak()}。(Inlines)

（Inlines）

since: 2.2.3

citeproc

citeproc (doc)

处理文件中的引用，将它们替换为渲染后的引用并添加参考文献。有关详细信息，请参阅手册中关于引用渲染的部分。

用法

-- Lua filter that behaves like `--citeproc`
function Pandoc (doc)
  return pandoc.utils.citeproc(doc)
end

参数

doc: 文档 (Pandoc)

处理后的文档 (Pandoc)

since: 2.19.1

equals

equals (element1, element2)

测试 AST 元素的相等性。Lua 中的元素被认为相等当且仅当反序列化得到的对象相等。

此函数已弃用。 请改用 Lua 的常规 == 相等运算符。

参数

element1: (any)
element2: (any)

两个对象是否表示同一元素 (boolean)

since: 2.5

from_simple_table

from_simple_table (simple_tbl)

从 SimpleTable 创建一个 Table 块元素。这对于处理 pandoc 2.10 版本之前的旧代码很有用。

用法

local simple = pandoc.SimpleTable(table)
-- modify, using pre pandoc 2.10 methods
simple.caption = pandoc.SmallCaps(simple.caption)
-- create normal table block again
table = pandoc.utils.from_simple_table(simple)

参数

simple_tbl: (SimpleTable)

表格块元素 (Block)

since: 2.11

make_sections

make_sections (number_sections, baselevel, blocks)

将 Block 元素列表转换为节。Div 将在每个 Header 处开始创建，并包含直到下一个同等级别的 Header 的内容。如果 number_sections 为 true，则每个 Header 将添加一个 number 属性，其中包含节编号。如果 base_level 非空，则将重新组织 Header 级别，以确保没有间隙，并且基础级别是指定的级别。

参数

编号章节: 节 Div 是否应包含一个额外的 number 属性，其中包含节编号。(boolean)
baselevel: 将顶层标题移至此级别 (integer|nil)
blocks: 要处理的块列表(Blocks)

带节的块(Blocks)

since: 2.8

normalize_date

normalize_date (date)

解析日期并尝试转换为“YYYY-MM-DD”格式。我们将年份限制在 1601-9999 的范围内 (ISO 8601 接受大于等于 1583，但 MS Word 只接受从 1601 年开始的日期)。如果转换失败，则返回 nil 而不是字符串。

参数

日期: 日期字符串 (string)

规范化日期，如果规范化失败则返回 nil。(string or nil)

since: 2.0.6

references

references (doc)

获取在元数据中以及通过外部参考文献定义的引用。只返回实际在文档中被引用的引用 (通过真实引用或 nocite)。URL 变量将被转换为链接。

用于表示引用值的结构对应于 CSL JSON 中使用的结构；返回值可用作 references 元数据，这是 pandoc 和 citeproc 在生成参考文献时使用的值之一。

用法

-- Include all cited references in document
function Pandoc (doc)
  doc.meta.references = pandoc.utils.references(doc)
  doc.meta.bibliography = nil
  return doc
end

参数

doc: 文档 (Pandoc)

引用列表。(table)

since: 2.17

run_json_filter

run_json_filter (doc, filter[, args])

通过 JSON 过滤器处理给定文档。

参数

doc: 要过滤的 Pandoc 文档 (Pandoc)
filter: 要运行的过滤器 (string)
args: 传递给过滤器的参数列表。默认为 {FORMAT}。({string,...})

已筛选的文档（Pandoc）

since: 2.1.1

run_lua_filter

run_lua_filter (doc, filter[, env])

通过 Lua 过滤器处理给定文档。

过滤器将在当前的 Lua 进程中运行。

参数

doc: 要过滤的 Pandoc 文档 (Pandoc)
filter: 要运行的过滤器的文件路径 (string)
env: 加载和运行过滤器的环境 (table)

已筛选的文档（Pandoc）

since: 3.2.1

sha1

sha1 (input)

计算给定字符串输入的 SHA1 哈希值。

参数

input: (string)

十六进制哈希值 (string)

since: 2.0.6

stringify

stringify (element)

将给定元素 (Pandoc、Meta、Block 或 Inline) 转换为没有格式的字符串。

参数

element: 某个 pandoc AST 元素 (AST element)

给定元素的纯字符串表示形式。(string)

since: 2.0.6

to_roman_numeral

to_roman_numeral (n)

将小于 4000 的整数转换为大写罗马数字。

用法

local to_roman_numeral = pandoc.utils.to_roman_numeral
local pandoc_birth_year = to_roman_numeral(2006)
-- pandoc_birth_year == 'MMVI'

参数

n: 小于 4000 的正整数 (integer)

罗马数字。(string)

since: 2.0.6

to_simple_table

to_simple_table (tbl)

将表转换为旧式/简单表。

用法

local simple = pandoc.utils.to_simple_table(table)
-- modify, using pre pandoc 2.10 methods
simple.caption = pandoc.SmallCaps(simple.caption)
-- create normal table block again
table = pandoc.utils.from_simple_table(simple)

参数

tbl: (Block)

SimpleTable 对象 (SimpleTable)

since: 2.11

type

type (value)

Pandoc 友好的 Lua 默认 type 函数版本，返回与手册中呈现的信息类似类型的类型。

该函数通过检查元字段 __name 来工作。如果参数具有字符串值的元字段 __name，则返回该字符串。否则，它的行为与普通 type 函数完全相同。

用法

-- Prints one of 'string', 'boolean', 'Inlines', 'Blocks',
-- 'table', and 'nil', corresponding to the Haskell constructors
-- MetaString, MetaBool, MetaInlines, MetaBlocks, MetaMap,
-- and an unset value, respectively.

function Meta (meta)
  print('type of metavalue `author`:', pandoc.utils.type(meta.author))
end

参数

value: 任何 Lua 值 (any)

给定值的类型 (string)

since: 2.17

Version

Version (v)

创建一个 Version 对象。

参数

v: 版本描述 (版本字符串、整数列表或整数)

新的 Version 对象 (Version)

模块 pandoc.mediabag

pandoc.mediabag 模块允许访问 pandoc 的媒体存储。“媒体包”在 pandoc 调用 --extract-media 或 (仅限 HTML) --embed-resources 选项时使用。

该模块作为模块 pandoc 的一部分加载，并且可以通过 pandoc.mediabag 字段访问，或者显式加载，例如：

local mb = require 'pandoc.mediabag'

函数

delete

delete (filepath)

从媒体包中删除单个条目。

参数

filepath: 要删除的项目的文件名。如果不存在具有给定文件名的条目，媒体包将保持不变。(string)

since: 2.7.3

empty

empty ()

清空媒体包，删除所有项目。

since: 2.7.3

fetch

fetch (source)

从 URL 或本地文件获取给定源。返回两个值：文件内容和 MIME 类型 (或空字符串)。

该函数首先尝试从媒体包中检索 source；如果失败，它将尝试下载或从本地文件系统读取，同时遵守 pandoc 的“资源路径”设置。

用法

local diagram_url = 'https://pandoc.cn/diagram.jpg'
local mt, contents = pandoc.mediabag.fetch(diagram_url)

参数

source: 资源的路径；可以是本地文件路径或 URI (string)

条目的 MIME 类型，如果文件未找到则为 nil。(string)
文件内容，如果文件未找到则为 nil。(string)

since: 2.0

fill

fill (doc)

用文档中的图像填充媒体包。无法检索的图像将被替换为具有“image”类的 Span，其中包含图像描述。

媒体包已包含条目的图像将不会被再次处理。

参数

doc: 从中填充媒体包的文档 (Pandoc)

修改后的文档 (Pandoc)

since: 2.19

insert

insert (filepath, mimetype, contents)

将新条目添加到 pandoc 的媒体包中。会替换任何具有相同 filepath 的现有媒体包条目。

用法

local fp = 'media/hello.txt'
local mt = 'text/plain'
local contents = 'Hello, World!'
pandoc.mediabag.insert(fp, mt, contents)

参数

filepath: 相对于输出文件夹的文件名和路径。(string)
mimetype: 项目的 MIME 类型；如果未知或不可用，则省略。(string)
内容: 文件的二进制内容。(string)

since: 2.0

items

items ()

返回一个用于 Lua 的泛型 for 语句的迭代器三元组。迭代器在每次调用时返回媒体包条目的文件路径、MIME 类型和内容。逐个处理项目以避免过多的内存使用。

只有当需要完全访问所有项目，包括其内容时，才应使用此函数。对于所有其他情况，应优先使用 list。

用法

for fp, mt, contents in pandoc.mediabag.items() do
  -- print(fp, mt, contents)
end

迭代器三元组

迭代器函数；必须使用迭代器状态和当前迭代器值进行调用。
迭代器状态 - 一个不透明的值，将传递给迭代器函数。
初始迭代器值。

since: 2.7.3

list

list ()

获取当前媒体包内容的摘要。

用法

-- calculate the size of the media bag.
local mb_items = pandoc.mediabag.list()
local sum = 0
for i = 1, #mb_items do
    sum = sum + mb_items[i].length
end
print(sum)

媒体包中每个条目的摘要项列表。摘要项包含 path、type 和 length 键，分别给出文件路径、MIME 类型和内容的长度 (字节)。(table)

since: 2.0

lookup

lookup (filepath)

在媒体包中查找媒体项，并返回其 MIME 类型和内容。

用法

local filename = 'media/diagram.png'
local mt, contents = pandoc.mediabag.lookup(filename)

参数

filepath: 要查找的文件名。(string)

条目的 MIME 类型，如果文件未找到则为 nil。(string)
文件内容，如果文件未找到则为 nil。(string)

since: 2.0

make_data_uri

make_data_uri (mime_type, raw_data)

根据 RFC 2397 将输入数据转换为 data URI。

示例

-- Embed an unofficial pandoc logo
local pandoc_logo_url = 'https://raw.githubusercontent.com/'
  .. 'tarleb/pandoc-logo/main/pandoc.svg'

local datauri = pandoc.mediabag.make_data_uri(
  pandoc.mediabag.fetch(pandoc_logo_url)
)

local image = pandoc.Image('Logo', datauri)

参数

mime_type: 数据的 MIME 类型 (string)
raw_data: 要编码的数据 (string)

data uri (string)

since: 3.7.1

write

write (dir[, fp])

将媒体包的内容写入指定的目录。如果提供了 fp，则只提取具有给定名称的资源。省略该参数意味着提取整个媒体包。如果提供了 fp 但在媒体包中找不到，则会引发错误。

参数

dir: 目标目录的路径 (string)
fp: 资源的规范名称 (相对路径) (string)

since: 3.0

模块 pandoc.List

此模块定义了 pandoc 的列表类型。它附带了有用的方法和方便的函数。

构造函数

pandoc.List([table]): 创建一个新的 List。如果提供了可选参数 table，则将其元表设置为 pandoc.List。这是 pandoc.List:new([table]) 的别名。

元方法

`pandoc.List:__concat (list)`

连接两个列表。

参数

list: 连接到第一个列表的第二个列表

返回: 一个包含 list1 和 list2 中所有元素的新列表

`pandoc.List:__eq (a, b)`

比较两个列表是否相等。当且仅当它们类型相同 (即具有相同的非 nil 元表)、长度相同，并且所有元素都相等时，列表才被视为相等。

参数

a, b: 任何 Lua 对象

如果两个列表相等，则为 true，否则为 false。

方法

`pandoc.List:at`

:at (index[, default])

返回给定索引处的元素，如果列表在该位置没有项，则返回 default。

负整数从列表的最后一个项目开始计数。

参数

index: 元素位置 (integer)
default: 如果索引超出范围，则返回的默认值 (any)

index 处的列表项，或 default。

`pandoc.List:clone ()`

返回列表的 (浅层) 副本。(要获得列表的深层副本，请使用带有空过滤器的 walk。)

`pandoc.List:extend (list)`

将给定列表添加到此列表的末尾。

参数

list: 要附加的列表

`pandoc.List:find (needle, init)`

返回给定项的第一次出现的值和索引。

参数

needle: 要搜索的项
init: 开始搜索的索引

返回: 第一个等于 needle 的项，如果不存在这样的项，则为 nil。

`pandoc.List:find_if (pred, init)`

返回第一个满足谓词的元素的值和索引。

参数

pred: 谓词函数
init: 开始搜索的索引

返回: 第一个使 test 成功的项，如果不存在这样的项，则为 nil。

`pandoc.List:filter (pred)`

返回一个新列表，其中包含所有满足给定条件的项目。

参数

pred: 项目必须满足的条件。

返回: 一个新列表，其中包含所有 test 为 true 的项。

`pandoc.List:includes (needle, init)`

检查列表是否包含与给定 needle 相等的项。

参数

needle: 要搜索的项
init: 开始搜索的索引

如果列表项等于 needle，则返回 true，否则返回 false

`pandoc.List:insert ([pos], value)`

将元素 value 插入到列表的 pos 位置，必要时将元素移至下一个更大的索引。

此函数与 table.insert 相同。

参数

pos: 新值的索引；默认为列表长度 + 1
value: 要插入到列表中的值

`pandoc.List:iter ([step])`

创建列表的迭代器。每次调用时，返回的函数都会返回下一个值。

用法

for item in List{1, 1, 2, 3, 5, 8}:iter() do
  -- process item
end

参数

step: 步进列表的步长。负步长将导致迭代器从列表末尾开始。默认为 1。(integer)

迭代器 (function)

`pandoc.List:map (fn)`

通过将给定函数应用于所有元素来返回当前列表的副本。

参数

fn: 应用于所有列表项的函数。

`pandoc.List:new([table])`

创建一个新的 List。如果提供了可选参数 table，则将其元表设置为 pandoc.List。

该函数还接受一个迭代器，在这种情况下，它会从迭代器函数返回的值创建一个新列表。

参数

table: 应被视为列表的表；默认为空表

返回: 更新后的输入值

`pandoc.List:remove ([pos])`

删除位置 pos 处的元素，并返回被删除元素的值。

此函数与 table.remove 相同。

参数

pos: 将要移除的列表值的索引；默认为最后一个元素的索引

返回：被移除的元素

`pandoc.List:sort ([comp])`

按给定顺序对列表元素进行排序，原地修改。如果提供了 comp，则它必须是一个函数，该函数接收两个列表元素并返回 true 当第一个元素在最终顺序中必须排在第二个元素之前（因此，排序后，i < j 暗示 not comp(list[j],list[i]))。如果未提供 comp，则使用标准的 Lua 操作符 <。

请注意，comp 函数必须在列表元素上定义一个严格的偏序；也就是说，它必须是反对称的并且是传递的。否则，可能无法进行有效的排序。

排序算法不稳定：通过给定顺序被认为是相等的元素，在排序后它们的相对位置可能会发生改变。

此函数与 table.sort 相同。

参数

comp: 比较函数，如上所述。

模块 pandoc.format

有关 pandoc 支持的格式的信息。

函数

all_extensions

all_extensions (format)

返回指定格式的所有有效扩展的列表。输入和输出之间不作区分；扩展在读取格式时可能有效，而在写入格式时无效，反之亦然。

参数

format: 格式名称 (string)

支持的 format 的所有扩展 (FormatExtensions)

since: 3.0

default_extensions

default_extensions (format)

返回给定格式的默认扩展列表；此函数不检查格式是否受支持，即使对于未知格式，它也会返回一个备用扩展列表。

参数

format: 格式名称 (string)

为 format 启用的默认扩展 (FormatExtensions)

since: 3.0

extensions

extensions (format)

返回指定格式的扩展配置。配置表示为一个表，其中所有支持的扩展是键，它们的默认状态是值，true 表示扩展默认启用，而 false 表示支持但禁用的扩展。

此函数可用于为自定义读取器和写入器中的 Extensions 全局变量赋值。

参数

format: 格式标识符 (string)

扩展配置 (table)

since: 3.0

from_path

from_path (path)

参数

路径: 文件路径，或路径列表 (string|{string,...})

通过启发式方法确定的格式 (string|nil)

since: 3.1.2

模块 pandoc.image

基本图像查询函数。

函数

size

size (image[, opts])

返回一个包含图像大小和分辨率的表；如果给定字符串不是图像，或者无法确定图像大小，则抛出错误。

结果表有四个条目：width（宽度）、height（高度）、dpi_horz（水平 DPI）和 dpi_vert（垂直 DPI）。

opts 参数，如果提供，应为 PANDOC_WRITER_OPTIONS 之类的 WriterOptions 对象，或带有 dpi 条目的表。它会影响 SVG 等矢量图像格式的计算。

参数

图像: 图像数据 (string)
opts: 写入器选项 (WriterOptions|table)

图像大小信息或错误消息 (table)

Since: 3.1.13

format

format (image)

将图像的格式作为小写字符串返回。

Pandoc 识别的格式包括 png、gif、tiff、jpeg、pdf、svg、eps 和 emf。

参数

图像: 二进制图像数据 (string)

图像格式，如果格式无法确定则为 nil (string|nil)

Since: 3.1.13

模块 pandoc.json

用于处理 JSON 的 JSON 模块；基于 Aeson Haskell 包。

字段

null

用于表示 null JSON 值的常量。(light userdata)

函数

decode

decode (str[, pandoc_types])

从 JSON 字符串创建 Lua 对象。如果输入可以被解码为表示 Inline、Block、Pandoc、Inlines 或 Blocks 元素，则函数将返回相应类型的对象。否则，如果输入不表示任何 AST 类型，则应用默认解码：对象和数组表示为表，JSON null 值变为 null，JSON 布尔值、字符串和数字使用同名的 Lua 类型进行转换。

通过将 pandoc_types 设置为 false 可以禁用对 AST 元素的特殊处理。

参数

str: JSON 字符串 (string)
pandoc_types: 是否在可能的情况下使用 pandoc 类型。(boolean)

解码后的对象 (any)

Since: 3.1.1

encode

encode (object)

将 Lua 对象编码为 JSON 字符串。

如果对象具有名为 __tojson 的元方法，则结果将是调用该方法并将 object 作为唯一参数传递的结果。该调用的结果预计是一个有效的 JSON 字符串，但这并未得到检查。

参数

object: 要转换的对象 (any)

给定 object 的 JSON 编码 (string)

Since: 3.1.1

模块 pandoc.log

访问 pandoc 的日志系统。

函数

info

info (message)

向 pandoc 的日志系统报告 ScriptingInfo 消息。

参数

message: 信息消息 (string)

Since: 3.2

silence

silence (fn)

在调用函数的同时应用该函数，但会阻止日志消息被添加到日志中。函数调用期间报告的警告和信息消息将作为第一个返回值返回，然后是函数调用的结果。

参数

fn: 要被静音的函数 (function)

函数调用期间触发的日志消息列表，以及函数返回的任何值。

Since: 3.2

warn

warn (message)

向 pandoc 的日志系统报告 ScriptingWarning。警告将被打印到 stderr，除非日志详细程度已设置为 ERROR。

参数

message: 警告消息 (string)

Since: 3.2

模块 pandoc.path

用于文件路径操作的模块。

字段

separator

分隔目录的字符。(string)

search_path_separator

用于分隔 PATH 环境变量中条目的字符。(string)

函数

filename

filename (filepath)

获取文件名。

参数

filepath: 路径 (string)

输入路径的文件名部分。(string)

Since: 2.12

is_absolute

is_absolute (filepath)

检查路径是否为绝对路径，即不是固定到根目录。

参数

filepath: 路径 (string)

当且仅当 filepath 是绝对路径时为 true，否则为 false。(boolean)

Since: 2.12

is_relative

is_relative (filepath)

检查路径是相对路径还是固定到根目录的路径。

参数

filepath: 路径 (string)

当且仅当 filepath 是相对路径时为 true，否则为 false。(boolean)

Since: 2.12

join

join (filepaths)

通过目录分隔符将路径元素重新组合在一起。

参数

filepaths: 路径组件 ({string,...})

连接后的路径。(string)

Since: 2.12

make_relative

make_relative (path, root[, unsafe])

根据相对路径压缩文件名。请注意，生成的路径永远不会引入 .. 路径，因为符号链接的存在意味着如果从 a/c 开始，../b 可能无法到达 a/b。有关实际示例，请参阅这篇博文。

参数

路径: 要相对化的路径 (string)
root: 根路径 (string)
unsafe: 是否允许结果中出现 ..。(boolean)

压缩后的文件名 (string)

Since: 2.12

normalize

normalize (filepath)

规范化路径。

// 仅在作为（Windows）网络驱动器的一部分时才有意义；在其他地方，多个斜杠会被减少为一个 path.separator（平台相关）。
/ 变为 path.separator（平台相关）。
./ 会被移除。
空路径将变为 .

参数

filepath: 路径 (string)

规范化后的路径。(string)

Since: 2.12

split

split (filepath)

按目录分隔符分割路径。

参数

filepath: 路径 (string)

所有路径组件的列表。({string,...})

Since: 2.12

split_extension

split_extension (filepath)

从文件路径中分割出最后一个扩展名，并返回各个部分。如果存在扩展名，则包含前导分隔符；如果路径没有扩展名，则返回空字符串作为扩展名。

参数

filepath: 路径 (string)

不带扩展名的文件路径 (string)
扩展名或空字符串 (string)

Since: 2.12

split_search_path

split_search_path (search_path)

将字符串按 search_path_separator 字符分割。在 Windows 上会忽略空白项，在 Posix 上会转换为 .。在 Windows 上，路径元素会去除引号。

参数

search_path: 平台相关的搜索路径 (string)

搜索路径中的目录列表 ({string,...})

Since: 2.12

treat_strings_as_paths

treat_strings_as_paths ()

增强字符串模块，以便字符串可以用作路径对象。

Since: 2.12

模块 pandoc.structure

访问更高级别的文档结构，包括分层章节和目录。

函数

make_sections

make_sections (blocks[, opts])

将 Blocks 组织成层级结构：一个章节列表（每个章节是一个带有类“section”的 Div，其第一个元素是 Header）。

可选的 opts 参数可以是一个表；有两个设置被识别：如果 number_sections 为 true，则会在每个 Header 中添加一个名为 number 的属性，其中包含章节编号。如果 base_level 是一个整数，则会重新组织 Header 的级别，使其没有间隙，并将编号级别向前或向后移动给定的值。最后，整数 slide_level 值会触发在该标题级别创建幻灯片。

请注意，可以传递 WriterOptions 对象作为 opts 表；这将把 number_section 和 slide_level 的值设置为命令行中定义的值。

用法

local blocks = {
  pandoc.Header(2, pandoc.Str 'first'),
  pandoc.Header(2, pandoc.Str 'second'),
}
local opts = PANDOC_WRITER_OPTIONS
local newblocks = pandoc.structure.make_sections(blocks, opts)

参数

blocks: 要处理的文档块 (Blocks|Pandoc)
opts: 选项 (table)

处理后的块 (Blocks)

since: 3.0

slide_level

slide_level (blocks)

查找开始幻灯片的标题级别（定义为在块中出现在非标题/非水平线的第一个标题级别）。

参数

blocks: 文档正文 (Blocks|Pandoc)

幻灯片级别 (integer)

since: 3.0

split_into_chunks

split_into_chunks (doc[, opts])

将 Pandoc 文档转换为 ChunkedDoc。

参数

doc

要分割的文档 (Pandoc)

opts

分割选项。

支持以下选项

`path_template`
:   template used to generate the chunks' filepaths
    `%n` will be replaced with the chunk number (padded with
    leading 0s to 3 digits), `%s` with the section number of
    the heading, `%h` with the (stringified) heading text,
    `%i` with the section identifier. For example,
    `"section-%s-%i.html"` might be resolved to
    `"section-1.2-introduction.html"`.

    Default is `"chunk-%n"` (string)

`number_sections`
:   whether sections should be numbered; default is `false`
    (boolean)

`chunk_level`
:   The heading level the document should be split into
    chunks. The default is to split at the top-level, i.e.,
    `1`. (integer)

`base_heading_level`
:   The base level to be used for numbering. Default is `nil`
    (integer|nil)

(table)

(ChunkedDoc)

since: 3.0

table_of_contents

table_of_contents (toc_source[, opts])

为给定对象生成目录。

参数

toc_source: 命令行参数列表 (Blocks|Pandoc|ChunkedDoc)
opts: 选项 (WriterOptions)

目录作为 BulletList 对象 (Block)

since: 3.0

模块 pandoc.system

访问系统信息和文件功能。

字段

arch

程序运行所在的机器架构。(string)

os

程序运行的操作系统。最常见的值是 darwin (macOS)、freebsd、linux、linux-android、mingw32 (Windows)、netbsd、openbsd。(string)

函数

cputime

cputime ()

返回当前程序使用的 CPU 时间（皮秒）。此结果的精度可能因不同版本和不同平台而异。

CPU 时间（皮秒）(integer)

Since: 3.1.1

environment

environment ()

将整个环境检索为一个字符串索引的表。

映射环境变量及其值的表。(table)

since: 2.7.3

get_working_directory

get_working_directory ()

获取当前工作目录，返回绝对路径。

since: 2.8

list_directory

list_directory ([directory])

列出目录的内容。

参数

directory: 要列出内容的目录路径。默认为 .。(string)

directory 中的所有条目列表，不包括特殊条目（. 和 ..）。(table)

since: 2.19

make_directory

make_directory (dirname[, create_parent])

创建一个新的空目录，或者尽可能接近空目录（由操作系统允许）。如果目录无法创建，例如父目录不存在或同名目录已存在，则该函数会抛出错误。

如果提供了可选的第二个参数且其值为真，则会根据需要创建所有目录，包括父目录。

参数

dirname: 新目录的名称 (string)
create_parent: 如果需要，创建父目录 (boolean)

since: 2.19

remove_directory

remove_directory (dirname[, recursive])

删除一个现有且为空的目录。如果提供了 recursive，则会递归删除目录及其内容。

参数

dirname: 要删除的目录名称 (string)
recursive: 是否递归删除内容 (boolean)

since: 2.19

with_environment

with_environment (environment, callback)

在自定义环境中运行操作。当调用 callback 时，只有 environment 给出的环境变量会被设置。即使在运行回调操作时发生错误，原始环境也会在函数完成后恢复。

参数

environment: 在运行 callback 之前设置的环境变量及其值 (table)
callback: 在自定义环境中执行的操作 (function)

对 callback 的调用的结果。

since: 2.7.3

with_temporary_directory

with_temporary_directory (parent_dir, templ, callback)

在给定目录中创建并使用临时目录。目录将在回调返回后被删除。

参数

parent_dir: 创建目录的父目录。如果省略此参数，则使用系统的规范临时目录。(string)
templ: 目录名称模板。(string)
callback: 函数，以临时目录的名称作为其第一个参数。(function)

对 callback 的调用的结果。

since: 2.8

with_working_directory

with_working_directory (directory, callback)

在不同目录下运行操作。此函数将工作目录更改为 directory，执行 callback，然后切换回原始工作目录，即使在运行回调操作时发生错误。

参数

directory: 应在其中执行给定 callback 的目录 (string)
callback: 在给定目录中执行的操作 (function)

对 callback 的调用的结果。

since: 2.7.3

模块 pandoc.layout

纯文本文档布局。

字段

blankline

插入一个空行，除非已经存在。( Doc )

cr

回车符。如果当前在行首，则不执行任何操作；否则，插入一个换行符。( Doc )

empty

空文档。( Doc )

space

一个可断开的（可重排的）空格。( Doc )

函数

after_break

after_break (text)

创建一个 Doc，该 Doc 仅在行首才会被包含。

一个有用的例子是转义 roff man 文件中的行首的 .。

参数

text: 放在换行符之后要包含的内容 (string)

新的文档 ( Doc )

Since: 2.18

before_non_blank

before_non_blank (doc)

有条件地包含给定 doc，除非它后面跟着一个空格。

参数

doc: 文档 ( Doc )

条件文档 ( Doc )

Since: 2.18

blanklines

blanklines (n)

插入空行，除非它们已经存在。

参数

n: 空行的数量 (integer)

条件空行 ( Doc )

Since: 2.18

braces

braces (doc)

将 doc 放入花括号中。

参数

doc: 文档 ( Doc )

由 {} 包围的 doc。( Doc )

Since: 2.18

brackets

brackets (doc)

将 doc 放入方括号中

参数

doc: 文档 ( Doc )

由 [] 包围的 doc。( Doc )

Since: 2.18

cblock

cblock (doc, width)

创建一个具有给定宽度和内容的块，居中对齐。

参数

doc: 文档 ( Doc )
width: 块宽度（字符数）(integer)

doc，在每行最多 width 个字符的块中居中对齐。( Doc )

Since: 2.18

chomp

chomp (doc)

从 doc 中去除尾随的空格。

参数

doc: 文档 ( Doc )

不带尾随空格的 doc ( Doc )

Since: 2.18

concat

concat (docs[, sep])

连接一个 Doc 列表。

参数

docs: Doc 列表 (`{Doc,...}`)
sep: 分隔符（默认：无）( Doc )

连接后的文档 ( Doc )

Since: 2.18

double_quotes

double_quotes (doc)

将 Doc 包装在双引号中。

参数

doc: 文档 ( Doc )

由 " 字符包围的 doc。( Doc )

Since: 2.18

flush

flush (doc)

使 Doc 左对齐。

参数

doc: 文档 ( Doc )

左对齐的 doc ( Doc )

Since: 2.18

hang

hang (doc, ind, start)

创建悬挂缩进。

参数

doc: 文档 ( Doc )
ind: 缩进宽度 (integer)
start: 文档 ( Doc )

第一行以 start 为前缀，后续行缩进 ind 个空格的 doc。( Doc )

Since: 2.18

inside

inside (contents, start, end)

将一个 Doc 包含在开始和结束 Doc 之间。

参数

内容: 文档 ( Doc )
start: 文档 ( Doc )
end: 文档 ( Doc )

包含的内容 ( Doc )

Since: 2.18

lblock

lblock (doc, width)

创建一个具有给定宽度和内容的块，左对齐。

参数

doc: 文档 ( Doc )
width: 块宽度（字符数）(integer)

放入块中的 doc，每行最多 width 个字符。( Doc )

Since: 2.18

literal

literal (text)

从字符串创建 Doc。

参数

text: 字面值 (string)

仅包含字面字符串的 doc ( Doc )

Since: 2.18

nest

nest (doc, ind)

将 Doc 按指定数量的空格缩进。

参数

doc: 文档 ( Doc )
ind: 缩进大小 (integer)

缩进 ind 个空格的 doc ( Doc )

Since: 2.18

nestle

nestle (doc)

从 Doc 中移除前导空格。

参数

doc: 文档 ( Doc )

已移除前导空格的 doc ( Doc )

Since: 2.18

nowrap

nowrap (doc)

使 Doc 不可重排。

参数

doc: 文档 ( Doc )

与输入相同，但不可重排 ( Doc )

Since: 2.18

parens

parens (doc)

将 doc 放入括号中。

参数

doc: 文档 ( Doc )

由 () 包围的 doc。( Doc )

Since: 2.18

prefixed

prefixed (doc, prefix)

使用指定的字符串作为每个内层文档行的前缀（如果不在行首，则第一个例外）。

参数

doc: 文档 ( Doc )
前缀: 每行的前缀 (string)

带前缀的 doc ( Doc )

Since: 2.18

quotes

quotes (doc)

将 Doc 包装在单引号中。

参数

doc: 文档 ( Doc )

由 ' 字符包围的 doc。( Doc )

Since: 2.18

rblock

rblock (doc, width)

创建一个具有给定宽度和内容的块，右对齐。

参数

doc: 文档 ( Doc )
width: 块宽度（字符数）(integer)

doc，在每行最多 width 个字符的块中右对齐。( Doc )

Since: 2.18

vfill

vfill (border)

一个可扩展的边框，当放置在盒子旁边时，会扩展到盒子的高度。字符串会在提供的列表中循环。

参数

border: 垂直扩展的字符 (string)

自动扩展边框 Doc ( Doc )

Since: 2.18

render

render (doc[, colwidth[, style]])

渲染一个 Doc。文本会在可断开的空格处重新排版，以匹配给定的行长度。如果行长度参数被省略或为 nil，则文本不会被重新排版。

参数

doc: 文档 ( Doc )
colwidth: 每行的最大字符数。值为 nil（默认值）表示文本不重新排版。( integer )
style: 是生成纯文本还是 ANSI 终端输出。必须是 'plain' 或 'ansi'。默认为 'plain'。(string)

渲染后的文档 (string)

Since: 2.18

is_empty

is_empty (doc)

检查一个文档是否为空。

参数

doc: 文档 ( Doc )

当且仅当 doc 为空文档时为 true，否则为 false。(boolean)

Since: 2.18

height

height (doc)

返回一个块或其他 Doc 的高度。

参数

doc: 文档 ( Doc )

文档高度 (integer|string)

Since: 2.18

min_offset

min_offset (doc)

返回一个 Doc 在可断开空格处重新排版时的最小宽度。

参数

doc: 文档 ( Doc )

最小可能宽度 (integer|string)

Since: 2.18

offset

offset (doc)

返回一个 Doc 的宽度，以字符数表示。

参数

doc: 文档 ( Doc )

文档宽度 (integer|string)

Since: 2.18

real_length

real_length (str)

返回一个字符串在等宽字体下的实际长度：组合字符为 0，普通字符为 1，东亚宽字符为 2。

参数

str: 要测量的 UTF-8 字符串 (string)

文本长度 (integer|string)

Since: 2.18

update_column

update_column (doc, i)

返回最后一个布局字符将占据的列。

参数

doc: 文档 ( Doc )
i: 起始列 (integer)

列号 (integer|string)

Since: 2.18

bold

bold (doc)

将 Doc 设置为粗体。

参数

doc: 文档 ( Doc )

粗体 Doc ( Doc )

Since: 3.4.1

italic

italic (doc)

将 Doc 设置为斜体。

参数

doc: 文档 ( Doc )

样式化的 Doc ( Doc )

Since: 3.4.1

underlined

underlined (doc)

给 Doc 添加下划线。

参数

doc: 文档 ( Doc )

样式化的 Doc ( Doc )

Since: 3.4.1

strikeout

strikeout (doc)

在 Doc 上添加删除线。

参数

doc: 文档 ( Doc )

样式化的 Doc ( Doc )

Since: 3.4.1

fg

fg (doc, color)

设置前景色。

参数

doc: 文档 ( Doc )
color: ‘black’、‘red’、‘green’、‘yellow’、‘blue’、‘magenta’、‘cyan’或‘white’之一。(string)

样式化的 Doc ( Doc )

Since: 3.4.1

bg

bg (doc, color)

设置背景色。

参数

doc: 文档 ( Doc )
color: ‘black’、‘red’、‘green’、‘yellow’、‘blue’、‘magenta’、‘cyan’或‘white’之一。(string)

样式化的 Doc ( Doc )

Since: 3.4.1

类型

Doc

参见上面的描述。

模块 pandoc.scaffolding

自定义写入器的脚手架。

字段

Writer

用作 Writer 函数的对象；该构造函数处理了大部分样板代码，只需要所有 AST 元素的渲染函数（table）

模块 pandoc.text

UTF-8 感知的文本操作函数，用 Haskell 实现。

文本模块也可以加载为 text 名称，尽管这是不推荐且已弃用的。

-- uppercase all regular text in a document:
function Str (s)
  s.text = pandoc.text.upper(s.text)
  return s
end

函数

fromencoding

fromencoding (s[, encoding])

将字符串转换为 UTF-8。encoding 参数指定输入字符串的编码。在 Windows 上，该参数默认为当前的 ANSI 代码页；在其他平台上，该函数将尝试使用文件系统的编码。

已知的编码集是系统依赖的，但至少包括 UTF-8、UTF-16BE、UTF-16LE、UTF-32BE 和 UTF-32LE。请注意，Windows 上的默认代码页可通过 CP0 获取。

参数

S: 要转换的字符串 (string)
encoding: 目标编码 (string)

UTF-8 字符串 (string)

since: 3.0

len

len (s)

返回 UTF-8 字符串的长度，即字符数。

参数

S: UTF-8 编码字符串 (string)

长度 (integer|string)

Since: 2.0.3

lower

lower (s)

返回一个 UTF-8 字符串的副本，已转换为小写。

参数

S: 要转换为小写的 UTF-8 字符串 (string)

s 的小写副本 (string)

Since: 2.0.3

reverse

reverse (s)

返回一个 UTF-8 字符串的副本，字符顺序颠倒。

参数

S: 要反转的 UTF-8 字符串 (string)

反转后的 s (string)

Since: 2.0.3

sub

sub (s, i[, j])

使用 Lua 的字符串索引规则返回 UTF-8 字符串的子字符串。

参数

S: UTF-8 字符串 (string)
i: 子字符串起始位置 (integer)
j: 子字符串结束位置 (integer)

文本子字符串 (string)

Since: 2.0.3

toencoding

toencoding (s[, enc])

将 UTF-8 字符串转换为另一种编码。encoding 参数在 Windows 上默认为当前的 ANSI 代码页；在其他平台上，它将尝试猜测文件系统的编码。

已知的编码集是系统依赖的，但至少包括 UTF-8、UTF-16BE、UTF-16LE、UTF-32BE 和 UTF-32LE。请注意，Windows 上的默认代码页可通过 CP0 获取。

参数

S: UTF-8 字符串 (string)
enc: 目标编码 (string)

重新编码后的字符串 (string)

since: 3.0

upper

upper (s)

返回一个 UTF-8 字符串的副本，已转换为大写。

参数

S: 要转换为大写的 UTF-8 字符串 (string)

s 的大写副本 (string)

Since: 2.0.3

模块 pandoc.template

处理 pandoc 模板。

函数

apply

apply (template, context)

将上下文与变量赋值应用于模板，返回渲染后的模板。context 参数必须是一个表，其中变量名为键，Doc、字符串、布尔值或表为值，其中表可以是上述类型的列表，也可以是嵌套的上下文。

参数

模板: 要应用的模板 (Template)
context: 变量值 (table)

渲染后的模板 ( Doc )

since: 3.0

compile

compile (template[, templates_path])

将模板字符串编译成 pandoc 可用的 Template 对象。

如果指定了 templates_path 参数，则它应该是与模板关联的文件路径。它用于检查部分内容。如果省略此参数，部分内容将仅从默认数据文件中获取。

编译失败时会引发错误。

参数

模板: 模板字符串（字符串）
templates_path: 用于确定部分内容的默认路径和扩展名的参数；默认使用数据文件的模板路径。（字符串）

已编译的模板（Template）

since: 2.17

default

default ([writer])

返回给定编写器的默认模板作为字符串。如果找不到这样的模板，则会引发错误。

参数

writer: 要检索模板的编写器名称；默认为全局 FORMAT。（字符串）

原始模板（字符串）

since: 2.17

get

get (filename)

检索模板的文本。

此函数首先检查资源路径中是否有此名称的文件；如果找不到，则检查用户数据目录中的 templates 目录。返回文件内容，如果找不到文件则引发错误。

参数

filename: 模板名称（字符串）

模板文件的内容（字符串）

since: 3.2.1

meta_to_context

meta_to_context (meta, blocks_writer, inlines_writer)

使用给定的函数将 Blocks 和 Inlines 转换为 Doc 值，从而根据文档的 Meta 数据创建模板上下文。

参数

meta: 文档元数据（Meta）
blocks_writer: 从 Blocks 到 Doc 值的转换器（函数）
inlines_writer: 从 Inlines 到 Doc 值的转换器（函数）

模板上下文（表）

since: 3.0

类型

Template

模块 pandoc.types

非 pandoc AST 部分的类型的构造函数。

函数

Version

Version (version_specifier)

参数

version_specifier: 版本字符串，如 '2.7.3'、Lua 数字，如 2.0、整数列表，如 {2,7,3}，或 Version 对象。（字符串|数字|{整数,...}|Version）

新的 Version 对象。（Version）

since: 2.7.3

模块 pandoc.zip

用于创建、修改和提取 zip 文件的函数。

该模块可以像函数一样调用，在这种情况下，其行为与下面描述的 zip 函数相同。

Zip 选项是可选的；定义时，它们必须是一个表，其中包含以下任何键：

recursive：设置为 true 时递归处理目录；
verbose：将信息消息打印到 stdout；
destination：值指定提取到的目录；
location：值用作路径名，定义文件的存放位置。
preserve_symlinks：布尔值，控制是否保留符号链接。此选项在 Windows 上被忽略。

函数

Entry

Entry (path, contents[, modtime])

从文件路径、未压缩的内容和文件的修改时间生成 ZipEntry。

参数

路径: 存档中的文件路径（字符串）
内容: 未压缩的内容（字符串）
modtime: 修改时间（整数）

新的 zip 存档条目（zip.Entry）

since: 3.0

read_entry

read_entry (filepath[, opts])

从文件或目录生成 ZipEntry。

参数

filepath: (string)
opts: zip 选项（表）

新的 zip 存档条目（zip.Entry）

since: 3.0

zip

zip (filepaths[, opts])

将给定文件打包并压缩成新的 Archive。

参数

filepaths: 用于创建存档的文件列表。（{字符串,...}）
opts: zip 选项（表）

新的存档（zip.Archive）

since: 3.0

类型

zip.Archive

属性

entries

此 zip 存档中的文件（{zip.Entry,...}）

方法

bytestring

bytestring (self)

返回存档的原始二进制字符串表示。

参数

self: （zip.Archive）

存档的字节（字符串）

extract

extract (self[, opts])

从此存档中提取所有文件，根据需要创建目录。请注意，最后修改时间仅在 POSIX 中正确设置，在 Windows 中不正确。此函数在存在加密条目时失败。

参数

self: （zip.Archive）
opts: zip 选项（表）

zip.Entry

属性

modtime

修改时间（自 Unix 纪元以来的秒数）（整数）

path

相对路径，使用 / 作为分隔符（zip.Entry）

方法

contents (self[, password])

获取 zip 条目的未压缩内容。如果提供了 password，则使用该密码解密内容。解密失败时会引发错误。

参数

self: （zip.Entry）
password: 条目的密码（字符串）

二进制内容（字符串）

symlink

symlink (self)

如果 Entry 代表符号链接，则返回目标，否则返回 nil。在 Windows 上始终返回 nil。

参数

self: （zip.Entry）

如果条目代表符号链接，则为链接目标（字符串|nil）

Pandoc Lua 筛选器

引言

Lua 筛选器结构

元素序列上的筛选器

遍历顺序

按类型遍历

自顶向下遍历

全局变量

Pandoc 模块

元素创建

公开的 pandoc 功能

Lua 解释器初始化

调试 Lua 筛选器

常见陷阱

示例

宏替换

在 LaTeX 和 HTML 输出中居中图像

在元数据中设置日期

在引文前删除空格

用元数据值替换占位符

修改 pandoc 的 MANUAL.txt 以便生成 man 页

从论文创建讲义

计算文档中的单词

将 ABC 代码转换为音乐符号

使用 TikZ 构建图像

Lua 类型参考

共享属性

clone

Pandoc

walk

Meta

MetaValue

Block

常用方法

walk

BlockQuote

BulletList

CodeBlock

DefinitionList

Div

Figure

Header

HorizontalRule

LineBlock

OrderedList

Para

Plain

RawBlock

Table

块

方法

walk

内联

通用方法

walk

引用

代码

强调

图像

换行

链接

数学

注释

引用

原始行内

小型大写字母

软换行

空格

跨度

字符串

删除线

粗体

下标

上标

下划线

内联

方法

walk

元素组件

属性

修改 pandoc 的 `MANUAL.txt` 以便生成 man 页

`clone`

`..`

`+`

`/`

`//`

`must_be_at_least`