xmlity_derive

Derive Macro Serialize

Source 
#[derive(Serialize)]
{
    // Attributes available to this derive:
    #[xelement]
    #[xattribute]
    #[xgroup]
    #[xvalue]
}
Expand description

Derives the Serialize trait for a type.

This macro works to serialize to XML-elements and other types of nodes including text and CDATA. To serialize to attributes, use the SerializeAttribute derive macro instead.

NOTE: It is perfectly possible to derive both Serialize and SerializeAttribute for the same type, allowing the parent to decide which serialization method to use. Since deserialization can work from multiple sources, simply deriving Deserialize is sufficient to deserialize from either elements or attributes (depending on what is enabled through the derive macro).

§Modes of serialization

Modes of serialization depends on the type of data structure you are serializing.

§Serialize as an element - Structs with #[xelement(...)] on the root of a type

The #[xelement(...)] attribute can be applied to the root of a type to specify that the type should be serialized as an element.

§Root options
Name Type Description
name String Element name.
namespace String The namespace of the element, defined as a string. This is exclusive with namespace_expr. If none of these are specified, the absence of a namespace is assumed. Must be a valid namespace string.
namespace_expr Expr The namespace of the element given as an expression to an xmlity::XmlNamespace value. This is exclusive with namespace. If none of these are specified, the absence of a namespace is assumed.
preferred_prefix String The element is serialized with the given prefix. Must be a valid XML prefix.
enforce_prefix bool Always set the prefix of the element to the prefix set in preferred_prefix. Enforce the use of the preferred prefix. If this is set to true, the preferred prefix will be used even if there is already a prefix bound to the namespace.
§Simple element with inline declarations
XML Rust types 
<note>
    <to>Tove</to>
    <from>Jani</from>
    <heading>Reminder</heading>
    <body>Message...</body>
</note>
ⓘ
#[derive(Serialize)]
#[xelement(name = "note")]
struct Note {
    #[xelement(name = "to")]
    to: String,
    #[xelement(name = "from")]
    from: String,
    #[xelement(name = "heading")]
    heading: String,
    #[xelement(name = "body")]
    body: String,
}
Rust value
ⓘ
Note {
    to: To("Tove".to_string()),
    from: From("Jani".to_string()),
    heading: Heading("Reminder".to_string()),
    body: Body("Message...".to_string()),
}

§Serialize as a sequence - structs with #[xvalue(...)] on the root of a type or no root attribute

The #[xvalue(...)] attribute can be applied to the root of a type to specify that the type should be serialized as a sequence of values, where each field is serialized as a value.

§Root options
Name Type Description
value String If the type is a unit struct, this attribute can be used to specify a text value to be serialized.

§Serialize as one of several types - enums with #[xvalue(...)] on the root of a type or no root attribute

The #[xvalue(...)] attribute can be applied to the root of an enum to specify that the type should be serialized as a one of several types.

§Root options
Name Type Description
rename_all "lowercase", "UPPERCASE", "PascalCase", "camelCase", "snake_case", "SCREAMING_SNAKE_CASE", "kebab-case", "SCREAMING-KEBAB-CASE" The text casing to use for unit variants when serializing if they don't have values specified.
with Path The path to the module that provides the serialization and deserialization functions. ::serialize and ::deserialize will be appended to this path and used as the serialize_with and deserialize_with functions.
serialize_with Expr Use function to serialize the value. Should have signature like pub fn serialize<S: xmlity::Serializer>(value: &T, serializer: S) -> Result<S::Ok, S::Error>
deserialize_with Expr Use function to deserialize the value. Should have signature like fn deserialize<'de, D: xmlity::Deserializer<'de>>(deserializer: D) -> Result<T, D::Error>
§Variant options

Variants have the same options as struct roots, and indeed work the same way.