【Uppsala】入口模块(lib.rs)

这段代码是 Uppsala 库的入口模块 （lib.rs），相当于整个库的"门面"。我来逐段解释它的结构和作用。

---

一、模块文档注释（//! 开头）

这部分是库的顶级文档 ，用 Markdown 格式书写，会被 rustdoc 生成到官方 API 文档中。

//! # Uppsala
//!
//! A zero-dependency pure Rust XML library ...

它清晰地列出了 Uppsala 的所有核心能力：

能力	说明
XML 1.0 解析	第五版，含良构性检查
命名空间支持	第三版，前缀解析和作用域
Arena DOM	用竞技场分配器管理节点，支持增删改
XPath 1.0	所有轴、核心函数、谓词
XSD 1.1 验证	结构 + 数据类型
XSD 正则引擎	用于 pattern 约束的自定义 NFA 匹配器
序列化	保真往返、漂亮打印、流式输出
XmlWriter	无需 DOM 的命令式构建器
UTF-16 自动检测	支持 LE/BE，带或不带 BOM

文档中的示例代码

文档里嵌入了三个示例（用 ~~~ 代码块包裹），分别演示：

1. 解析和 XPath 查询 ：解析 XML，用 get_elements_by_tag_name 遍历 DOM，用 XPath 查询特定节点。
2. XSD 验证：从 Schema 文档构建验证器，检查数据是否符合类型约束。
3. 命令式构建 XML ：用 XmlWriter 逐步写出 XML 字符串。

资源限制说明

文档还解释了防止恶意输入的安全措施：

限制项	默认值	作用
元素嵌套深度	128 层	防止递归解析导致栈溢出
实体展开字节预算	1 MiB	防御"十亿笑"攻击（Billion Laughs）
实体展开嵌套深度	256 层	防止深层实体链耗尽栈空间

这些限制都可以通过 Parser::with_max_depth() 等方法调整。

---

二、模块声明（pub mod）

pub mod dom;
pub mod error;
mod exslt;
pub mod namespace;
pub mod parser;
pub mod pull;
mod simd;
#[cfg(feature = "fuzzing")]
pub use crate::simd::fuzz_exports;
pub mod writer;
pub mod xpath;
pub mod xsd;
pub mod xsd_regex;
pub mod xslt;

公开模块（pub mod）

这些是库对外暴露的子模块，用户可以直接访问：

模块	功能
dom	DOM 数据结构（Document、Node、Element 等）
error	所有错误类型（XmlError、ParseError 等）
namespace	命名空间解析和作用域管理
parser	XML 解析器核心
pull	拉取式（pull）解析器，事件流模式
writer	XmlWriter，命令式构建 XML
xpath	XPath 1.0 求值引擎
xsd	XSD 1.1 验证器
xsd_regex	XSD pattern 约束的正则引擎
xslt	XSLT 1.0 转换引擎

私有模块（mod 不带 pub）

• exslt：EXSLT 扩展（XSLT 的扩展函数集），内部使用不对外暴露。
• simd：SIMD 加速的字节扫描器（SSE2），内部热点优化。

条件编译

#[cfg(feature = "fuzzing")]
pub use crate::simd::fuzz_exports;

只有在启用 fuzzing feature 时才导出 SIMD 相关的内部函数，用于模糊测试（fuzz testing）。正常编译时这些不会出现在 API 中。

---

三、公开重导出（pub use）

pub use dom::{
    Attribute, ChildrenIter, Document, Element, NodeId, NodeKind, ProcessingInstruction, QName,
    XmlDeclaration, XmlWriteOptions,
};
pub use error::{
    NamespaceError, ParseError, ValidationError, WellFormednessError, XPathError, XmlError,
    XmlResult,
};
pub use namespace::NamespaceResolver;
pub use parser::Parser;
pub use pull::{NamespaceDeclaration, PullEvent, PullParser};
pub use writer::XmlWriter;
pub use xpath::{XPathEvaluator, XPathValue};
pub use xsd::{XsdValidator, XSI_NAMESPACE, XS_NAMESPACE};
pub use xsd_regex::XsdRegex;
pub use xslt::{Stylesheet, DEFAULT_MAX_XSLT_DEPTH, XSLT_NAMESPACE};

为什么重导出？

如果不重导出，用户要访问 Document 需要写 uppsala::dom::Document。重导出后，可以直接写 uppsala::Document，更简洁。

重点重导出的类型

