MuPDF/SumatraPDF XML 解析器(fz_xml)完全指南:API、实现原理与实战调用
MuPDF/SumatraPDF XML 解析器(fz_xml)完全指南:API、实现原理与实战调用
本指南围绕 MuPDF 内置的 XML 解析器(fz_parse_xml 系列 API)展开,它位于 ext/mupdf/docs/reference/c/fitz/xml.md,是 SumatraPDF 文档格式支持(XPS、SVG、EPUB/XHTML、XFA 表单、XMP 元数据)的底层基础设施。读完本文,你将掌握 fz_xml 树模型的核心 API 用法、preserve_white 等关键参数的取舍、解析器的容错与编码处理细节,以及它在 MuPDF 与 SumatraPDF 各模块中的真实调用方式。
一、设计定位:轻量、非校验的“格式良好 XML”解析器
MuPDF 的 XML 解析器是一个刻意保持极简的解析器,其能力边界在文档与源码中说得非常明确:
- 只处理**格式良好(well formed)**的 XML;
- 不做任何命名空间(namespace)处理——这一点在源码中表现为
xml_emit_open_tag会主动跳过名称中的命名空间前缀(xml.c中/* skip namespace prefix */逻辑),把<dc:title>解析为标签名title; - 不校验 XML 语法合法性(不验证 DTD、不检查文档结构约束)。
从源码结构看,整个解析器仅由三个文件构成:
- include/mupdf/fitz/xml.h —— 对外公开的 C API 头文件;
- source/fitz/xml.c —— 解析器主体实现(约 1464 行);
- source/fitz/xml-imp.h —— 内部树节点与属性结构定义。
另有 source/fitz/xml-write.c 与 source/fitz/xmltext-device.c 负责 XML 输出与文本抽取,同样属于该模块。
这种“够用就好”的设计动机很直接:MuPDF 需要解析的 XPS、SVG、EPUB、XFA 等格式虽然基于 XML,但不需要完整的 XML 标准栈(命名空间解析、Schema 校验、DTD 展开)就能正确读取,砍掉这些重负担可以显著缩小代码体积与解析开销,正符合 SumatraPDF 这类追求轻量快速的阅读器对嵌入解析器的要求。
二、输入编码支持与自动转码
解析器支持以下编码的输入(原文档明确列出):
UTF-8、UTF-16、iso-8859-1、iso-8859-7、koi8、windows-1250、windows-1251、windows-1252
在 source/fitz/xml.c 的 convert_to_utf8 中,编码判定按以下优先级进行:
- BOM 探测:
0xFE 0xFF视为 UTF-16 大端(BE),0xFF 0xFE视为 UTF-16 小端(LE),自动跳过后逐 16 位转码为 UTF-8; - XML 声明:查找
<?xml ... encoding="..." ?>(find_xml_encoding),将声明中的编码名与 WHATWG 编码别名表(encoding_aliases 表)比对,例如latin1→iso-8859-1、cp1251→windows-1251、ascii/us-ascii→iso-8859-1等; - HTML meta 标签:若未命中声明,则扫描
<meta http-equiv="content-type" content="text/html; charset=XXX">(find_meta_encoding),这对解析 XHTML/EPUB 内容尤为关键; - UTF-8 BOM:
0xEF 0xBB 0xBF跳过 BOM 头; - 默认:视为 UTF-8 直接使用,不做拷贝(
dofree = 0)。
转码路径统一经由 MuPDF 的 fz_text_decoder 完成(代码注释提示:内存敏感场景可改用 decode_size 先计算所需缓冲区),最终所有文本节点与属性值都以 UTF-8 对外暴露,调用方无需关心原始编码。
三、核心 API:解析、根节点与生命周期
原文档给出了两个不透明类型与四个核心入口:
typedef struct { opaque } fz_xml_doc; /* 文档句柄(整个树的引用计数与内存池) */
typedef struct { opaque } fz_xml; /* 树节点(元素或文本) */
fz_xml_doc *fz_parse_xml(fz_context *ctx, fz_buffer *buf, int preserve_white);
void fz_drop_xml(fz_context *ctx, fz_xml_doc *xml);
fz_xml *fz_xml_root(fz_xml_doc *xml);
逐一拆解:
fz_parse_xml(ctx, buf, preserve_white):把fz_buffer中的内容解析成一棵 XML 树,返回的fz_xml指针在源码中实际就是文档节点(xml.h 中typedef fz_xml fz_xml_doc说明二者是同一个结构体,fz_xml_doc仅为向后兼容的别名)。buf允许为NULL(按空文档处理,源码fz_parse_xml中有empty_string兜底)。fz_drop_xml(ctx, xml):释放文档引用。注意它接受任意位置的节点——实现中会先沿up链爬到根文档节点,再对文档引用计数做减一,归零时通过fz_drop_pool释放整棵树(xml.c L357-L371)。fz_xml_root(xml):返回树的根元素。即便传入的是树中任意节点,也会先回溯到文档节点再返回其子节点(xml.c L343-L355)。
除原文档列出的入口外,xml.h 还提供三个同源入口:
fz_parse_xml_stream(ctx, stream, preserve_white):从fz_stream读取全部内容(初始块 128 字节)后解析;fz_parse_xml_archive_entry(ctx, arch, filename, preserve_white):直接解析归档(如 EPUB 容器、XPS 部件)中的某个条目;fz_try_parse_xml_archive_entry(...):变体——归档条目不存在时返回NULL而不抛异常,其余行为相同。
配套引用语义还有 fz_keep_xml(引用计数 +1,返回原节点指针)与 fz_detach_xml(把一个子树从树中摘除并提升为新的文档根,见 xml.c L373-L394),多用于需要对局部子树做独立生命周期管理的场景。
四、树遍历 API:prev / next / up / down
fz_xml *fz_xml_prev(fz_xml *item);
fz_xml *fz_xml_next(fz_xml *item);
fz_xml *fz_xml_up(fz_xml *item);
fz_xml *fz_xml_down(fz_xml *item);
语义(实现见 xml.c L200-L221):
fz_xml_prev/fz_xml_next:返回当前节点的前一个 / 后一个兄弟节点,无则NULL;fz_xml_up:返回父元素。注意实现上的细节——它“永远不会向上走到 DOC 文档节点”(item->up && item->up->up判定),即从根元素调用返回NULL;fz_xml_down:返回第一个子节点;对文本节点返回NULL。
理解遍历行为的前提是了解树的内存表示(xml-imp.h L54-L83):
- 树的最顶端是一个 doc 节点(
up == NULL),它不参与业务遍历,只承载整棵树的refs引用计数和fz_pool内存池指针; - 普通节点是
fz_xml,通过up/down/prev/next四向指针构成双向链表 + 父子结构; - 文本节点用哨兵值
MAGIC_TEXT((fz_xml *)1)标记:item->down == MAGIC_TEXT即表示这是文本节点,此时item里存的是文本内容而非子节点。
正是这种紧凑设计,让 fz_xml_down 得以用“非文本节点才返回 down”一句话实现,也让遍历代码在绝大多数场景下无需区分节点类型。
五、节点查询 API:标签、属性与文本
原文档定义的四个查询函数是日常使用频率最高的 API:
int fz_xml_is_tag(fz_xml *item, const char *name);
/* 若该元素是名为 name 的标签,返回 true(非 0),否则返回 0 */
char *fz_xml_tag(fz_xml *item);
/* 若该元素是标签,返回标签名(UTF-8);文本节点或文档节点返回 NULL */
char *fz_xml_att(fz_xml *item, const char *att);
/* 返回标签元素的属性 att 的值;非标签元素或属性缺失时返回 NULL */
char *fz_xml_text(fz_xml *item);
/* 若该节点是文本元素,返回其 UTF-8 文本;否则返回 NULL */
实现要点(xml.c L223-L253):
fz_xml_is_tag先排除文档节点与文本节点,再用strcmp精确比较标签名;fz_xml_att沿节点的属性单链表线性查找;属性结构struct attribute(xml-imp.h L31-L36)为“变长 name + value 指针 + next 指针”,全部内存来自解析时创建的内存池,节点释放时随池整体回收;- 属性值在解析阶段就已完成实体解码(见下文“实体处理”),因此
fz_xml_att返回的是解码后的真实字符串。
此外 xml.h 还提供一批便捷变体:
fz_xml_att_alt(item, one, two):优先取one属性,缺失时回退取two,两者都缺返回NULL——对“同义属性”兼容很有用;fz_xml_att_eq(item, name, match):属性存在且值等于match时返回 1,否则 0;fz_xml_add_att(ctx, pool, node, key, val):运行时向节点追加属性(用于构造/改写树);fz_new_text_from_xml(ctx, root):将某节点下所有直接文本子节点拼接为一个新分配的 UTF-8 字符串。
六、查找 API:find / find_next / find_down 与扩展
原文档给出了三个基础的按标签名查找函数:
fz_xml *fz_xml_find(fz_xml *item, const char *tag);
/* 查找下一个具有给定标签名的元素。若 item 自身匹配则返回它;
否则从其后第一个兄弟开始找。没有匹配的兄弟时返回 NULL。 */
fz_xml *fz_xml_find_next(fz_xml *item, const char *tag);
/* 从 item 的下一个兄弟开始,查找具有给定标签名的兄弟元素;无则 NULL */
fz_xml *fz_xml_find_down(fz_xml *item, const char *tag);
/* 在 item 的第一个子元素及其兄弟中查找给定标签名的子元素;无则 NULL */
实现上三者共用核心逻辑:fz_xml_find 先跳过 DOC 文档节点(item = item->down),再沿 next 兄弟链做 strcmp 匹配(xml.c L263-L294)。fz_xml_find_down 等价于 fz_xml_find(fz_xml_down(item), tag),因此它实际会在所有子节点(而非仅第一个)中查找。
需要更复杂的匹配时,xml.h 还提供组合条件与深度优先遍历版本:
fz_xml_find_match(item, tag, att, match)/fz_xml_find_next_match/fz_xml_find_down_match:按“标签名 + 属性名 + 属性值”三重条件查找(tag可传NULL表示忽略标签名);fz_xml_find_dfs/fz_xml_find_next_dfs/fz_xml_find_dfs_top/fz_xml_find_next_dfs_top:深度优先搜索整棵子树,top参数可限定搜索上界(实现见 xml.c L1340-L1424),适合“递归查找任意深度元素”的需求。
一个典型的遍历 + 查询组合示例(解析并读取所有 <title> 子元素):
fz_xml_doc *doc = fz_parse_xml(ctx, buf, 1);
fz_xml *node;
for (node = fz_xml_down(fz_xml_root(doc)); node; node = fz_xml_next(node)) {
if (fz_xml_is_tag(node, "title")) {
const char *text = fz_xml_text(fz_xml_down(node));
/* ... 处理标题文本 ... */
}
}
fz_drop_xml(ctx, doc);
七、preserve_white 的语义与真实调用场景
preserve_white 是 fz_parse_xml 最值得关注的参数。原文档的说明是:
若
preserve_white为 false,解析器会丢弃所有纯空白文本元素。这对解析 XPS、SVG 这类非文本文档很有用;而解析 XHTML 时则需要保留空白。
源码中的实现(xml.c L567-L605 的 xml_emit_text)分两步:
- 深度为 0(根标签之外的文本)直接丢弃;
- 当
preserve_white == 0时,若某段文本全部由空白字符(空格、\r、\n、\t,见iswhite)组成,则不生成文本节点。
原因在于:XPS/SVG/EPUB 的 XML 常以缩进美化排版,若保留这些空白节点,遍历与文本提取会混入大量无意义空白;而 XHTML 中空白直接影响排版语义(如 <pre>、行内元素的间距),必须原样保留。
仓库内的真实用法恰好印证了这一规则:
| 调用位置 | preserve_white | 用途 |
|---|---|---|
| source/xps/xps-doc.c | 0 | 解析 XPS 文档部件 |
| source/svg/svg-doc.c | 0 | 解析 SVG 矢量图形 |
| source/html/epub-doc.c | 0 | 解析 EPUB 的 NCX 目录、nav 文档、container.xml、content.opf 等元数据文件 |
| source/html/html-parse.c | 1 | 解析 XHTML 正文 |
| source/pdf/pdf-form.c | 0 | 解析 PDF 的 XFA 动态表单 |
| source/pdf/pdf-zugferd.c | 0 | 解析 ZUGFeRD 电子发票 XML |
八、源码级解析原理:状态机、实体与容错
fz_parse_xml 的核心是 xml_parse_document_imp 这个手写递归下降解析器(以 goto 实现状态跳转,避免 C 递归栈开销),它用 struct parser(持有 pool、head、preserve_white、depth 四个字段)驱动对输入的一遍扫描。解析路径覆盖:
- 文本:累积到
<为止; - 元素:
<名称 属性...>与自闭合<名称/>; - 属性:
名称="值"或名称='值',并有一个特例——为兼容 MOBI 的filepos=00000无引号纯数字属性值(xml.c L806-L811)单独处理; - 注释
<!-- ... -->、CDATA<![CDATA[...]]>、处理指令<?...?>与 DOCTYPE/ENTITY 声明(<!DOCTYPE ...>直接跳过到>)。
实体(entity)解码
文本与属性值中的 &...; 实体由 xml_parse_entity 处理,支持:
- 数字实体:
&#NNN;(十进制)与&#xHH;(十六进制); - 五个 XML 预定义实体:
<>&'"; - 大量 HTML 命名实体:源码内置了一张约 250 项的 html_entities 表,覆盖
(160)、©、€、希腊字母、数学符号等——代码注释说明“本应只为 XHTML 启用,但统一支持并无害”。
解码结果经 fz_runetochar 以 UTF-8 写回节点。
嵌套深度限制与容错恢复
- 解析器设置了
FZ_XML_MAX_DEPTH 4096的嵌套深度上限(xml.c L33),超过即抛出FZ_ERROR_SYNTAX(“too deep xml element nesting”),防止恶意/畸形文档造成栈溢出; - 在标签闭合检查上,MuPDF 上游要求严格的匹配;而SumatraPDF 分支做了定制增强:
close_tag对不匹配的闭合标签采取“容错恢复”策略(xml.c L641-L673,注释明确标注SumatraPDF: recover from mismatched closers (FB2 #5792))——遇到<b><i>x</b></i>这类现实中 FB2/HTML 常见的标签交错时,自动向上关闭中间未闭合的标签继续解析;找不到匹配开放标签的闭合标签则按 HTML 风格忽略,避免整篇文档解析失败。这是原文档之外、由仓库源码确认的实用性改进。
输出与调试
解析出的树可用 fz_output_xml(写到一个 fz_output)或 fz_debug_xml(直接打到 stdout,供调试)以缩进文本形式打印;文本节点会转义显示为 "...",便于快速肉眼核对结构(xml.c L119-L198)。
九、内存模型:内存池 + 引用计数
整棵树的生命周期由两层机制管理:
- fz_pool:
fz_parse_xml一开始就fz_new_pool,之后所有节点、属性、字符串都在该池中分配,解析失败时fz_drop_pool一次释放全部,无逐节点泄漏风险; - 引用计数:文档节点持有
refs,fz_keep_xml递增、fz_drop_xml递减,归零后释放整个池。因此从任意节点调用fz_drop_xml都能安全销毁整棵树(见 xml.c L1098-L1165 的 fz_parse_xml 与 L1426-L1439 的 fz_keep_xml)。
另外,当编译开关 FZ_ENABLE_HTML_ENGINE 开启时,fz_parse_xml_from_html5 会把输入交给 Gumbo 库执行完整的 HTML5 解析算法(自动补全缺失标签、修复结构错误),再通过 xml_from_gumbo 转成同一棵 fz_xml 树——EBook/XHTML 容错解析的更高层入口,但注意它不接收 preserve_white 参数(内部恒为 1)。
十、SumatraPDF 中的实际应用:XMP 元数据读取
在 SumatraPDF 侧,XML 解析器最直观的应用是读取 PDF 的 XMP 元数据。函数 PdfFillInfoFromXmp(src/EngineMupdf.cpp L3146-L3183) 展示了标准的“解析 → 遍历 → 释放”模式:
fz_try(ctx) {
buf = pdf_load_stream(ctx, meta);
xml = fz_parse_xml(ctx, buf, 0); // XMP 为元数据,无需保留空白
XmpFields fields{};
XmlWalkXmp(xml, &fields); // 遍历提取各字段
PdfInfoPutMissing(ctx, info, SeqStrByIndex(kXmpInfoKeys, 0), fields.title, ...);
/* ... author / subject / keywords / copyright / creator / producer / dates ... */
}
fz_always(ctx) {
fz_drop_xml(ctx, xml); // 释放整棵树
fz_drop_buffer(ctx, buf);
}
fz_catch(ctx) { /* 解析失败仅告警,不中断 */ }
其中 XmlWalkXmp 对 fz_xml 树使用 fz_xml_att 读取命名空间属性(如 xml:lang)、按本地名匹配标签(见 src/EngineMupdf.cpp L2988-L3030)——这正体现了“解析器剥离命名空间前缀、以本地名匹配”的设计对上层消费方带来的便利。同时 src/libsumatrapdf.def 也将 fz_parse_xml、fz_xml_find_down 等符号导出为 libsumatrapdf 动态库的公开 API。
十一、使用建议与注意事项
- 选择合适的 preserve_white:解析 SVG/XPS/EPUB 元数据用
0,解析需要保真排版的 XHTML 正文用1; - 输入编码:非 UTF-8 输入只要命中支持列表即可自动转码;若文档既不声明编码又无 BOM 且非 UTF-8,将按 UTF-8 处理,可能出现乱码,建议上游先归一化;
- 命名空间:解析器不区分命名空间,
<dc:title>与<title>都会被匹配为title,处理带命名空间的文档时注意可能的重名冲突; - 异常处理:解析遇到语法错误会抛出
FZ_ERROR_SYNTAX,调用方务必用fz_try/fz_catch包裹(SumatraPDF 的做法是捕获后降级告警);不过对常见的不匹配闭合标签,SumatraPDF 分支已内置容错恢复; - 深度限制:嵌套超过 4096 层的文档会被拒绝,正常文档远达不到此上限,可放心使用;
- 生命周期:任意持有节点即可
fz_drop_xml释放整棵树,不要在释放后继续使用任何节点指针。
综上,MuPDF 的 fz_xml 解析器以极小的实现代价换来了对 XPS、SVG、EPUB、XFA、XMP 等格式的统一解析能力,是理解 SumatraPDF/MuPDF 文档加载链路时不可绕过的一块基础拼图。继续深入可阅读 xml.h 完整头文件、解析器实现 以及 EPUB 加载器、XPS 加载器 中的消费代码。