Pandoc Lua 过滤器 - pandoc.mediabag 模块
该 pandoc.mediabag
模块允许访问 Pandoc 的媒体存储。 “媒体包” 在使用 --extract-media
或(仅限 HTML)--embed-resources
选项调用 Pandoc 时使用。
此模块作为 pandoc
模块的一部分加载,并可以通过 pandoc.mediabag
字段访问,或者显式地要求使用,例如:
local mb = require 'pandoc.mediabag'
函数
delete
delete (filepath)
从媒体包中删除单个条目。
参数 | 描述 |
---|---|
filepath |
要删除的项目的文件名。如果不存在具有给定文件名的条目,则媒体包将保持不变。( string ) |
自版本:2.7.3
empty
empty ()
清空媒体包,删除所有项目。
自版本:2.7.3
fetch
fetch (source)
从 URL 或本地文件获取给定来源。返回两个值:文件的内容和 MIME 类型(或空字符串)。
此函数将首先尝试从媒体包中检索 source
;如果失败,它将尝试下载或从本地文件系统读取,同时尊重 Pandoc 的 “资源路径” 设置。
示例用法:
local diagram_url = 'https://pandoc.org/diagram.jpg'
local mt, contents = pandoc.mediabag.fetch(diagram_url)
参数 | 描述 |
---|---|
source |
资源的路径;要么是本地文件路径,要么是 URI ( string ) |
返回值:
- 条目的 MIME 类型,如果没有找到文件则返回
nil
。(string
) - 文件的内容,如果没有找到文件则返回
nil
。(string
)
自版本:2.0
fill
fill (doc)
使用给定文档中的图像填充媒体包。无法检索的图像将被替换为包含图像描述的 “image” 类别的 Span。
对于媒体包中已经包含项目的图像将不再处理。
参数 | 描述 |
---|---|
doc |
从中填充媒体包的文档( Pandoc 类型 ) |
返回值:
- 修改后的文档( Pandoc 类型 )
自版本:2.19
insert
insert (filepath, mimetype, contents)
向 Pandoc 的媒体包(mediabag)添加一个新的条目。如果存在同名的 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 ) |
contents |
文件的二进制内容。( string ) |
自版本: 2.0
items
items ()
返回一个迭代器三元组,用于 Lua 的通用 for
语句。每次调用时,迭代器返回媒体包中一个条目的文件路径、MIME 类型和内容。为了减少内存使用,逐个处理条目。
使用示例:
for fp, mt, contents in pandoc.mediabag.items() do
-- print(fp, mt, contents)
end
返回:
迭代器三元组:
- 迭代器函数;需要以迭代器状态和当前迭代值作为参数调用。
- 迭代器状态 — 传递给迭代器函数的一个不透明的值。
- 初始迭代值。
自版本: 2.7.3
list
list ()
获取当前媒体包内容的摘要。
使用示例:
-- 计算媒体包的大小。
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)
自版本: 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
)
自版本: 2.0
write
write (dir[, fp])
将媒体包的内容写入指定的目标目录。如果提供了 fp
,则仅提取具有给定名称的资源。省略该参数意味着整个媒体包都会被提取。如果提供了 fp
但未能在媒体包中找到,则会抛出错误。
参数 | 描述 |
---|---|
dir |
目标目录的路径。( string ) |
fp |
资源的规范名称(相对路径)。( string ) |
自版本: 3.0