oxixml_xml/

writer.rs

//! High-level interface for an events-based XML emitter.
//!
//! The central type is [`Writer`], which serializes XML [`Event`]s to any
//! [`std::io::Write`] implementor, mirroring the quick-xml 0.41 `Writer`. Because
//! the reader and the writer share the same [`Event`] vocabulary, a stream of
//! events read by a [`Reader`](crate::reader::Reader) can be written back out
//! verbatim (a round trip).
//!
//! For convenience, [`Writer::create_element`] returns an [`ElementWriter`]
//! builder that makes writing a single element with attributes and content
//! ergonomic, and [`Writer::new_with_indent`] adds pretty-printing.
//!
//! # Example
//!
//! ```
//! use oxixml_xml::events::{BytesEnd, BytesStart, BytesText, Event};
//! use oxixml_xml::writer::Writer;
//!
//! let mut writer = Writer::new(Vec::new());
//! writer.write_event(Event::Start(BytesStart::new("root"))).expect("start");
//! writer.write_event(Event::Text(BytesText::new("hello & bye"))).expect("text");
//! writer.write_event(Event::End(BytesEnd::new("root"))).expect("end");
//!
//! let result = writer.into_inner();
//! assert_eq!(result, br#"<root>hello &amp; bye</root>"#);
//! ```

use std::borrow::Cow;
use std::io::{self, Write};

use crate::encoding::UTF8_BOM;
use crate::events::attributes::Attribute;
use crate::events::{BytesCData, BytesPI, BytesStart, BytesText, Event};

#[cfg(feature = "async-tokio")]
mod async_tokio;

/// A struct that holds a writer configuration.
///
/// The current writer configuration can be retrieved by calling
/// [`Writer::config()`] and changed through [`Writer::config_mut()`].
#[derive(Debug, Default, Clone, PartialEq, Eq)]
#[cfg_attr(feature = "serde-types", derive(serde::Deserialize, serde::Serialize))]
#[non_exhaustive]
pub struct Config {
    /// Whether to add a space before the closing slash in empty elements.
    /// According to the [W3C guidelines], this is recommended for maximum
    /// compatibility.
    ///
    /// When set to `true`, empty elements are terminated with "` />`". When set to
    /// `false`, empty elements are terminated with "`/>`".
    ///
    /// Default: `false`.
    ///
    /// # Example
    ///
    /// ```
    /// use oxixml_xml::writer::Writer;
    ///
    /// let mut writer = Writer::new(Vec::new());
    /// writer.config_mut().add_space_before_slash_in_empty_elements = true;
    ///
    /// writer.create_element("tag")
    ///     .with_attribute(("attr1", "value1"))
    ///     .write_empty()
    ///     .expect("write");
    ///
    /// assert_eq!(writer.into_inner(), br#"<tag attr1="value1" />"#);
    /// ```
    ///
    /// [W3C guidelines]: https://www.w3.org/TR/xhtml1/#guidelines
    pub add_space_before_slash_in_empty_elements: bool,
}

/// XML writer. Writes XML [`Event`]s to a [`std::io::Write`] implementor.
///
/// # Examples
///
/// This example reads an XML document event by event, renaming one element while
/// keeping the rest verbatim, and writes it back out.
///
/// ```
/// use oxixml_xml::events::{BytesEnd, BytesStart, Event};
/// use oxixml_xml::reader::Reader;
/// use oxixml_xml::writer::Writer;
///
/// let xml = r#"<this_tag k1="v1" k2="v2"><child>text</child></this_tag>"#;
/// let mut reader = Reader::from_str(xml);
/// let mut writer = Writer::new(Vec::new());
/// loop {
///     match reader.read_event().expect("valid event") {
///         Event::Start(e) if e.name().as_ref() == b"this_tag" => {
///             let mut elem = BytesStart::new("my_elem");
///             elem.extend_attributes(e.attributes().map(|attr| attr.expect("attr")));
///             elem.push_attribute(("my-key", "some value"));
///             writer.write_event(Event::Start(elem)).expect("start");
///         }
///         Event::End(e) if e.name().as_ref() == b"this_tag" => {
///             writer.write_event(Event::End(BytesEnd::new("my_elem"))).expect("end");
///         }
///         Event::Eof => break,
///         e => writer.write_event(e).expect("event"),
///     }
/// }
///
/// let result = writer.into_inner();
/// let expected = r#"<my_elem k1="v1" k2="v2" my-key="some value"><child>text</child></my_elem>"#;
/// assert_eq!(result, expected.as_bytes());
/// ```
#[derive(Clone)]
pub struct Writer<W> {
    /// Underlying writer.
    writer: W,
    /// Writer configuration.
    config: Config,
    /// Indentation configuration and state; stored separately from other
    /// configuration since it also tracks writer state.
    indent: Option<Indentation>,
}