类型	来源模块	用途
Document	dom	XML 文档的根对象
NodeId	dom	节点的唯一标识（索引）
XmlError / XmlResult	error	统一的错误类型和结果别名
Parser	parser	解析器构建器
XPathEvaluator / XPathValue	xpath	XPath 求值器和返回值
XsdValidator	xsd	XSD 验证器
XmlWriter	writer	XML 构建器
Stylesheet	xslt	XSLT 样式表

还导出了三个常量：

• XS_NAMESPACE：XSD 命名空间 http://www.w3.org/2001/XMLSchema
• XSI_NAMESPACE：XSD 实例命名空间 http://www.w3.org/2001/XMLSchema-instance
• XSLT_NAMESPACE：XSLT 命名空间 http://www.w3.org/1999/XSL/Transform

---

四、顶层便捷函数

1. parse ------ 从字符串解析

pub fn parse(input: &str) -> XmlResult<Document<'_>> {
    let parser = Parser::new();
    parser.parse(input)
}

最简单的入口，传入 &str 返回 Document。文档的生命周期与输入字符串绑定（Document<'_>）。

2. parse_bytes ------ 从字节数组解析（自动检测编码）

pub fn parse_bytes(input: &[u8]) -> XmlResult<Document<'static>> {
    let text = decode_xml_bytes(input)?;
    let mut doc = Parser::new().parse(&text)?;
    if let Some(decl) = doc.xml_declaration.as_mut() {
        if decl.encoding.is_some() {
            decl.encoding = Some(Cow::Borrowed("UTF-8"));
        }
    }
    Ok(doc.into_static())
}

流程：

1. 调用 decode_xml_bytes 自动检测编码（UTF-8、UTF-16 LE/BE），返回 Rust String。
2. 用 Parser 解析该字符串。
3. 如果文档有 XML 声明中的 encoding 属性，统一规范化为 "UTF-8"（因为已经转成 Rust UTF-8 字符串了）。
4. 调用 into_static() 将 Document<'_> 转为 Document<'static>，脱离输入字节的生命周期束缚。

3. transform ------ XSLT 一键转换

pub fn transform(xslt: &str, xml: &str) -> XmlResult<String> {
    let style_doc = Parser::new().parse(xslt)?;
    let stylesheet = Stylesheet::compile(&style_doc)?;
    let mut source = Parser::new().parse(xml)?;
    source.prepare_xpath();
    stylesheet.transform(&source)
}

流程：

1. 解析 XSLT 样式表字符串 → style_doc
2. 编译样式表 → Stylesheet（提前编译，可复用）
3. 解析源 XML → source
4. 调用 prepare_xpath() 为 XPath 查询准备索引（提高查询效率）
5. 执行转换 → 返回结果字符串

注释特别说明：如果要转换多个文档，应该先调用 Stylesheet::compile 编译一次，然后复用，避免重复编译开销。

---

五、内部辅助函数 ------ 编码检测与解码

decode_xml_bytes

实现了 XML 1.0 附录 F 的编码自动检测逻辑：

检测规则	判定为
前 2 字节 FF FE	UTF-16 LE（有 BOM）
前 2 字节 FE FF	UTF-16 BE（有 BOM）
前 3 字节 EF BB BF	UTF-8（有 BOM，剥离后解码）
前 2 字节 00 3C（< 的 BE 表示）	UTF-16 BE（无 BOM）
前 2 字节 3C 00（< 的 LE 表示）	UTF-16 LE（无 BOM）
其他	UTF-8

decode_utf16_le / decode_utf16_be

将字节流转换为 UTF-16 代码单元序列，然后调用 Rust 标准库的 String::from_utf16 进行解码。

关键检查：字节长度必须是偶数（否则无法配对成 16 位单元），否则返回错误。

---

总结：代码结构一览

lib.rs
├── 文档注释（库级文档 + 示例）
├── 模块声明（10 个公开模块 + 2 个私有模块）
├── 重导出（将核心类型提升到根命名空间）
├── 顶层函数
│   ├── parse()        → 从 &str 解析
│   ├── parse_bytes()  → 从 &[u8] 解析（自动检测编码）
│   └── transform()    → XSLT 一键转换
└── 内部辅助函数
    ├── decode_xml_bytes()  → 编码检测 + 分发
    ├── decode_utf16_le()   → UTF-16 LE 解码
    └── decode_utf16_be()   → UTF-16 BE 解码

这个文件本身只有约 220 行（含注释），是整个库的"总调度中心"。理解它之后，你就对整个 Uppsala 的功能模块有了全局认识。后续深入到 parser、dom、xpath 等子模块时，心里就有清晰的定位了。