Trait DomSerializer 

pub trait DomSerializer {
    type Error: Debug;

    // Required methods
    fn element_start(
        &mut self,
        tag: &str,
        namespace: Option<&str>,
    ) -> Result<(), Self::Error>;
    fn attribute(
        &mut self,
        name: &str,
        value: Peek<'_, '_>,
        namespace: Option<&str>,
    ) -> Result<(), Self::Error>;
    fn children_start(&mut self) -> Result<(), Self::Error>;
    fn children_end(&mut self) -> Result<(), Self::Error>;
    fn element_end(&mut self, tag: &str) -> Result<(), Self::Error>;
    fn text(&mut self, content: &str) -> Result<(), Self::Error>;

    // Provided methods
    fn comment(&mut self, _content: &str) -> Result<(), Self::Error> { ... }
    fn doctype(&mut self, _content: &str) -> Result<(), Self::Error> { ... }
    fn struct_metadata(&mut self, _shape: &Shape) -> Result<(), Self::Error> { ... }
    fn field_metadata(&mut self, _field: &FieldItem) -> Result<(), Self::Error> { ... }
    fn variant_metadata(
        &mut self,
        _variant: &'static Variant,
    ) -> Result<(), Self::Error> { ... }
    fn is_attribute_field(&self) -> bool { ... }
    fn is_text_field(&self) -> bool { ... }
    fn is_elements_field(&self) -> bool { ... }
    fn is_tag_field(&self) -> bool { ... }
    fn is_doctype_field(&self) -> bool { ... }
    fn clear_field_state(&mut self) { ... }
    fn format_float(&self, value: f64) -> String { ... }
    fn serialize_none(&mut self) -> Result<(), Self::Error> { ... }
    fn format_namespace(&self) -> Option<&'static str> { ... }
}

Low-level serializer interface for DOM-based formats (XML, HTML).

This trait provides callbacks for tree structure events. The shared serializer logic walks facet types and calls these methods.

Required Associated Types

type Error: Debug

Format-specific error type.

Required Methods

fn element_start( &mut self, tag: &str, namespace: Option<&str>, ) -> Result<(), Self::Error>

Begin an element with the given tag name.

Followed by zero or more attribute calls, then children_start.

fn attribute( &mut self, name: &str, value: Peek<'_, '_>, namespace: Option<&str>, ) -> Result<(), Self::Error>

Emit an attribute on the current element.

Only valid between element_start and children_start. The value is passed as a Peek so the serializer can format it directly without intermediate allocations.

fn children_start(&mut self) -> Result<(), Self::Error>

Start the children section of the current element.

fn children_end(&mut self) -> Result<(), Self::Error>

End the children section.

fn element_end(&mut self, tag: &str) -> Result<(), Self::Error>

End the current element.

fn text(&mut self, content: &str) -> Result<(), Self::Error>

Emit text content.

Provided Methods

fn comment(&mut self, _content: &str) -> Result<(), Self::Error>

Emit a comment (usually for debugging or special content).

fn doctype(&mut self, _content: &str) -> Result<(), Self::Error>

Emit a DOCTYPE declaration (XML/HTML).

This is called before the root element when a field marked with #[facet(xml::doctype)] or similar is encountered.

fn struct_metadata(&mut self, _shape: &Shape) -> Result<(), Self::Error>

Provide struct/container metadata before serializing.

This allows extracting container-level attributes like xml::ns_all.

fn field_metadata(&mut self, _field: &FieldItem) -> Result<(), Self::Error>

Provide field metadata before serializing a field.

This allows extracting field-level attributes like xml::attribute, xml::text, xml::ns, etc.

fn variant_metadata( &mut self, _variant: &'static Variant, ) -> Result<(), Self::Error>

Provide variant metadata before serializing an enum variant.

fn is_attribute_field(&self) -> bool

Check if the current field should be serialized as an attribute.

fn is_text_field(&self) -> bool

Check if the current field should be serialized as text content.

fn is_elements_field(&self) -> bool

Check if the current field is an “elements” list (no wrapper element).

fn is_tag_field(&self) -> bool

Check if the current field is a “tag” field (stores the element’s tag name).

fn is_doctype_field(&self) -> bool

Check if the current field is a “doctype” field (stores the DOCTYPE declaration).

fn clear_field_state(&mut self)

Clear field-related state after a field is serialized.

fn format_float(&self, value: f64) -> String

Format a floating-point value as a string.

Override this to provide custom float formatting (e.g., fixed decimal places). The default implementation uses Display. The value is passed as f64 (f32 values are upcast).

fn serialize_none(&mut self) -> Result<(), Self::Error>

Called when serializing None. DOM formats typically skip the field entirely.

fn format_namespace(&self) -> Option<&'static str>

Returns the format namespace for this serializer (e.g., “xml”, “html”).

This is used to select format-specific proxy types when a field has #[facet(xml::proxy = XmlProxy)] or similar format-namespaced proxies.

Returns None by default, which falls back to format-agnostic proxies.

Implementors