impl<W> Writer<W> {
    /// Creates a `Writer` from a generic writer.
    pub const fn new(inner: W) -> Writer<W> {
        Writer {
            writer: inner,
            config: Config {
                add_space_before_slash_in_empty_elements: false,
            },
            indent: None,
        }
    }

    /// Creates a `Writer` with configured indentation from a generic writer.
    ///
    /// Each nesting level is indented by `indent_size` repetitions of the
    /// `indent_char` byte (typically `b' '` or `b'\t'`).
    pub fn new_with_indent(inner: W, indent_char: u8, indent_size: usize) -> Writer<W> {
        Writer {
            writer: inner,
            config: Config {
                add_space_before_slash_in_empty_elements: false,
            },
            indent: Some(Indentation::new(indent_char, indent_size)),
        }
    }

    /// Consumes this `Writer`, returning the underlying writer.
    pub fn into_inner(self) -> W {
        self.writer
    }

    /// Gets a mutable reference to the underlying writer.
    pub fn get_mut(&mut self) -> &mut W {
        &mut self.writer
    }

    /// Gets a reference to the underlying writer.
    pub const fn get_ref(&self) -> &W {
        &self.writer
    }

    /// Returns a reference to the writer configuration.
    pub const fn config(&self) -> &Config {
        &self.config
    }

    /// Returns a mutable reference to the writer configuration.
    pub fn config_mut(&mut self) -> &mut Config {
        &mut self.config
    }

    /// Provides a simple, high-level API for writing an XML element.
    ///
    /// Returns an [`ElementWriter`] that simplifies setting attributes and writing
    /// content inside the element.
    ///
    /// # Example
    ///
    /// ```
    /// use oxixml_xml::events::BytesText;
    /// use oxixml_xml::writer::Writer;
    ///
    /// let mut writer = Writer::new(Vec::new());
    ///
    /// // writes <tag attr1="value1"/>
    /// writer.create_element("tag")
    ///     .with_attribute(("attr1", "value1"))
    ///     .write_empty()
    ///     .expect("empty");
    ///
    /// // writes <tag attr1="value1" attr2="value2">with some text inside</tag>
    /// writer.create_element("tag")
    ///     .with_attributes(vec![("attr1", "value1"), ("attr2", "value2")])
    ///     .write_text_content(BytesText::new("with some text inside"))
    ///     .expect("text");
    ///
    /// // writes <tag><fruit quantity="0">apple</fruit><fruit quantity="1">orange</fruit></tag>
    /// writer.create_element("tag")
    ///     .write_inner_content(|writer| {
    ///         let fruits = ["apple", "orange"];
    ///         for (quant, item) in fruits.iter().enumerate() {
    ///             writer
    ///                 .create_element("fruit")
    ///                 .with_attribute(("quantity", quant.to_string().as_str()))
    ///                 .write_text_content(BytesText::new(item))?;
    ///         }
    ///         Ok(())
    ///     })
    ///     .expect("inner");
    /// ```
    #[must_use]
    pub fn create_element<'a, N>(&'a mut self, name: N) -> ElementWriter<'a, W>
    where
        N: Into<Cow<'a, str>>,
    {
        ElementWriter {
            writer: self,
            start_tag: BytesStart::new(name),
            state: AttributeIndent::NoneAttributesWritten,
            spaces: Vec::new(),
        }
    }
}

