12 个版本

0.2.8	2024 年 7 月 22 日
0.2.6	2022 年 5 月 31 日
0.2.5	2021 年 3 月 22 日
0.2.3	2020 年 4 月 16 日
0.1.4	2020 年 3 月 31 日

在 Web 编程中排名第 100

每月下载量 650
在 tiles7800 中使用

MIT 许可证

300KB
4K SLoC

Crate xml_dom

提供对 W3C 文档对象模型核心，第 2 级合理忠实实现的 Rust crate。

此 crate 提供了一个基于特质的 DOM 实现，对第 2 级规范中定义的样式和语义进行了最小更改。规范中 IDL 的具体映射在文档中进行了描述，然而从纯粹的风格角度来看，该实现具有以下特点：

它通过不透明引用类型 RefNode 保持节点类型特质和树实现之间合理的分离。
尽可能使用 IDL 中的名称，进行最小转换。
所有 IDL 属性都变为特质函数（属性 "foo" 变为 foo()、set_foo() 和 unset_foo()）。

这导致了典型的 DOM 程序员体验的复制，其中需要在节点特质之间进行类型转换。这由 xml_dom::convert 模块支持。

示例

use xml_dom::level2::*;
use xml_dom::level2::convert::*;

// Bootstrap; get an instance of `DOMImplementation`. The mechanism for this is
// intentionally undefined by the specification.
let implementation = get_implementation();

// Create a `DocumentType` instance.
let document_type = implementation
    .create_document_type(
        "html",
        Some("-//W3C//DTD XHTML 1.0 Transitional//EN"),
        Some("http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"),
    )
    .unwrap();

// Create a new `Document` using the document type defined above. Note that this
// also has the side-effect of creating the document's root element named "html".
let mut document_node = implementation
    .create_document(
        Some("http://www.w3.org/1999/xhtml"),
        Some("html"),
        Some(document_type))
    .unwrap();

// Cast the returned document `RefNode` into a `RefDocument` trait reference
let document = as_document_mut(&mut document_node).unwrap();

// Fetch the document's root element as a node, then cast to `RefElement`.
let mut root_node = document.document_element().unwrap();
let root = as_element_mut(&mut root_node).unwrap();

// Create an `Attribute` instance on the root element.
root.set_attribute("lang", "en");

// Create two child `Element`s of "html".
let _head = root.append_child(document.create_element("head").unwrap());
let _body = root.append_child(document.create_element("body").unwrap());

// Display as XML.
let xml = document_node.to_string();
println!("document 2: {}", xml);

这应产生以下 XML；请注意，此文档中添加了格式化，为 RefNode 提供的 Display 实现不进行输出格式化。

<!DOCTYPE
  html
  PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  SYSTEM "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html lang="en">
  <head></head>
  <body></body>
</html>

特性

目前仅提供一个特性，即 quick_parser，它提供了一个具有单个公共函数的新模块 parser。此特性默认启用。

pub fn read_xml(xml: AsRef<str>) -> Result<RefNode>;

这将解析文档并返回一个新的 RefNode，该节点对应于 Document 特质。

变更

版本 0.2.8

依赖管理
- 更新了 quick-xml，它有一些破坏性 API 变更。
- 从 log 包迁移到 tracing 包。
- 移除了 this_error 依赖。

版本 0.2.7

更新到 2021 版本的 Rust
更新了 quick-xml 依赖。
使用 thiserror 对 Error 类型进行重构。
- 封装了依赖库的错误，并移除了手动 From 实现。
- 移除了未使用的 Error 枚举类型。
使用 AsRef<str> 和 Into<String> 使多个接口更通用。

版本 0.2.6

更新了 quick-xml 依赖。
- 必须更新对底层解析器错误处理。
- 必须显式处理 CData 解析器。

版本 0.2.5

添加了与现有的 parser::from_str 一起的 parser::from_reader 函数，以允许对底层源的流输入。

版本 0.2.4

更新了 quick-xml 依赖。
将 TODOs 移入 GitHub issues。
开始迁移到 GitHub actions 进行构建。

版本 0.2.3

主要是文档更新/修复。
使命名空间支持遵循 ProcessingOptions。

版本 0.2.2

主要是文档更新/修复。
修复了处理 xml:id 的缺陷。

版本 0.2.1

错误修复
- 修复了 Travis 中的发布错误
- 将 Attribute::owner_element 从 Node::parent_node 分离，它们并不相同。
- 修复了 Attribute 测试中对 owner_element 的处理。
- 修复了 Node::insert_before 中 WrongDocument 错误的实现，并在 Element::set_attribute_node 中使用相同的实现。
- 修复了值在获取时而非设置时进行转义的问题。
- 实现了来自 XML 1.1 规范的 属性值归一化 和 换行符处理。
  - 添加了对 regex 的依赖。
  - 添加了 EntityResolver 特性，以便在 DOM 中进行回调。
  - Entity 节点子节点的扩展尚未完成。
代码清理
- 在 trait_impls 中添加了一些用于常见模式的宏。
- 简化了一些现有的 match 表达式。

版本 0.2.0

清理了文档。
稳定发布。

版本 0.1.4

重大变更 重构以添加 level2 模块，允许稍后添加其他级别。同时将扩展移动到 level2::ext 模块。
重大变更 将方法重命名为符合 DOM 名称
- Node::name 到 Node::node_name;
- CharacterData::substring 更改为 CharacterData::substring_data;
- CharacterData::append 更改为 CharacterData::append_data;
- CharacterData::insert 更改为 CharacterData::insert_data;
- CharacterData::delete 更改为 CharacterData::delete_data;
- CharacterData::replace 更改为 CharacterData::replace_data.
实现了以下方法
- 节点::clone_node;
- 节点::normalize;
- 命名空间::normalize_mappings.
添加了以下DOM方法
- 属性::owner_element;
- 节点::local_name;
- 节点::namespace_uri;
- 节点::prefix.
CI构建现在与Travis一起工作，rust-xml_dom。
添加了基于quick_xml的文本解析器。
将其作为0.2.0候选版本。

版本0.1.3

总体上增加了更多单元测试，特别是针对append/insert/replace子节点
添加了对XML声明（XmlDecl，XmlVersion）的支持，不重复使用处理指令
支持最新的第二级扩展接口（Entity，EntityReference和Notation）。
- 此外，还将create_notation，create_entity和create_internal_entity添加到dom_impl中。
实现了一个选项（ProcessingOptions和DOMImplementation::create_document_with_options）功能，以启用扩展处理行为。
修复了一些嵌套借用问题。

版本0.1.2

专注于功能完成
- 实现所有核心特质功能
- 实现目前支持的特质的扩展特质功能
- 转义文本
- 重构NodeImpl以支持扩展特质
单元测试，大量的单元测试

版本0.1.1

专注于API，更清晰地分离特质的实现
更好的Display格式化
更好的append_child规则支持
支持命名空间解析
支持设置值时的文本转义
更多示例，进一步完善常见方法
注意，这目前还不适用于生产使用。

xml_dom