Split into separate Html and HtmlBuilder types

Author: lambda-fairy

maud/src/lib.rs

@@ -46,69 +46,69 @@ mod escape;
 pub trait ToHtml {
     /// Creates an HTML representation of `self`.
     fn to_html(&self) -> Html {
-        let mut buffer = Html::default();
-        self.push_html_to(&mut buffer);
-        buffer
+        let mut builder = HtmlBuilder::new();
+        self.push_html_to(&mut builder);
+        builder.finalize()
     }
 
     /// Appends an HTML representation of `self` to the given buffer.
     ///
     /// Its default implementation just calls `.to_html()`, but you may
     /// override it with something more efficient.
-    fn push_html_to(&self, buffer: &mut Html) {
-        self.to_html().push_html_to(buffer)
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        self.to_html().push_html_to(builder)
     }
 }
 
 impl ToHtml for str {
-    fn push_html_to(&self, buffer: &mut Html) {
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
         // XSS-Safety: Special characters will be escaped by `escape_to_string`.
-        escape::escape_to_string(self, buffer.as_mut_string_unchecked());
+        escape::escape_to_string(self, builder.as_mut_string_unchecked());
     }
 }
 
 impl ToHtml for String {
-    fn push_html_to(&self, buffer: &mut Html) {
-        str::push_html_to(self, buffer);
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        str::push_html_to(self, builder);
     }
 }
 
 impl<'a> ToHtml for Cow<'a, str> {
-    fn push_html_to(&self, buffer: &mut Html) {
-        str::push_html_to(self, buffer);
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        str::push_html_to(self, builder);
     }
 }
 
 impl<'a> ToHtml for Arguments<'a> {
-    fn push_html_to(&self, buffer: &mut Html) {
-        let _ = buffer.write_fmt(*self);
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        let _ = builder.write_fmt(*self);
     }
 }
 
 impl<'a, T: ToHtml + ?Sized> ToHtml for &'a T {
-    fn push_html_to(&self, buffer: &mut Html) {
-        T::push_html_to(self, buffer);
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        T::push_html_to(self, builder);
     }
 }
 
 impl<'a, T: ToHtml + ?Sized> ToHtml for &'a mut T {
-    fn push_html_to(&self, buffer: &mut Html) {
-        T::push_html_to(self, buffer);
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        T::push_html_to(self, builder);
     }
 }
 
 impl<T: ToHtml + ?Sized> ToHtml for Box<T> {
-    fn push_html_to(&self, buffer: &mut Html) {
-        T::push_html_to(self, buffer);
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        T::push_html_to(self, builder);
     }
 }
 
 macro_rules! impl_to_html_with_display {
     ($($ty:ty)*) => {
         $(
             impl ToHtml for $ty {
-                fn push_html_to(&self, buffer: &mut Html) {
-                    let _ = write!(buffer, "{self}");
+                fn push_html_to(&self, builder: &mut HtmlBuilder) {
+                    let _ = write!(builder, "{self}");
                 }
             }
         )*
@@ -123,9 +123,9 @@ macro_rules! impl_to_html_with_itoa {
     ($($ty:ty)*) => {
         $(
             impl ToHtml for $ty {
-                fn push_html_to(&self, buffer: &mut Html) {
+                fn push_html_to(&self, builder: &mut HtmlBuilder) {
                     // XSS-Safety: The characters '0' through '9', and '-', are HTML safe.
-                    let _ = itoa::fmt(buffer.as_mut_string_unchecked(), *self);
+                    let _ = itoa::fmt(builder.as_mut_string_unchecked(), *self);
                 }
             }
         )*
@@ -179,8 +179,8 @@ impl_to_html_with_itoa! {
 ///
 /// - **I have performance-sensitive rendering code that needs direct
 ///   access to the buffer.**
-///     - Use [`Html::as_mut_string_unchecked`], and ask a security
-///       expert for review.
+///     - Use [`HtmlBuilder::as_mut_string_unchecked`], and ask a
+///       security expert for review.
 ///
 /// - **I have special requirements and the other options don't work for
 ///   me.**
@@ -274,6 +274,75 @@ impl Html {
         }
     }
 
+    /// Exposes the underlying buffer as a `&str`.
+    pub fn as_str(&self) -> &str {
+        &self.inner
+    }
+
+    /// Converts the inner value to a `String`.
+    pub fn into_string(self) -> String {
+        self.inner.into_owned()
+    }
+}
+
+impl ToHtml for Html {
+    fn push_html_to(&self, builder: &mut HtmlBuilder) {
+        // XSS-Safety: `self` is already guaranteed to be trusted HTML.
+        builder.as_mut_string_unchecked().push_str(self.as_str());
+    }
+}
+
+impl From<Html> for String {
+    fn from(html: Html) -> String {
+        html.into_string()
+    }
+}
+
+/// The literal string `<!DOCTYPE html>`.
+///
+/// # Example
+///
+/// A minimal web page:
+///
+/// ```rust
+/// use maud::{DOCTYPE, html};
+///
+/// let page = html! {
+///     (DOCTYPE)
+///     html {
+///         head {
+///             meta charset="utf-8";
+///             title { "Test page" }
+///         }
+///         body {
+///             p { "Hello, world!" }
+///         }
+///     }
+/// };
+/// ```
+pub const DOCTYPE: Html = Html::from_const_unchecked("<!DOCTYPE html>");
+
+/// A partially created fragment of HTML.
+///
+/// Unlike [`Html`], an `HtmlBuilder` might have unclosed elements or
+/// attributes.
+///
+/// This type cannot be constructed by hand. The [`html!`] macro creates
+/// one internally, and passes it to [`ToHtml::push_html_to`].
+#[derive(Clone, Debug)]
+pub struct HtmlBuilder {
+    inner: Cow<'static, str>,
+}
+
+impl HtmlBuilder {
+    /// For internal use only.
+    #[doc(hidden)]
+    pub fn new() -> Self {
+        Self {
+            inner: Cow::Owned(String::new()),
+        }
+    }
+
     /// For internal use only.
     #[doc(hidden)]
     pub fn with_capacity(capacity: usize) -> Self {
@@ -287,11 +356,6 @@ impl Html {
         value.push_html_to(self);
     }
 
-    /// Exposes the underlying buffer as a `&str`.
-    pub fn as_str(&self) -> &str {
-        &self.inner
-    }
-
     /// Exposes the underlying buffer as a `&mut String`.
     ///
     /// This is useful for performance-sensitive use cases that need
@@ -300,12 +364,16 @@ impl Html {
     /// # Example
     ///
     /// ```rust
-    /// use maud::Html;
+    /// use maud::{HtmlBuilder, ToHtml};
     /// # mod base64 { pub fn encode(_: &mut String, _: &[u8]) {} }
     ///
-    /// fn append_base64_to_html(buffer: &mut Html, bytes: &[u8]) {
-    ///     // XSS-Safety: The characters [A-Za-z0-9+/=] are all HTML-safe.
-    ///     base64::encode(buffer.as_mut_string_unchecked(), bytes);
+    /// struct Base64<'a>(&'a [u8]);
+    ///
+    /// impl<'a> ToHtml for Base64<'a> {
+    ///     fn push_html_to(&self, builder: &mut HtmlBuilder) {
+    ///         // XSS-Safety: The characters [A-Za-z0-9+/=] are all HTML-safe.
+    ///         base64::encode(builder.as_mut_string_unchecked(), self.0);
+    ///     }
     /// }
     /// ```
     ///
@@ -323,56 +391,21 @@ impl Html {
         self.inner.to_mut()
     }
 
-    /// Converts the inner value to a `String`.
-    pub fn into_string(self) -> String {
-        self.inner.into_owned()
+    /// For internal use only.
+    #[doc(hidden)]
+    pub fn finalize(self) -> Html {
+        // XSS-Safety: This is called from the `html!` macro, which enforces safety itself.
+        Html::from_unchecked(self.inner)
     }
 }
 
-impl Write for Html {
+impl Write for HtmlBuilder {
     fn write_str(&mut self, text: &str) -> fmt::Result {
         self.push(text);
         Ok(())
     }
 }
 
-impl ToHtml for Html {
-    fn push_html_to(&self, buffer: &mut Html) {
-        // XSS-Safety: `self` is already guaranteed to be trusted HTML.
-        buffer.as_mut_string_unchecked().push_str(self.as_str());
-    }
-}
-
-impl From<Html> for String {
-    fn from(html: Html) -> String {
-        html.into_string()
-    }
-}
-
-/// The literal string `<!DOCTYPE html>`.
-///
-/// # Example
-///
-/// A minimal web page:
-///
-/// ```rust
-/// use maud::{DOCTYPE, html};
-///
-/// let page = html! {
-///     (DOCTYPE)
-///     html {
-///         head {
-///             meta charset="utf-8";
-///             title { "Test page" }
-///         }
-///         body {
-///             p { "Hello, world!" }
-///         }
-///     }
-/// };
-/// ```
-pub const DOCTYPE: Html = Html::from_const_unchecked("<!DOCTYPE html>");
-
 #[cfg(feature = "rocket")]
 mod rocket_support {
     extern crate std;

maud/tests/misc.rs

@@ -1,4 +1,4 @@
-use maud::{self, html, Html, ToHtml};
+use maud::{self, html, Html, HtmlBuilder, ToHtml};
 
 #[test]
 fn issue_13() {
@@ -55,7 +55,7 @@ fn issue_23() {
 fn render_impl() {
     struct R(&'static str);
     impl ToHtml for R {
-        fn push_html_to(&self, buffer: &mut Html) {
+        fn push_html_to(&self, buffer: &mut HtmlBuilder) {
             buffer.push(self.0);
         }
     }

maud_macros/src/lib.rs

@@ -37,8 +37,8 @@ fn expand(input: TokenStream) -> TokenStream {
     let stmts = generate::generate(markups, output_ident.clone());
     quote!({
         extern crate maud;
-        let mut #output_ident = maud::Html::with_capacity(#size_hint);
+        let mut #output_ident = maud::HtmlBuilder::with_capacity(#size_hint);
         #stmts
-        #output_ident
+        maud::HtmlBuilder::finalize(#output_ident)
     })
 }