impl<W: Write> Writer<W> {
    /// Writes a [Byte-Order-Mark] character to the document.
    ///
    /// # Example
    ///
    /// ```
    /// use oxixml_xml::writer::Writer;
    ///
    /// let mut writer = Writer::new_with_indent(Vec::new(), b' ', 4);
    ///
    /// writer.write_bom().expect("bom");
    /// writer
    ///     .create_element("empty")
    ///     .with_attribute(("attr1", "value1"))
    ///     .write_empty()
    ///     .expect("empty");
    ///
    /// assert_eq!(
    ///     std::str::from_utf8(&writer.into_inner()).expect("utf-8"),
    ///     "\u{FEFF}<empty attr1=\"value1\"/>"
    /// );
    /// ```
    ///
    /// [Byte-Order-Mark]: https://unicode.org/faq/utf_bom.html#BOM
    pub fn write_bom(&mut self) -> io::Result<()> {
        self.write(UTF8_BOM)
    }

    /// Writes the given event to the underlying writer.
    pub fn write_event<'a, E: Into<Event<'a>>>(&mut self, event: E) -> io::Result<()> {
        let mut next_should_line_break = true;
        let result = match event.into() {
            Event::Start(e) => {
                let result = self.write_wrapped(b"<", &e, b">");
                if let Some(i) = self.indent.as_mut() {
                    i.grow();
                }
                result
            }
            Event::End(e) => {
                if let Some(i) = self.indent.as_mut() {
                    i.shrink();
                }
                self.write_wrapped(b"</", &e, b">")
            }
            Event::Empty(e) => self.write_wrapped(
                b"<",
                &e,
                if self.config.add_space_before_slash_in_empty_elements {
                    b" />"
                } else {
                    b"/>"
                },
            ),
            Event::Text(e) => {
                next_should_line_break = false;
                self.write(&e)
            }
            Event::Comment(e) => self.write_wrapped(b"<!--", &e, b"-->"),
            Event::CData(e) => {
                next_should_line_break = false;
                self.write(b"<![CDATA[")?;
                self.write(&e)?;
                self.write(b"]]>")
            }
            Event::Decl(e) => self.write_wrapped(b"<?", &e, b"?>"),
            Event::PI(e) => self.write_wrapped(b"<?", &e, b"?>"),
            Event::DocType(e) => self.write_wrapped(b"<!DOCTYPE ", &e, b">"),
            Event::GeneralRef(e) => self.write_wrapped(b"&", &e, b";"),
            Event::Eof => Ok(()),
        };
        if let Some(i) = self.indent.as_mut() {
            i.should_line_break = next_should_line_break;
        }
        result
    }

    /// Writes bytes directly to the underlying writer.
    #[inline]
    pub(crate) fn write(&mut self, value: &[u8]) -> io::Result<()> {
        self.writer.write_all(value)
    }

    #[inline]
    fn write_wrapped(&mut self, before: &[u8], value: &[u8], after: &[u8]) -> io::Result<()> {
        if let Some(ref i) = self.indent {
            if i.should_line_break {
                self.writer.write_all(b"\n")?;
                self.writer.write_all(i.current())?;
            }
        }
        self.write(before)?;
        self.write(value)?;
        self.write(after)?;
        Ok(())
    }

    /// Manually writes a newline and indentation at the proper level.
    ///
    /// This can be used when the heuristic to line break and indent after every
    /// [`Event`] apart from [`Text`](Event::Text) fails, such as when a
    /// [`Start`](Event::Start) occurs directly after a [`Text`](Event::Text).
    ///
    /// This method does nothing if `Writer` was not constructed with
    /// [`new_with_indent`](Self::new_with_indent).
    pub fn write_indent(&mut self) -> io::Result<()> {
        if let Some(ref i) = self.indent {
            self.writer.write_all(b"\n")?;
            self.writer.write_all(i.current())?;
        }
        Ok(())
    }

