Pandoc Lua 过滤器 - Pandoc 模块
Pandoc 模块包含了用于 Pandoc 脚本的字段和函数;包括文档树元素的构造器、解析给定格式文本的函数以及过滤和修改子树的函数。
Fields
readers
可以被 Pandoc 解析的格式集合。表中的所有键都可以作为 pandoc.read
中的 format
值使用。
writers
Pandoc 可以生成的格式集合。表中的所有键都可以作为 pandoc.write
中的 format
值使用。
Functions
Pandoc
Pandoc (blocks[, meta])
参数 | 描述 |
---|---|
blocks | 文档内容 ( Blocks ) |
meta | 文档元数据 ( Meta ) |
返回: 新的 Pandoc 文档 ( Pandoc )
Meta
Meta (meta)
参数 | 描述 |
---|---|
meta | 包含元信息的表格 (table ) |
返回: 新的 Meta 表格
MetaBlocks
MetaBlocks (content)
创建一个值以用作元数据中的 MetaBlocks
值;通过 pandoc.Blocks
创建输入列表的副本,并丢弃所有非列表键。
参数 | 描述 |
---|---|
content |
块内容 ( Blocks ) |
返回: 包含块元素的列表 ( Blocks )
MetaBool
MetaBool (bool)
参数 | 描述 |
---|---|
bool |
真或假 ( boolean ) |
返回: 输入,不变 ( boolean
)
MetaInlines
MetaInlines (inlines)
创建一个值以用作元数据中的 MetaInlines
值;通过 pandoc.Inlines
创建输入列表的副本,并丢弃所有非列表键。
参数 | 描述 |
---|---|
inlines |
内联元素 ( Inlines ) |
返回: 包含内联元素的列表 ( Inlines )
MetaList
MetaList (values)
创建一个值以用作元数据中的 MetaList
;通过 pandoc.List
创建输入列表的副本,并丢弃所有非列表键。
参数 | 描述 |
---|---|
values |
值或值列表 ( MetaValue | {MetaValue,...} ) |
返回: 包含元值的列表 ( List
)
MetaMap
MetaMap (key_value_map)
创建一个值以用作元数据中的 MetaMap
;通过复制输入表并仅保留字符串键的对来创建。
参数 | 描述 |
---|---|
key_value_map |
一个元值的字符串索引映射 ( table ) |
返回: 元值映射 ( table
)
MetaString
MetaString (s)
创建一个值以用作元数据中的 MetaString
;对于布尔值,这是恒等函数,仅为了完整性而存在。
参数 | 描述 |
---|---|
s |
字符串值 ( string ) |
返回: 不变的输入 ( string
)
BlockQuote
BlockQuote (content)
创建一个内容引用元素。
参数 | 描述 |
---|---|
content |
内容( Blocks ) |
返回: 内容引用元素 (Block)
BulletList
BulletList (items)
创建一个项目列表。
参数 | 描述 |
---|---|
items |
列表项( {Blocks, ...} ) |
返回: 项目列表元素 ( Block )
CodeBlock
CodeBlock (text[, attr])
创建一个代码块元素。
参数 | 描述 |
---|---|
text |
代码字符串 ( string ) |
attr |
元素属性 ( Attr ) |
返回: 代码块元素 ( Block )
DefinitionList
DefinitionList (content)
创建一个包含术语及其解释的定义列表。
参数 | 描述 |
---|---|
content |
定义项( {{Inlines , { Blocks , ... }}, ...} ) |
返回: 定义列表元素 ( Block )
Div
Div (content[, attr])
创建一个分区元素
参数 | 描述 |
---|---|
content |
区块内容 ( Blocks ) |
attr |
元素属性 ( Attr ) |
返回: 分区元素 ( Block )
Figure
Figure (content[, caption[, attr]])
创建一个 图 元素。
参数 | 描述 |
---|---|
content |
图块内容 ( Blocks ) |
caption |
图的标题 ( Caption ) |
attr |
元素属性 ( Attr ) |
返回: 图对象 ( Block )
Header
Header (level, content[, attr])
创建一个标题元素。
参数 | 描述 |
---|---|
level |
标题级别 ( 整型 ) |
content |
内联内容 ( Inlines ) |
attr |
元素属性 ( Attr ) |
返回: 标题元素 ( Block )
HorizontalRule
HorizontalRule()
创建一个水平线。
返回: 水平线元素 ( Block )
LineBlock
LineBlock(content)
创建一个行块元素。
参数 | 描述 |
---|---|
content |
行内容 ( {Inlines, ...} ) |
返回: 行块元素 ( Block )
OrderedList
OrderedList (items[, listAttributes])
创建一个有序列表。
参数 | 描述 |
---|---|
items |
列表项 ( { Blocks, ... } ) |
listAttributes |
列表参数 ( ListAttributes ) |
返回: 有序列表元素 (Block)
Para
Para (content)
创建一个段落元素。
参数 | 描述 |
---|---|
content |
行内内容 ( Inlines ) |
返回: 段落元素 ( Block )
Plain
Plain (content)
创建一个纯文本元素。
参数 | 描述 |
---|---|
content |
行内内容 ( Inlines ) |
返回: 纯文本元素 ( Block )
RawBlock
RawBlock (format, text)
创建指定格式的原始内容块。
参数 | 描述 |
---|---|
format |
内容格式( string ) |
text |
原始内容( string ) |
返回: 原始块元素 ( Block )
Table
Table (caption, colspecs, head, bodies, foot[, attr])
创建一个表格元素。
参数 | 描述 |
---|---|
caption |
表格标题 ( Caption ) |
colspecs |
列对齐和宽度 ( ColSpec, ... ) |
head |
表头 ( TableHead ) |
bodies |
表主体 ( TableBody, ... ) |
foot |
表尾 ( TableFoot ) |
attr |
元素属性 ( Attr ) |
返回: 表格元素 ( Block )
Blocks
Blocks (block_like_elements)
创建一个 Blocks
列表。
参数 | 描述 |
---|---|
block_like_elements |
可以被视为 Block 值的元素列表或单个值 ( Blocks ) |
返回: 区块元素列表 ( Blocks )
Cite
Cite (Inlines, citations)
创建一个 Cite 内联元素。
参数 | 描述 |
---|---|
Inlines |
占位符内容 ( content ) |
citations |
引用列表 ( Caption, ... ) |
返回: 引用元素 ( Inline )
Code
Code (code[, attr])
创建一个 Code 内联元素。
参数 | 描述 |
---|---|
code |
代码字符串 ( string ) |
attr |
额外属性 ( Attr ) |
返回: 代码元素 ( Inline )
Emph
Emph (content)
创建表示强调文本的内联元素。
参数 | 描述 |
---|---|
content |
内联内容( Inlines ) |
返回: 新的对象 ( Inline )
Image
Image (caption, src[, title[, attr]])
创建一个图片元素。
参数 | 描述 |
---|---|
caption |
描述图片的文字( Inlines ) |
src |
图片文件路径( string ) |
title |
简短的图片描述( string ) |
attr |
图片属性 ( Attr ) |
返回: 图片元素 ( Inline )
LineBreak
LineBreak ()
创建一个换行内联元素。
返回: 换行( Inline )
Link
Link (content, target[, title[, attr]])
创建链接内联元素,通常是超链接。
参数 | 描述 |
---|---|
content |
链接文字( Inlines ) |
target |
链接目标( string ) |
title |
简短的链接描述( string ) |
attr |
链接属性( Attr ) |
返回: 链接元素( Inline )
Math
Math (mathtype, text)
创建数学公式元素,可以是内联或显示的。
参数 | 描述 |
---|---|
mathtype |
渲染指定方式( MathType ) |
text |
数学内容( string ) |
返回: 数学元素( Inline )
Note
Note (content)
创建一个内联的注释元素。
参数 | 描述 |
---|---|
content |
注脚块内容 ( 参见 Blocks ) |
返回: 注释 (参见 Inline )
Quoted
Quoted (quotetype, content)
给定引号类型和被引用的内容,创建一个引用的内联元素。
参数 | 描述 |
---|---|
quotetype |
引号类型 ( QuoteType ) |
content |
被引用的内容 (参见 Inlines ) |
返回: 引用元素 ( 参见 Inline )
RawInline
RawInline (format, text)
创建一个原始内联元素。
参数 | 描述 |
---|---|
format |
内容的格式 ( string ) |
text |
字符串内容 ( string ) |
返回: 原始内联元素 ( 参见 Inline )
SmallCaps
SmallCaps (content)
创建以小大写形式显示的文本。
参数 | 描述 |
---|---|
content |
内联内容 参见 ( Inlines ) |
返回: 新对象 ( 参见 Inline )
SoftBreak
SoftBreak ()
创建一个软换行的内联元素。
返回: 软换行 ( 参见 Inline )
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)
创建一个下标内联元素。
参数 | 描述 |
---|---|
content |
内联内容( 参见 Inlines ) |
返回: 新的对象( 参见 Inline )
Superscript
Superscript (content)
创建一个上标内联元素。
参数 | 描述 |
---|---|
content |
内联内容( 参见 Inlines ) |
返回: 新的对象( 参见 Inline )
Underline
Underline (content)
创建带有下划线的文本。
参数 | 描述 |
---|---|
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 )
Cell
Cell (blocks[, align[, rowspan[, colspan[, attr]]]])
创建一个新的表格单元格。
参数 | 描述 |
---|---|
blocks |
单元格内容( Blocks ) |
align |
文本对齐方式,默认为 AlignDefault ( Alignment ) |
rowspan |
单元格占据的行数,默认为 1 (整数) |
colspan |
单元格占据的列数,默认为 1 (整数) |
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 ) |
mode |
引用渲染模式 (CitationMode ) |
prefix (可选) |
前缀 ( Inlines ) |
suffix (可选) |
后缀 ( Inlines ) |
note_num (可选) |
注释编号 ( integer ) |
hash (可选) |
散列号 ( integer ) |
返回: 新的引用对象 (Citation
)
ListAttributes
ListAttributes ([start[, style[, delimiter]]])
创建一个新的ListAttributes
对象。
参数 | 描述 |
---|---|
start (可选) |
第一项列表的编号 ( integer ) |
style (可选) |
用于列表编号的样式 ( string ) |
delimiter (可选) |
列表编号的分隔符 ( string ) |
返回: 新的 ListAttributes
对象 (ListAttributes
)
Row
Row ([cells[, attr]])
创建一个表格行。
参数 | 描述 |
---|---|
cells (可选) |
该行中的表格单元格列表 ( Cell , ... ) |
attr (可选) |
行属性 ( Attr ) |
返回: 新的 Row
对象 (Row
)
TableFoot
TableFoot ([rows[, attr]])
创建一个表格脚注。
参数 | 描述 |
---|---|
rows (可选) |
表格行列表 ( Row , ... ) |
attr (可选) |
表格脚注属性 ( Attr ) |
返回: 新的TableFoot
对象 (TableFoot
)
TableHead
TableHead ([rows[, attr]])
创建一个表格头部。
参数 | 描述 |
---|---|
rows (可选) |
表格行列表 ( 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], ... } ) |
widths |
相对列宽 ( { number , ...} ) |
header |
表格表头行 ( { Blocks , ... } ) |
rows |
表格行 ( { { [Blocks], ... }, ... } ) |
返回: 新的 SimpleTable 对象 (SimpleTable)
Constants
AuthorInText
: 作者名字在文本中提及。SuppressAuthor
: 抑制显示作者名字。NormalCitation
: 使用默认引用样式。DisplayMath
: 公式展示风格,表示公式应单独一行展示。InlineMath
: 公式内嵌风格,表示公式应内嵌于文本中。SingleQuote
: 引用类型,用于 Quoted ,表示字符串被单引号包围。DoubleQuote
: 引用类型,用于 Quoted ,表示字符串被双引号包围。AlignLeft
: 表格单元格左对齐。AlignRight
: 表格单元格右对齐。AlignCenter
: 表格单元格内容居中。AlignDefault
: 表格单元格不对齐方式做任何改变。DefaultDelim
: 使用默认列表编号分隔符。Period
: 列表编号以句点分隔。OneParen
: 列表编号以单个括号分隔。TwoParens
: 列表编号以双括号分隔。DefaultStyle
: 列表使用默认编号风格。Example
: 列表项以示例形式编号。Decimal
: 使用十进制整数编号。LowerRoman
: 使用小写罗马数字编号。UpperRoman
: 使用大写罗马数字编号。LowerAlpha
: 使用小写字母编号。UpperAlpha
: 使用大写字母编号。sha1
: 别名 pandoc.utils.sha1 (已废弃,建议使用pandoc.utils.sha1
)。
其他构造器
ReaderOptions (opts)
创建一个新的 ReaderOptions
对象。
参数 | 描述 |
---|---|
opts |
可以是一个包含 ReaderOptions 对象部分属性的表,或者另一个 ReaderOptions 对象。对于未明确指定的属性,会使用手册中定义的默认值。如果表中包含不属于 ReaderOptions 对象的属性,则会抛出错误。( 类型:ReaderOptions | table ) |
返回: 新的 ReaderOptions
对象
用法示例:
-- 复制命令行定义的读取选项。
local cli_opts = pandoc.ReaderOptions(PANDOC_READER_OPTIONS)
-- 默认读取选项,但将列数设置为66。
local short_columns_opts = pandoc.ReaderOptions {columns = 66}
WriterOptions (opts)
创建一个新的 WriterOptions
对象。
参数 | 描述 |
---|---|
opts |
可以是一个包含 WriterOptions 对象部分属性的表,或者另一个 WriterOptions 对象。对于未明确指定的属性,会使用手册中定义的默认值。如果表中包含不属于 WriterOptions 对象的属性,则会抛出错误。( 类型:WriterOptions | table ) |
返回: 新的 WriterOptions
对象
用法示例:
-- 复制命令行定义的写入选项。
local cli_opts = pandoc.WriterOptions(PANDOC_WRITER_OPTIONS)
-- 默认写入选项,但将DPI设置为300。
local high_dpi_opts = pandoc.WriterOptions {dpi = 300}
帮助函数
pipe (command, args, input)
运行命令并传递参数及输入数据,然后返回输出结果。
参数 | 描述 |
---|---|
command |
要运行的程序( string )。 |
args |
传递给程序的一系列参数(字符串列表)。 |
input |
通过标准输入传递给程序的数据( string )。 |
返回 命令的输出结果( string
)。
异常 如果命令退出时带有非零错误代码,则抛出一个包含 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]])
将给定的字符串解析为一个 Pandoc 文档。解析器在与读取主输入文件相同的环境中运行;它完全能够访问文件系统和媒体包。这意味着如果文档指定了要包含的文件,如在 LaTeX、reStructuredText 和 Org 等格式中可能做到的那样,那么这些文件将被包含在最终的文档中。任何媒体元素都会被添加到从其他解析的输入文件中检索到的媒体元素中。
format
参数定义了将要解析的格式风味。这可以是一个字符串,使用 +
和 -
来启用和禁用扩展功能,或者是一个包含字段 format
( string
)和 extensions
( table
)的表。
参数 | 描述 |
---|---|
markup |
待解析的标记 ( string | Sources ) |
format |
格式规范;默认为 "markdown" 。有关此参数的完整描述,请参见上面的说明。 ( string | table ) |
reader_options |
传递给读取器的选项;可以是 ReaderOptions 对象或包含 ReaderOptions 对象一部分键值对的表;默认为手册中记录的默认值。 ( ReaderOptions | table ) |
返回: 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]])
将文档转换为指定的目标格式。
参数 | 描述 |
---|---|
doc |
要转换的文档 (Pandoc) |
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)
Usage:
-- 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