# commonlibrary_rust_ylong_xml

**Repository Path**: xue-lei3/commonlibrary_rust_ylong_xml

## Basic Information

- **Project Name**: commonlibrary_rust_ylong_xml
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: https://gitee.com/openharmony-sig/commonlibrary_rust_ylong_xml
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2023-06-19
- **Last Updated**: 2023-10-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ylong_xml

## 简介
`ylong_xml` 模块提供了 XML 语法格式文本或字符串的序列化功能，以及对应生成实例的反序列化功能。

### ylong_xml 在 Openharmony 中的位置
![structure](./figures/ylong_xml_oh_relate.png)
以下是对于上图关键字段的描述信息：
- `ylong_xml`：提供 `xml` 序列化与反序列化能力的系统组件
- `serde`：第三方库，用于高效、通用地序列化和反序列化 `Rust` 数据结构。

### ylong_xml 内部架构图
![structure](./figures/ylong_xml_inner_structure.png)
`ylong_xml` 内部主要分为两个模块，以自定义 DOM 结构为核心的模块和适配第三方库 `serde` 的模块。

1. `ylong_xml` 的主要实现是一系列 DOM 结构及相关方法。
- `Document`：DOM 根结构，存储整个 `xml` 文本内容。
- `Attribute`：DOM 子结构之一，用于存储 `xml` 标签的特征。
- `Element`：DOM 子结构之一，用于存储 `xml` 标签及其内容。
- `Comment`：DOM 子结构之一，用于存储 `xml` 注释。
- `Text`：DOM 子结构之一，用于存储 `xml` 标签对应的内容。
- `CdataSection`：DOM 子结构之一，用于存储 `xml` 中使用 CDATA 语法格式记录的内容。
- 序列化功能：支持将 `Document` 实例输出为紧凑型字符串或写到输出流中。
- 反序列化功能：支持解析 `xml` 文本或输入流中的 `xml` 内容并生成 `Document` 实例。

2. `ylong_xml` 适配了第三方库 `serde` 
- `Serializer`：序列化输出的辅助结构类型。
- `Deserializer`：反序列化输出的辅助结构类型。
- 序列化功能：支持将实现了 `serde::Serialize` trait 的类型实例序列化为 `xml` 文本内容或将内容写到输出流中。
- 反序列化功能：若实现了 `serde::Deserialize` trait 的类型在 `xml` 内容中，则可将该部分 `xml` 内容反序列化为该类型的实例。

## 目录
```
ylong_xml
├─ docs                                   # 说明文档
├─ examples                               # ylong_xml 代码示例
├─ figures                                # ylong_xml 架构图
├─ patches                                # patches 相关信息
├─ src
│  ├─ grammar                             # 序列化相关辅助方法
│  ├─ structure                           # Document 结构及其子结构定义与方法实现
│  ├─ error.rs                            # 错误类型定义，便于定位
│  ├─ output.rs                           # 序列化输出 Trait 与方法定义
│  ├─ parse.rs                            # DOM 结构反序列化实现
│  └─ reader.rs                           # 各类 Reader 定义与方法实现
└─ tests                                  # 测试目录
```

## 编译构建
若使用 GN 编译工具链, 在 BUILD.GN 的 deps 段下添加依赖。添加后使用 GN 进行编译和构建：

```gn 
deps += ["//commonlibrary/rust/ylong_xml:lib"]
```

若使用 Cargo 编译工具链, 在 ```Cargo.toml``` 下添加依赖。添加后使用 ```cargo``` 进行编译和构建：

```toml
[dependencies]
ylong_xml = { path = "/commonlibrary/rust/ylong_xml" } # 请使用路径依赖
```

## 用户指南
详情内容请见[用户指南](./docs/user_guide_zh.md)