    /// Writes a serde-serializable value as an XML element named `tag_name`.
    ///
    /// The value is serialized with [`crate::se::Serializer`], so the usual
    /// mapping rules apply (`@field` becomes an attribute, `$text` becomes the
    /// text content, and so on). If this `Writer` was created with
    /// [`new_with_indent`](Self::new_with_indent), the produced markup shares the
    /// writer's indentation state.
    ///
    /// # Examples
    ///
    /// ```
    /// # use serde::Serialize;
    /// # use oxixml_xml::events::{BytesStart, Event};
    /// # use oxixml_xml::writer::Writer;
    /// # use oxixml_xml::se::SeError;
    /// # fn main() -> Result<(), SeError> {
    /// #[derive(Debug, PartialEq, Serialize)]
    /// struct MyData {
    ///     question: String,
    ///     answer: u32,
    /// }
    ///
    /// let data = MyData {
    ///     question: "The Ultimate Question of Life, the Universe, and Everything".into(),
    ///     answer: 42,
    /// };
    ///
    /// let mut buffer = Vec::new();
    /// let mut writer = Writer::new_with_indent(&mut buffer, b' ', 4);
    ///
    /// let start = BytesStart::new("root");
    /// let end = start.to_end();
    ///
    /// writer.write_event(Event::Start(start.clone()))?;
    /// writer.write_serializable("my_data", &data)?;
    /// writer.write_event(Event::End(end))?;
    ///
    /// assert_eq!(
    ///     std::str::from_utf8(&buffer)?,
    ///     r#"<root>
    ///     <my_data>
    ///         <question>The Ultimate Question of Life, the Universe, and Everything</question>
    ///         <answer>42</answer>
    ///     </my_data>
    /// </root>"#
    /// );
    /// # Ok(())
    /// # }
    /// ```
    #[cfg(feature = "serialize")]
    #[cfg_attr(docsrs, doc(cfg(feature = "serialize")))]
    pub fn write_serializable<T: serde::Serialize>(
        &mut self,
        tag_name: &str,
        content: &T,
    ) -> std::result::Result<(), crate::errors::serialize::SeError> {
        use crate::se::{Indent, Serializer};

        self.write_indent()?;
        let mut fmt = ToFmtWrite(&mut self.writer);
        let mut serializer = Serializer::with_root(&mut fmt, Some(tag_name))?;

        if let Some(indent) = &mut self.indent {
            serializer.set_indent(Indent::Borrow(indent));
        }

        content.serialize(serializer)?;

        Ok(())
    }
}

/// Adapts an [`std::io::Write`] implementor to the [`std::fmt::Write`] trait
/// required by the serde serializer.
#[cfg(feature = "serialize")]
pub(crate) struct ToFmtWrite<T>(pub T);

#[cfg(feature = "serialize")]
impl<T> std::fmt::Write for ToFmtWrite<T>
where
    T: std::io::Write,
{
    fn write_str(&mut self, s: &str) -> std::fmt::Result {
        self.0.write_all(s.as_bytes()).map_err(|_| std::fmt::Error)
    }
}

/// Tracks indent-inside-element state for [`ElementWriter`].
///
/// ```mermaid
/// stateDiagram-v2
///     [*] --> NoneAttributesWritten
///     NoneAttributesWritten --> Spaces : .with_attribute()
///     NoneAttributesWritten --> WriteConfigured : .new_line()
///
///     Spaces --> Spaces : .with_attribute()
///     Spaces --> WriteSpaces : .new_line()
///
///     WriteSpaces --> Spaces : .with_attribute()
///     WriteSpaces --> WriteSpaces : .new_line()
///
///     Configured --> Configured : .with_attribute()
///     Configured --> WriteConfigured : .new_line()
///
///     WriteConfigured --> Configured : .with_attribute()
///     WriteConfigured --> WriteConfigured : .new_line()
/// ```
#[derive(Debug)]
enum AttributeIndent {
    /// Initial state: `ElementWriter` was just created and no attributes are
    /// written yet.
    NoneAttributesWritten,
    /// Write the specified count of spaces to indent before writing an attribute
    /// in `with_attribute()`.
    WriteSpaces(usize),
    /// Keep the space indent that should be used if `new_line()` is called.
    Spaces(usize),
    /// Write the specified count of indent characters before writing an attribute
    /// in `with_attribute()`.
    WriteConfigured(usize),
    /// Keep the indent that should be used if `new_line()` is called.
    Configured(usize),
}

/// A builder to write a single element, returned by [`Writer::create_element`].
///
/// Contains methods to add attributes and inner content to the element.
pub struct ElementWriter<'a, W> {
    writer: &'a mut Writer<W>,
    start_tag: BytesStart<'a>,
    state: AttributeIndent,
    /// Contains spaces used to write space indents of attributes.
    spaces: Vec<u8>,
}

impl<'a, W> ElementWriter<'a, W> {
    /// Adds an attribute to this element.
    pub fn with_attribute<'b, I>(mut self, attr: I) -> Self
    where
        I: Into<Attribute<'b>>,
    {
        self.write_attr(attr.into());
        self
    }

