Crate facet_xml 

XML serialization and deserialization for Facet types.

This crate provides XML support for Facet types using an event-driven architecture powered by quick-xml.

Quick start

use facet::Facet;
use facet_xml as xml;

#[derive(Facet, Debug, PartialEq)]
struct Person {
    #[facet(xml::attribute)]
    id: u32,
    #[facet(xml::element)]
    name: String,
    #[facet(xml::element)]
    age: Option<u32>,
}

fn main() -> Result<(), facet_xml::XmlError> {
    let xml_str = r#"<Person id="42"><name>Alice</name></Person>"#;
    let person: Person = facet_xml::from_str(xml_str)?;
    assert_eq!(person.name, "Alice");
    assert_eq!(person.id, 42);
    assert_eq!(person.age, None);

    let output = facet_xml::to_string(&person)?;
    // Output: <Person id="42"><name>Alice</name></Person>
    Ok(())
}

Important: Every struct field must declare how it maps to XML. Add #[facet(xml::attribute)], #[facet(xml::element)], #[facet(xml::elements)], #[facet(xml::text)], #[facet(xml::element_name)], or #[facet(child)] to every field that should appear in XML. Fields without an annotation now trigger an error instead of being silently skipped.

Attribute Guide

#[facet(xml::element)]

Maps a field to a child XML element:

#[derive(Facet)]
struct Book {
    #[facet(xml::element)]
    title: String,
    #[facet(xml::element)]
    author: String,
}
// Deserializes: <Book><title>1984</title><author>Orwell</author></Book>

#[facet(xml::elements)]

Maps a field to multiple child elements (for Vec, HashSet, etc.):

#[derive(Facet)]
struct Library {
    #[facet(xml::elements)]
    books: Vec<Book>,
}

#[derive(Facet)]
struct Book {
    #[facet(xml::attribute)]
    isbn: String,
}
// Deserializes: <Library><Book isbn="123"/><Book isbn="456"/></Library>

#[facet(xml::attribute)]

Maps a field to an XML attribute:

#[derive(Facet)]
struct Item {
    #[facet(xml::attribute)]
    id: u32,
    #[facet(xml::attribute)]
    name: String,
}
// Deserializes: <Item id="1" name="widget"/>

#[facet(xml::text)]

Maps a field to the text content of the element:

#[derive(Facet)]
struct Message {
    #[facet(xml::attribute)]
    from: String,
    #[facet(xml::text)]
    content: String,
}
// Deserializes: <Message from="alice">Hello, world!</Message>

Error Reporting

Errors use miette spans where possible, so diagnostics can point back to the offending XML source.

Structs

DeserializeOptions

Options for controlling XML deserialization behavior.

SerializeOptions

Options for XML serialization.

Span

Source span with offset and length.

Spanned

A value with source span information.

Xml

A wrapper type for XML serialization and deserialization.

XmlError

Error type for XML deserialization.

Enums

Attr

XML attribute types for field and container configuration.

XmlErrorKind

Detailed classification of XML errors.

Functions

from_slice

Deserialize an XML byte slice into a value of type T.

from_slice_owned

Deserialize an XML byte slice into an owned type.

from_slice_with_options

Deserialize an XML byte slice into a value of type T with custom options.

from_str

Deserialize an XML string into a value of type T.

from_str_with_options

Deserialize an XML string into a value of type T with custom options.

to_string

Serialize a value of type T to an XML string.

to_string_pretty

Serialize a value of type T to a pretty-printed XML string.

to_string_with_options

Serialize a value of type T to an XML string with custom options.

to_writer

Serialize a value of type T to a writer as XML.

to_writer_pretty

Serialize a value of type T to a writer as pretty-printed XML.

to_writer_with_options

Serialize a value of type T to a writer as XML with custom options.

Type Aliases

FloatFormatter

A function that formats a floating-point number to a writer.