谁是 Xavier？

这是一个新的库，所以请报告所有错误并帮助我们！

介绍 Xavier：一个受 Serde 启发的简化 XML 解析库 灵感。为什么是 Xavier？嗯...它以 X 开头，这是我想到的第一个名字，没有别的。

Xavier 是一个轻量级且多功能的 XML 解析库，旨在简化处理 XML 数据的过程，使其更加轻松高效。

虽然速度是 Xavier 设计的考虑因素之一，但重要的是要强调，原始速度并不是它的主要目标。相反，Xavier 优先考虑易用性和人体工程学设计，旨在在不牺牲可靠性和开发者体验的情况下，简化 Rust 应用程序中的 XML 解析任务。

它必须用于相对较小的 xml，因为它将所有数据存储在内存中。

注意 1：尚不支持 UTF-16。努力工作！欢迎 PR。

注意 2：我们的 DOM 实现旨在尽可能接近原始规范，但由于规范和 Rust 处理概念之间的差异，实现完美匹配是困难的。

为什么不扩展 Serde？

有人已经做到了，但我更喜欢从头开始。此外，由于 Xavier 专注于 XML 解析，我相信它应该更简单且更适合该目的。

示例

序列化

从简单开始

这是一个可能的简单示例

#[derive(XmlSerializable)]
struct XMLObject {
    pub some_string: String,
    pub some_int: i32,
    pub some_float: f32
}

// ... 
    println!(from_obj(&instance));
// ... 

应产生

<XMLObject>
    <some_string>Some Content A</some_string>
    <some_int>0</some_int>
    <some_float>0.0</some_float>
</XMLObject>

名称

改进名称

#[derive(XmlSerializable)]
#[xml(name="object", case="Camel", prefix="xml_", suffix="Item", no_suffix, no_prefix)]
struct XMLObject {
    #[xml(name="just_string")]
    pub some_string: String,
    pub some_int: i32,
    pub some_float: f32
}

// ... 
    println!(from_obj(&instance));
// ... 

应产生

<object>
    <xmlJustStringItem>Some Content A</xmlJustStringItem>
    <xmlSomeIntItem>0</xmlSomeIntItem>
    <xmlSomeFloatItem>0.0</xmlSomeFloatItem>
</object>

注意 1：使用 camel config 将会产生所有元素使用相同约定的情况。

注意 2：所有由 convert_case crate 支持的情况都可以使用，除了 Randoms。

注意 3：ignore_case 可以用于忽略元素的案例。

命名空间

使用命名空间

#[derive(XmlSerializable)]
#[xml(ns="xml", name="object", case="Camel")]
struct XMLObject {
    #[xml(xmlns)]
    pub namespaces: Namespaces,
    #[xml(name="just_string")]
    pub some_string: String,
    pub some_int: i32,
    pub some_float: f32
}

// ... 
    let xmlns = namespaces!(xml = "http://www.w3.org/XML/1998/namespace", xhtml = "http://www.w3.org/1999/xhtml");
    XMLObject{ namespaces: xmlns, ... }
    //...
    println!(from_obj(&instance));
    // ... 

应产生

<xml:object 
   xmlns:xml="http://www.w3.org/XML/1998/namespace" 
   xmlns:xhtml="http://www.w3.org/1999/xhtml">
        <xml:justString>Some Content A</justString>
        <xml:someInt>0</someInt>
        <xml:someFloat>0.0</someFloat>
</xml:object>

注意： #[xml(xmlns)] 只能在根节点上使用一次。

属性

使用属性

#[derive(XmlSerializable)]
#[xml(ns="a", name="object", case="Camel")]
struct XMLObject {
    #[xml(attribute, name="just_string")]
    pub some_string: String,
    pub some_int: i32,
    pub some_float: f32
}

// ... 
    println!(from_obj(&instance));
// ... 

应产生

<a:xmlObject justString="Some Text">
    <a:someInt>0</a:someInt> 
    <a:someFloat>0</a:someFloat> 
</a:xmlObject>

注意：use_suffix="false" 或 use_prefix="true" 可以用来强制使用后缀或前缀。

枚举

使用枚举

#[derive(XmlSerializable)]
enum CustomEnum {
    ValueA
}

// Many libs don't implement of infer any string value in this case, we are no exception.
impl Display for CustomEnum {
    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
        let str = match self {
            CustomEnum::ValueA => { "Value A".to_string() },
        };
        write!(f, "{}", str)
    }
}

#[derive(XmlSerializable)]
#[xml(name="object")]
struct XMLObject {
    pub enum_field: CustomEnum,
}

// ...
     println!(from_obj(&instance));
// ...

应产生

<object>
    <enum_field>ValueA</enum_field>
</object>

无名称结构体

使用类似这样的单元结构体

#[derive(XmlSerializable)]
#[xml(ns="a", name="object")]
pub struct XMLObject(String);

应产生

<a:object>Some Text</a:object>

注意：在这种情况下不支持多个属性，否则将产生编译错误。

单元结构体

使用类似这样的单元结构体

#[derive(XmlSerializable)]
#[xml(name="object")]
struct XMLObject;

应产生

<object></object>

作为根元素并不那么有用...但考虑在更树形上下文中将其用作标志字段。

树

像这样组合结构体

#[derive(XmlSerializable)]
#[xml(name="my_child")]
struct Child {
    pub child_field_a: String,
}

#[derive(XmlSerializable)]
#[xml(name="object", case="Camel")]
struct XMLObject {
    pub field_a: String,
    #[xml(tree)] //Same as #[xml(flatten)] 
    pub child: Child
}

应产生

<object>
    <fieldA>Some value</fieldA>
    <my_child>
        <child_field_a>Other value</child_field_a>
    </my_child>    