    /// Adds additional attributes to this element using an iterator.
    ///
    /// The yielded items must be convertible to [`Attribute`] via `Into`.
    pub fn with_attributes<'b, I>(mut self, attributes: I) -> Self
    where
        I: IntoIterator,
        I::Item: Into<Attribute<'b>>,
    {
        let mut iter = attributes.into_iter();
        if let Some(attr) = iter.next() {
            self.write_attr(attr.into());
            self.start_tag.extend_attributes(iter);
        }
        self
    }

    /// Pushes a new line inside the element between attributes. Does nothing if
    /// [`Writer`] was created without indentation support.
    ///
    /// # Examples
    ///
    /// ```
    /// use oxixml_xml::writer::Writer;
    ///
    /// let mut writer = Writer::new_with_indent(Vec::new(), b' ', 2);
    /// writer
    ///   .create_element("element")
    ///     .with_attribute(("first", "1"))
    ///     .with_attribute(("second", "2"))
    ///     .new_line()
    ///     .with_attributes([("third", "3"), ("fourth", "4")])
    ///     .write_empty()
    ///     .expect("write");
    ///
    /// assert_eq!(
    ///     std::str::from_utf8(&writer.into_inner()).expect("utf-8"),
    ///     "<element first=\"1\" second=\"2\"\n         third=\"3\" fourth=\"4\"/>",
    /// );
    /// ```
    pub fn new_line(mut self) -> Self {
        if let Some(i) = self.writer.indent.as_mut() {
            match self.state {
                // `.new_line()` called just after `.create_element()`. Use element
                // indent to additionally indent attributes.
                AttributeIndent::NoneAttributesWritten => {
                    self.state = AttributeIndent::WriteConfigured(i.indent_size)
                }
                AttributeIndent::WriteSpaces(_) => {}
                // `.new_line()` called when `.with_attribute()` was called at least
                // once. The spaces should be used to indent.
                AttributeIndent::Spaces(indent) => {
                    self.state = AttributeIndent::WriteSpaces(indent)
                }
                AttributeIndent::WriteConfigured(_) => {}
                // `.new_line()` called when `.with_attribute()` was called at least
                // once. The configured indent characters should be used to indent.
                AttributeIndent::Configured(indent) => {
                    self.state = AttributeIndent::WriteConfigured(indent)
                }
            }
            self.start_tag.push_newline();
        }
        self
    }

    /// Writes an attribute and maintains indentation state.
    fn write_attr<'b>(&mut self, attr: Attribute<'b>) {
        if let Some(i) = self.writer.indent.as_mut() {
            // Save the indent that we should use next time `.new_line()` is called.
            self.state = match self.state {
                // Neither `.new_line()` nor `.with_attribute()` called yet. If a
                // newline inside attributes is later requested, indent them by the
                // length of the tag name, +1 for `<` and +1 for one space.
                AttributeIndent::NoneAttributesWritten => {
                    self.start_tag.push_attribute(attr);
                    AttributeIndent::Spaces(self.start_tag.name().as_ref().len() + 2)
                }
                // Indent was requested by a previous `.new_line()`; write it. The
                // newline was already written.
                AttributeIndent::WriteSpaces(indent) => {
                    if self.spaces.len() < indent {
                        self.spaces.resize(indent, b' ');
                    }
                    self.start_tag.push_indent(&self.spaces[..indent]);
                    self.start_tag.push_attr(attr);
                    AttributeIndent::Spaces(indent)
                }
                // `.new_line()` was not called, but `.with_attribute()` was. Use
                // the previously calculated indent.
                AttributeIndent::Spaces(indent) => {
                    self.start_tag.push_attribute(attr);
                    AttributeIndent::Spaces(indent)
                }
                // Indent was requested by a previous `.new_line()`; write it. The
                // newline was already written.
                AttributeIndent::WriteConfigured(indent) => {
                    self.start_tag.push_indent(i.additional(indent));
                    self.start_tag.push_attr(attr);
                    AttributeIndent::Configured(indent)
                }
                // `.new_line()` was not called, but `.with_attribute()` was. Use
                // the previously calculated indent.
                AttributeIndent::Configured(indent) => {
                    self.start_tag.push_attribute(attr);
                    AttributeIndent::Configured(indent)
                }
            };
        } else {
            self.start_tag.push_attribute(attr);
        }
    }
}

