Struct Buffer

pub struct Buffer<C: Context = Node> { /* private fields */ }

Available on crate feature alloc only.

The buffer used for rendering HTML.

This is a wrapper around String that prevents accidental XSS vulnerabilities by disallowing direct rendering of raw HTML into the buffer without clearly indicating the risk of doing so.

Implementations

impl Buffer

pub fn new() -> Self

Creates a new, empty Buffer.

pub fn dangerously_from_string(string: String) -> Self

Creates a new Buffer from the given String.

It is recommended to add a // XSS SAFETY comment above the usage of this function to indicate why the original string is safe to be used as raw HTML.

pub fn dangerously_from_string_mut(string: &mut String) -> &mut Self

Creates a new &mut Buffer from the given &mut String.

It is recommended to add a // XSS SAFETY comment above the usage of this function to indicate why the original string is safe to be used as raw HTML.

pub fn as_attribute_buffer(&mut self) -> &mut AttributeBuffer

Converts this into an &mut AttributeBuffer.

pub fn rendered(self) -> Rendered<String>

Renders the buffer to a Rendered<String>.

impl<C: Context> Buffer<C>

pub fn dangerously_get_string(&mut self) -> &mut String

Gets a mutable reference to the inner String.

For Buffer<Node> (a.k.a. Buffer) writes, the caller must push complete HTML nodes. If rendering string-like types, the pushed contents must escape & to &, < to <, and > to >.

For Buffer<AttributeValue> (a.k.a. AttributeBuffer) writes, the caller must push attribute values which will eventually be surrounded by double quotes. The pushed contents must escape & to &, < to <, > to >, and " to ".

This should only be needed in very specific cases, such as manually constructing raw HTML, usually within a Renderable::render_to implementation.

It is recommended to add a // XSS SAFETY comment above the usage of this method to indicate why it is safe to directly write to the underlying buffer.

Example

use hypertext::{Buffer, prelude::*};

fn get_some_html() -> String {
    // get html from some source, such as a CMS
    "<h2>Some HTML from the CMS</h2>".into()
}

let mut buffer = Buffer::new();

maud! {
    h1 { "My Document!" }
}
.render_to(&mut buffer);

// XSS SAFETY: The CMS sanitizes the HTML before returning it.
buffer.dangerously_get_string().push_str(&get_some_html());

assert_eq!(
    buffer.rendered().as_inner(),
    "<h1>My Document!</h1><h2>Some HTML from the CMS</h2>"
)

Trait Implementations

impl<C: Clone + Context> Clone for Buffer<C>

fn clone(&self) -> Buffer<C>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Buffer

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<C: Default + Context> Default for Buffer<C>

fn default() -> Buffer<C>

Returns the “default value” for a type.

impl<C: PartialEq + Context> PartialEq for Buffer<C>

fn eq(&self, other: &Buffer<C>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<C: Eq + Context> Eq for Buffer<C>

impl<C: Context> StructuralPartialEq for Buffer<C>