在 Lua 中创建自定义 Pandoc 阅读器
引言
如果你需要解析一种 pandoc 尚未处理的格式，你可以使用 Lua 语言创建自定义阅读器。Pandoc 内置了 Lua 解释器，因此你无需安装任何额外的软件即可完成此操作。
自定义阅读器是一个 Lua 文件，它定义了一个名为 Reader 的函数，该函数接受两个参数
- 要解析的原始输入，作为源列表
- 可选地，一个阅读器选项表，例如
{ columns = 62, standalone = true }。
Reader 函数应返回一个 Pandoc AST。这可以使用 pandoc 模块中的函数创建，该模块自动在作用域内。（事实上，所有可用于 Lua 过滤器的实用函数也适用于自定义阅读器。）
每个源项对应于传递给 pandoc 的一个文件或流，其中包含其文本和名称。例如，如果将单个文件 input.txt 传递给 pandoc，则源列表将只包含一个元素 s，其中 s.name == 'input.txt' 且 s.text 包含文件内容作为字符串。
源列表及其每个元素都可以通过 Lua 标准库函数 tostring 转换为字符串。
一个最小的示例如下：
function Reader(input)
return pandoc.Pandoc({ pandoc.CodeBlock(tostring(input)) })
end这只会返回一个包含所有输入的大型代码块的文档。或者，要为每个输入文件创建一个单独的代码块，可以这样写：
function Reader(input)
return pandoc.Pandoc(input:map(
function (s) return pandoc.CodeBlock(s.text) end))
end在一个非平凡的阅读器中，你将需要解析输入。你可以使用标准的 Lua 库函数（例如，patterns 库），或者使用功能强大且快速的 lpeg 解析库，该库自动在作用域内。你也可以使用外部 Lua 库（例如，XML 解析器）。
之前的 pandoc 版本将原始字符串而不是源列表传递给 Reader 函数。依赖此行为的 Reader 函数已过时，但仍受支持：Pandoc 会分析任何脚本错误，检测代码何时假定旧行为。在这种情况下，代码会使用原始字符串输入重新运行，从而确保向后兼容性。
字节字符串阅读器
为了读取包括 docx、odt 和 epub 在内的二进制格式，pandoc 支持 ByteStringReader 函数。ByteStringReader 函数类似于处理文本输入的 Reader 函数。ByteStringReader 函数不是传递源列表，而是传递一个字节字符串，即包含二进制输入的字符串。
-- read input as epub
function ByteStringReader (input)
return pandoc.read(input, 'epub')
end格式扩展
自定义阅读器可以构建成其行为可通过格式扩展（如 smart、citations 或 hard-line-breaks）进行控制。支持的扩展是那些在全局 Extensions 表中作为键存在的扩展。默认启用状态的扩展字段值为 true 或 enable，而受支持但禁用的扩展值为 false 或 disable。
示例：具有以下全局表的编写器支持 smart、citations 和 foobar 扩展，其中 smart 默认启用，另外两个默认禁用。
Extensions = {
smart = 'enable',
citations = 'disable',
foobar = true
}用户像往常一样控制扩展，例如 pandoc -f my-reader.lua+citations。扩展可以通过阅读器选项的 extensions 字段访问，例如：
function Reader (input, opts)
print(
'The citations extension is',
opts.extensions:includes 'citations' and 'enabled' or 'disabled'
)
-- ...
end在 Extensions 字段中既未启用也未禁用的扩展被阅读器视为不受支持。尝试通过命令行修改此类扩展将导致错误。
示例：纯文本阅读器
这是一个使用 lpeg 将输入解析为空格分隔的字符串和空行分隔的段落的简单示例。
-- A sample custom reader that just parses text into blankline-separated
-- paragraphs with space-separated words.
-- For better performance we put these functions in local variables:
local P, S, R, Cf, Cc, Ct, V, Cs, Cg, Cb, B, C, Cmt =
lpeg.P, lpeg.S, lpeg.R, lpeg.Cf, lpeg.Cc, lpeg.Ct, lpeg.V,
lpeg.Cs, lpeg.Cg, lpeg.Cb, lpeg.B, lpeg.C, lpeg.Cmt
local whitespacechar = S(" \t\r\n")
local wordchar = (1 - whitespacechar)
local spacechar = S(" \t")
local newline = P"\r"^-1 * P"\n"
local blanklines = newline * (spacechar^0 * newline)^1
local endline = newline - blanklines
-- Grammar
G = P{ "Pandoc",
Pandoc = Ct(V"Block"^0) / pandoc.Pandoc;
Block = blanklines^0 * V"Para" ;
Para = Ct(V"Inline"^1) / pandoc.Para;
Inline = V"Str" + V"Space" + V"SoftBreak" ;
Str = wordchar^1 / pandoc.Str;
Space = spacechar^1 / pandoc.Space;
SoftBreak = endline / pandoc.SoftBreak;
}
function Reader(input)
return lpeg.match(G, tostring(input))
end使用示例
% pandoc -f plain.lua -t native
*Hello there*, this is plain text with no formatting
except paragraph breaks.
- Like this one.
^D
[ Para
[ Str "*Hello"
, Space
, Str "there*,"
, Space
, Str "this"
, Space
, Str "is"
, Space
, Str "plain"
, Space
, Str "text"
, Space
, Str "with"
, Space
, Str "no"
, Space
, Str "formatting"
, SoftBreak
, Str "except"
, Space
, Str "paragraph"
, Space
, Str "breaks."
]
, Para
[ Str "-"
, Space
, Str "Like"
, Space
, Str "this"
, Space
, Str "one."
]
]示例：wiki Creole 阅读器
这是 Creole 通用维基标记的解析器。它使用 lpeg 语法。有趣的是：这个自定义阅读器比 pandoc 内置的 creole 阅读器更快！这表明可以通过这种方式设计高性能阅读器。
-- A sample custom reader for Creole 1.0 (common wiki markup)
-- http://www.wikicreole.org/wiki/CheatSheet
-- For better performance we put these functions in local variables:
local P, S, R, Cf, Cc, Ct, V, Cs, Cg, Cb, B, C, Cmt =
lpeg.P, lpeg.S, lpeg.R, lpeg.Cf, lpeg.Cc, lpeg.Ct, lpeg.V,
lpeg.Cs, lpeg.Cg, lpeg.Cb, lpeg.B, lpeg.C, lpeg.Cmt
local whitespacechar = S(" \t\r\n")
local specialchar = S("/*~[]\\{}|")
local wordchar = (1 - (whitespacechar + specialchar))
local spacechar = S(" \t")
local newline = P"\r"^-1 * P"\n"
local blankline = spacechar^0 * newline
local endline = newline * #-blankline
local endequals = spacechar^0 * P"="^0 * spacechar^0 * newline
local cellsep = spacechar^0 * P"|"
local function trim(s)
return (s:gsub("^%s*(.-)%s*$", "%1"))
end
local function ListItem(lev, ch)
local start
if ch == nil then
start = S"*#"
else
start = P(ch)
end
local subitem = function(c)
if lev < 6 then
return ListItem(lev + 1, c)
else
return (1 - 1) -- fails
end
end
local parser = spacechar^0
* start^lev
* #(- start)
* spacechar^0
* Ct((V"Inline" - (newline * spacechar^0 * S"*#"))^0)
* newline
* (Ct(subitem("*")^1) / pandoc.BulletList
+
Ct(subitem("#")^1) / pandoc.OrderedList
+
Cc(nil))
/ function (ils, sublist)
return { pandoc.Plain(ils), sublist }
end
return parser
end
-- Grammar
G = P{ "Doc",
Doc = Ct(V"Block"^0)
/ pandoc.Pandoc ;
Block = blankline^0
* ( V"Header"
+ V"HorizontalRule"
+ V"CodeBlock"
+ V"List"
+ V"Table"
+ V"Para") ;
Para = Ct(V"Inline"^1)
* newline
/ pandoc.Para ;
HorizontalRule = spacechar^0
* P"----"
* spacechar^0
* newline
/ pandoc.HorizontalRule;
Header = (P("=")^1 / string.len)
* spacechar^1
* Ct((V"Inline" - endequals)^1)
* endequals
/ pandoc.Header;
CodeBlock = P"{{{"
* blankline
* C((1 - (newline * P"}}}"))^0)
* newline
* P"}}}"
/ pandoc.CodeBlock;
Placeholder = P"<<<"
* C(P(1) - P">>>")^0
* P">>>"
/ function() return pandoc.Div({}) end;
List = V"BulletList"
+ V"OrderedList" ;
BulletList = Ct(ListItem(1,'*')^1)
/ pandoc.BulletList ;
OrderedList = Ct(ListItem(1,'#')^1)
/ pandoc.OrderedList ;
Table = (V"TableHeader" + Cc{})
* Ct(V"TableRow"^1)
/ function(headrow, bodyrows)
local numcolumns = #(bodyrows[1])
local aligns = {}
local widths = {}
for i = 1,numcolumns do
aligns[i] = pandoc.AlignDefault
widths[i] = 0
end
return pandoc.utils.from_simple_table(
pandoc.SimpleTable({}, aligns, widths, headrow, bodyrows))
end ;
TableHeader = Ct(V"HeaderCell"^1)
* cellsep^-1
* spacechar^0
* newline ;
TableRow = Ct(V"BodyCell"^1)
* cellsep^-1
* spacechar^0
* newline ;
HeaderCell = cellsep
* P"="
* spacechar^0
* Ct((V"Inline" - (newline + cellsep))^0)
/ function(ils) return { pandoc.Plain(ils) } end ;
BodyCell = cellsep
* spacechar^0
* Ct((V"Inline" - (newline + cellsep))^0)
/ function(ils) return { pandoc.Plain(ils) } end ;
Inline = V"Emph"
+ V"Strong"
+ V"LineBreak"
+ V"Link"
+ V"URL"
+ V"Image"
+ V"Str"
+ V"Space"
+ V"SoftBreak"
+ V"Escaped"
+ V"Placeholder"
+ V"Code"
+ V"Special" ;
Str = wordchar^1
/ pandoc.Str;
Escaped = P"~"
* C(P(1))
/ pandoc.Str ;
Special = specialchar
/ pandoc.Str;
Space = spacechar^1
/ pandoc.Space ;
SoftBreak = endline
* # -(V"HorizontalRule" + V"CodeBlock")
/ pandoc.SoftBreak ;
LineBreak = P"\\\\"
/ pandoc.LineBreak ;
Code = P"{{{"
* C((1 - P"}}}")^0)
* P"}}}"
/ trim / pandoc.Code ;
Link = P"[["
* C((1 - (P"]]" + P"|"))^0)
* (P"|" * Ct((V"Inline" - P"]]")^1))^-1 * P"]]"
/ function(url, desc)
local txt = desc or {pandoc.Str(url)}
return pandoc.Link(txt, url)
end ;
Image = P"{{"
* #-P"{"
* C((1 - (S"}"))^0)
* (P"|" * Ct((V"Inline" - P"}}")^1))^-1
* P"}}"
/ function(url, desc)
local txt = desc or ""
return pandoc.Image(txt, url)
end ;
URL = P"http"
* P"s"^-1
* P":"
* (1 - (whitespacechar + (S",.?!:;\"'" * #whitespacechar)))^1
/ function(url)
return pandoc.Link(pandoc.Str(url), url)
end ;
Emph = P"//"
* Ct((V"Inline" - P"//")^1)
* P"//"
/ pandoc.Emph ;
Strong = P"**"
* Ct((V"Inline" -P"**")^1)
* P"**"
/ pandoc.Strong ;
}
function Reader(input, reader_options)
return lpeg.match(G, tostring(input))
end使用示例
% pandoc -f creole.lua -t markdown
== Wiki Creole
You can make things **bold** or //italic// or **//both//** or //**both**//.
Character formatting extends across line breaks: **bold,
this is still bold. This line deliberately does not end in star-star.
Not bold. Character formatting does not cross paragraph boundaries.
You can use [[internal links]] or [[http://www.wikicreole.org|external links]],
give the link a [[internal links|different]] name.
^D
## Wiki Creole
You can make things **bold** or *italic* or ***both*** or ***both***.
Character formatting extends across line breaks: \*\*bold, this is still
bold. This line deliberately does not end in star-star.
Not bold. Character formatting does not cross paragraph boundaries.
You can use [internal links](internal links) or [external
links](http://www.wikicreole.org), give the link a
[different](internal links) name.示例：从 API 解析 JSON
这个自定义阅读器会消费 https://www.reddit.com/r/haskell.json 的 JSON 输出，并生成一个包含 Haskell 子版块当前热门文章的文档。
它假设 pandoc.json 库可用，该库随 pandoc 3.1（不包括）之后的版本提供。仍可以通过使用不同的 JSON 库与旧版 pandoc 一起使用。例如，可以使用 luarocks install luajson 安装 luajson——但请确保是为 Lua 5.4 安装，这是 pandoc 打包的版本。
-- consumes the output of https://www.reddit.com/r/haskell.json
local json = require 'pandoc.json'
local function read_inlines(raw)
local doc = pandoc.read(raw, "commonmark")
return pandoc.utils.blocks_to_inlines(doc.blocks)
end
local function read_blocks(raw)
local doc = pandoc.read(raw, "commonmark")
return doc.blocks
end
function Reader(input)
local parsed = json.decode(tostring(input))
local blocks = {}
for _,entry in ipairs(parsed.data.children) do
local d = entry.data
table.insert(blocks, pandoc.Header(2,
pandoc.Link(read_inlines(d.title), d.url)))
for _,block in ipairs(read_blocks(d.selftext)) do
table.insert(blocks, block)
end
end
return pandoc.Pandoc(blocks)
end类似的代码可用于消费其他 API 的 JSON 输出。
请注意，文本字段的内容是 Markdown，因此我们使用 pandoc.read() 进行转换。
示例：语法高亮的代码文件
这是一个阅读器，它将每个输入文件的内容放入代码块中，将文件扩展名设置为代码块的类以启用代码高亮显示，并将文件名作为标题放置在每个代码块上方。
function to_code_block (source)
local _, lang = pandoc.path.split_extension(source.name)
return pandoc.Div{
pandoc.Header(1, source.name == '' and '<stdin>' or source.name),
pandoc.CodeBlock(source.text, {class=lang}),
}
end
function Reader (input, opts)
return pandoc.Pandoc(input:map(to_code_block))
end示例：从网页提取内容
这个阅读器使用命令行程序 readable（通过 npm install -g readability-cli 安装）来清理 HTML 输入中与导航相关的内容，只保留主要内容。
-- Custom reader that extracts the content from HTML documents,
-- ignoring navigation and layout elements. This preprocesses input
-- through the 'readable' program (which can be installed using
-- 'npm install -g readability-cli') and then calls the HTML reader.
-- In addition, Divs that seem to have only a layout function are removed
-- to avoid clutter.
function make_readable(source)
local result
if not pcall(function ()
local name = source.name
if not name:match("http") then
name = "file:///" .. name
end
result = pandoc.pipe("readable",
{"--keep-classes","--base",name},
source.text)
end) then
io.stderr:write("Error running 'readable': do you have it installed?\n")
io.stderr:write("npm install -g readability-cli\n")
os.exit(1)
end
return result
end
local boring_classes =
{ row = true,
page = true,
container = true
}
local boring_attributes = { "role" }
local function is_boring_class(cl)
return boring_classes[cl] or cl:match("col%-") or cl:match("pull%-")
end
local function handle_div(el)
for i,class in ipairs(el.classes) do
if is_boring_class(class) then
el.classes[i] = nil
end
end
for i,k in ipairs(boring_attributes) do
el.attributes[k] = nil
end
if el.identifier:match("readability%-") then
el.identifier = ""
end
if #el.classes == 0 and #el.attributes == 0 and #el.identifier == 0 then
return el.content
else
return el
end
end
function Reader(sources)
local readable = ''
for _,source in ipairs(sources) do
readable = readable .. make_readable(source)
end
local doc = pandoc.read(readable, "html", PANDOC_READER_OPTIONS)
-- Now remove Divs used only for layout
return doc:walk{ Div = handle_div }
end使用示例
pandoc -f readable.lua -t markdown https://pandoc.cn并将输出与以下内容进行比较：
pandoc -f html -t markdown https://pandoc.cn