impl<'a, W: Write> ElementWriter<'a, W> {
    /// Writes some text inside the current element.
    pub fn write_text_content(self, text: BytesText) -> io::Result<&'a mut Writer<W>> {
        self.writer
            .write_event(Event::Start(self.start_tag.borrow()))?;
        self.writer.write_event(Event::Text(text))?;
        self.writer
            .write_event(Event::End(self.start_tag.to_end()))?;
        Ok(self.writer)
    }

    /// Writes a CDATA event `<![CDATA[...]]>` inside the current element.
    pub fn write_cdata_content(self, text: BytesCData) -> io::Result<&'a mut Writer<W>> {
        self.writer
            .write_event(Event::Start(self.start_tag.borrow()))?;
        self.writer.write_event(Event::CData(text))?;
        self.writer
            .write_event(Event::End(self.start_tag.to_end()))?;
        Ok(self.writer)
    }

    /// Writes a processing instruction `<?...?>` inside the current element.
    pub fn write_pi_content(self, pi: BytesPI) -> io::Result<&'a mut Writer<W>> {
        self.writer
            .write_event(Event::Start(self.start_tag.borrow()))?;
        self.writer.write_event(Event::PI(pi))?;
        self.writer
            .write_event(Event::End(self.start_tag.to_end()))?;
        Ok(self.writer)
    }

    /// Writes an empty (self-closing) tag.
    pub fn write_empty(self) -> io::Result<&'a mut Writer<W>> {
        self.writer.write_event(Event::Empty(self.start_tag))?;
        Ok(self.writer)
    }

    /// Creates a new scope for writing XML inside the current element.
    pub fn write_inner_content<F>(self, closure: F) -> io::Result<&'a mut Writer<W>>
    where
        F: FnOnce(&mut Writer<W>) -> io::Result<()>,
    {
        self.writer
            .write_event(Event::Start(self.start_tag.borrow()))?;
        closure(self.writer)?;
        self.writer
            .write_event(Event::End(self.start_tag.to_end()))?;
        Ok(self.writer)
    }
}

/// Indentation configuration and state used by [`Writer`] when pretty-printing.
#[derive(Debug, Clone)]
pub(crate) struct Indentation {
    /// Whether the next markup event should be preceded by a line break and
    /// indentation. Toggled off after [`Text`](Event::Text) and
    /// [`CData`](Event::CData) events so that text stays on the same line.
    should_line_break: bool,
    /// The byte used for indentation (e.g. `b' '` or `b'\t'`).
    indent_char: u8,
    /// How many `indent_char`s make up a single level of indentation.
    indent_size: usize,
    /// A cache of the bytes used for indentation.
    indents: Vec<u8>,
    /// The current amount of indentation, in bytes.
    current_indent_len: usize,
}

impl Indentation {
    pub(crate) fn new(indent_char: u8, indent_size: usize) -> Self {
        Self {
            should_line_break: false,
            indent_char,
            indent_size,
            indents: vec![indent_char; 128],
            current_indent_len: 0, // invariant: must remain <= indents.len()
        }
    }

    /// Increases indentation by one level.
    pub(crate) fn grow(&mut self) {
        self.current_indent_len += self.indent_size;
        self.ensure(self.current_indent_len);
    }

    /// Decreases indentation by one level. Does nothing if the level is already
    /// zero.
    pub(crate) fn shrink(&mut self) {
        self.current_indent_len = self.current_indent_len.saturating_sub(self.indent_size);
    }

    /// Returns the indent string for the current level.
    pub(crate) fn current(&self) -> &[u8] {
        &self.indents[..self.current_indent_len]
    }

    /// Returns the current indent plus an additional indent.
    pub(crate) fn additional(&mut self, additional_indent: usize) -> &[u8] {
        let new_len = self.current_indent_len + additional_indent;
        self.ensure(new_len);
        &self.indents[..new_len]
    }

    fn ensure(&mut self, new_len: usize) {
        if self.indents.len() < new_len {
            self.indents.resize(new_len, self.indent_char);
        }
    }
}

#[cfg(test)]
mod tests;