</object>

注意：案例的范围是元素。同样适用于命名空间。

集合

像这样组合结构体

#[derive(XmlSerializable)]
#[xml(name="my_child")]
struct Child {
    pub child_field_a: String,
}

#[derive(XmlSerializable)]
#[xml(name="object", case="Camel")]
struct XMLObject {
    pub field_a: String,
    pub children: Vec<Child>
}

应产生

<object>
	<fieldA>Some Text</fieldA>
	<children>
		<my_child>
			<child_field_a>Child A</child_field_a>
		</my_child>
		<my_child>
			<child_field_a>Child B</child_field_a>
		</my_child>
	</children>
</object>

注意：也支持 HashMap<String, T: XmlSerializable>，但没有命名效果。

作为标签的结构体

配置嵌套结构体如下

#[derive(XmlSerializable)]
#[xml(tag, name="child")]
struct Child {
    #[xml(attribute, name="attr")]
    pub attribute: String,
    #[xml(value)]  
    pub value: String,
}

#[derive(XmlSerializable)]
#[xml(name="object", case="Camel")]
struct XMLObject {
    pub field_a: String,
    #[xml(tree)]
    pub child: Child
}

应产生

<object>
    <fieldA>Some value</fieldA>
    <child attr="Attr Value">Other value</child>    
</object>

注意 1：你可以有任意多的属性，但只有一个值！注意 2：如果未指定，字段的默认行为是属性，值为空。

XML 声明

你可以这样配置 XML

#[derive(XmlSerializable)]
#[declaration(version="1.0" encoding="UTF-8" standaline = "no")]
#[xml(name="xml")]
struct XMLObject {
    //...
}
// or
#[derive(XmlSerializable)]
#[declaration]
#[xml(name="xml")]
struct XMLObject {
    //...
}

应产生

<?xml version = "1.0" encoding = "UTF-8" standalone = "no" ?>
<xml>
    ...
</xml>

注意：如果未指定，默认使用以下声明 version="1.0" encoding="UTF-8" standaline = "no"

DTD

使用这个

#[derive(XmlSerializable)]
#[declaration]
#[dtd = "Note.dtd"]
#[xml(name="xml")]
struct XMLObject {
    //...
}

应产生

<?xml version = "1.0" encoding = "UTF-8" standalone = "no" ?>
<!DOCTYPE xml SYSTEM "Note.dtd">
<xml>
    ...
</xml>

注意 1：目前不支持内联 DTD。然而，我愿意探索其他方法。欢迎和感激 Pull requests。注意 2：XML 验证不在此项目范围内。

PI（处理指令）

使用这个

#[derive(XmlSerializable)]
#[declaration]
#[pi(something key="value" flag)]
#[xml(name="xml")]
struct XMLObject {
    //...
}

应产生

<?xml version = "1.0" encoding = "UTF-8" standalone = "no" ?>
<?something key="value" flag?>
<xml>
    ...
</xml>

便利

CDATA

这个

  println!(cdata!("Some text & others"));  

打印这个

  <![CDATA[Some text & others]]>

文本编码

  println!(encode!("Some text & others"));  

打印这个

   Some text & others

注释

这个

  println!(comment!("Some text & others"));  

打印这个

  <!--Some text & others-->

反序列化

从简单开始

这是一个可能的简单示例

#[derive(XmlDeserializable)]
struct XMLObject {
    pub some_string: String,
    pub some_int: i32,
    pub some_float: f32
}

// ... 
    let xml = r#"
    <XMLObject>
        <some_string>Some Content A</some_string>
        <some_int>0</some_int>
        <some_float>0.0</some_float>
    </XMLObject>"#
    
    let instance: XMLObject = from_xml(&xml)?;
    assert_eq!(instance.some_string, "Some Content A");
    assert_eq!(instance.some_int, 0);
    assert_eq!(instance.some_float, 0.0);
// ... 

正如你所见，这与序列化中的标签结构相同。查看很多示例 在这里！

名称、属性、枚举、无名称结构体、单元结构体、树、集合和作为标签的结构体

与序列化完全一样，但在相反的方向。相同的标签！😊

便利

XML 声明

可以使用此宏解析声明！

    let (version, encoding, standalone) = declaration!(&xml);

DTD

可以使用此宏解析 DTD！

    let (target, file) = dtd!(&xml);

PI（处理指令）

可以使用此宏解析 PI！

    instructions!(&xml, | tag, instruction, params | {
        // DO something related with the instruction itself
    });

文本解码

  println!(decode!("Some text & others"));  

打印这个

   Some text & others

命名空间

将作为正常标签属性提供。

错误

Xavier DOM (WIP) 实现，由于规范使用 DOMException，但 "Xavier DeSer tiene un PError" ʕ•ᴥ•ʔ

待办事项

具有生存期的结构体和其他

难度：简单

来自 deserialize::parser::complex::tokens::types 的 TypeParser 函数以静态结构化方式处理类型解析，期望元素遵循预定义的顺序。虽然对于更简单的 Rust 元素有效，但在处理更复杂的 Rust 构造时可能需要额外的时间和精力。尽管如此，这项任务是可管理的，并且通过仔细注意，我们可以有效地导航这些复杂性。

如果需要，你可以修改 constructors.rs 中的对象创建过程或调整 setters/ 中的结构字段赋值。

实现 DOM

难度：中等

(branch feature/dom)

规范来自 https://www.w3.org/TR/REC-DOM-Level-1/level-one-core.html。

DOM 实现必须作为名为 "dom" 的 Cargo 功能访问，并可以使用如下方式

    //...
    let doc = to_dom(&xml);
    //...
    let xml = from_dom(&xml);
    //...