Skip to main content

hemplate_runtime/
render.rs

1//! Codegen dispatch helpers for `{+ expr +}` and `{+= expr =+}`.
2//!
3//! Uses the autoref specialization pattern so the derive macro can emit
4//! a single call site that does the right thing for both `Hemplate`
5//! types (call `render_into` — output is already HTML) and `Display`
6//! types (HTML-escape via `HtmlEscape`).
7//!
8//! **Users never call these directly.** The derive macro generates all
9//! call sites.
10
11use crate::Hemplate;
12use crate::context::HtmlValue;
13use crate::error::RenderError;
14use crate::escape::HtmlEscape;
15use alloc::{boxed::Box, sync::Arc, vec::Vec};
16use core::fmt;
17
18struct RenderBuffer<'a>(&'a mut dyn fmt::Write);
19
20impl fmt::Write for RenderBuffer<'_> {
21    fn write_str(&mut self, text: &str) -> fmt::Result {
22        self.0.write_str(text)
23    }
24}
25
26// ---------------------------------------------------------------------------
27// Escaped interpolation: {+ expr +}
28// ---------------------------------------------------------------------------
29
30/// Wrapper emitted by codegen for `{+ expr +}`.
31///
32/// `L` is a marker type named after the template position. A value that is
33/// neither `Hemplate` nor `Display` fails with an error that prints this type,
34/// so the message names the template file, line and column.
35#[doc(hidden)]
36pub struct Escaped<'a, T: ?Sized, L = ()>(pub &'a T, pub core::marker::PhantomData<L>);
37
38impl<'a, T: ?Sized> Escaped<'a, T> {
39    /// Wrap a value without a position marker.
40    #[doc(hidden)]
41    pub fn new(value: &'a T) -> Self {
42        Self(value, core::marker::PhantomData)
43    }
44}
45
46// Priority 1 (inherent): Hemplate types render directly — output is safe HTML.
47impl<T: Hemplate + ?Sized, L> Escaped<'_, T, L> {
48    /// Render a Hemplate component into the buffer (no escaping).
49    #[doc(hidden)]
50    pub fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
51        self.0.render_into(buf)
52    }
53}
54
55/// Fallback for `Display` types in escaped context.
56#[doc(hidden)]
57pub trait EscapedFallback {
58    /// Render a Display value into the buffer with HTML escaping.
59    fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError>;
60}
61
62// Priority 2 (trait): Display types get HTML-escaped.
63impl<T: fmt::Display + ?Sized, L> EscapedFallback for Escaped<'_, T, L> {
64    fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
65        use fmt::Write as _;
66        write!(RenderBuffer(buf), "{}", HtmlEscape(self.0))?;
67        Ok(())
68    }
69}
70
71// ---------------------------------------------------------------------------
72// Raw interpolation: {+= expr =+}
73// ---------------------------------------------------------------------------
74
75/// Wrapper emitted by codegen for a whole dynamic attribute `+name="expr"`.
76///
77/// `get` yields the value to render, or `None` to omit the attribute: an
78/// `Option` gives its content, every other value is always present.
79#[doc(hidden)]
80pub struct Present<'a, T: ?Sized>(pub &'a T);
81
82// Priority 1 (inherent): an `Option` attribute is present only when `Some`.
83impl<'a, T> Present<'a, Option<T>> {
84    #[doc(hidden)]
85    pub fn get(&self) -> Option<&'a T> {
86        self.0.as_ref()
87    }
88}
89
90/// Fallback for every non-`Option` value: always present.
91#[doc(hidden)]
92pub trait PresentFallback<'a, T: ?Sized> {
93    fn get(&self) -> Option<&'a T>;
94}
95
96impl<'a, T: ?Sized> PresentFallback<'a, T> for Present<'a, T> {
97    fn get(&self) -> Option<&'a T> {
98        Some(self.0)
99    }
100}
101
102/// Emitted by codegen before raw output to reject components at compile time.
103///
104/// For a `Hemplate` type the inherent `check` returns [`RawComponent`], which
105/// fails the generated [`RawOutputAllowed`] bound with that trait's message;
106/// every other value returns `()`. Components render with `{+ child +}`, never
107/// pre-rendered into raw output.
108#[doc(hidden)]
109pub struct RawGuard<'a, T: ?Sized>(pub &'a T);
110
111/// What the raw-output guard yields for a Hemplate component; it never
112/// satisfies [`RawOutputAllowed`], so `{+= component =+}` does not compile.
113pub struct RawComponent;
114
115impl<T: Hemplate + ?Sized> RawGuard<'_, T> {
116    #[doc(hidden)]
117    pub fn check(&self) -> RawComponent {
118        RawComponent
119    }
120}
121
122/// Fallback: every non-component value passes the guard.
123#[doc(hidden)]
124pub trait RawGuardFallback {
125    fn check(&self);
126}
127
128impl<T: ?Sized> RawGuardFallback for RawGuard<'_, T> {
129    #[inline(always)]
130    fn check(&self) {}
131}
132
133/// Satisfied only by what the raw-output guard returns for non-components.
134#[diagnostic::on_unimplemented(
135    message = "a Hemplate component cannot be inserted as raw output `{{+= .. =+}}`",
136    label = "a component renders itself; raw output would insert it as unchecked markup",
137    note = "compose it with escaped interpolation: `{{+ child +}}`"
138)]
139pub trait RawOutputAllowed {}
140
141#[diagnostic::do_not_recommend]
142impl RawOutputAllowed for () {}
143
144/// Called by codegen for `{+= expr =+}`: insert trusted markup unescaped.
145///
146/// The [`HtmlValue`] bound is the whole check. Hemplate components, strings and
147/// other plain `Display` values do not implement it, so a mistake fails to
148/// compile at this call with the trait's explanation.
149#[doc(hidden)]
150pub fn render_raw<T: HtmlValue + ?Sized>(
151    value: &T,
152    buf: &mut dyn core::fmt::Write,
153) -> Result<(), RenderError> {
154    use fmt::Write as _;
155    write!(RenderBuffer(buf), "{value}")?;
156    Ok(())
157}
158
159// ---------------------------------------------------------------------------
160// Blanket Hemplate impls
161// ---------------------------------------------------------------------------
162
163impl<T: Hemplate + ?Sized> Hemplate for &T {
164    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
165        (*self).render_into(buf)
166    }
167}
168
169impl<T: Hemplate + ?Sized> Hemplate for Box<T> {
170    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
171        (**self).render_into(buf)
172    }
173}
174
175impl<T: Hemplate + ?Sized> Hemplate for Arc<T> {
176    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
177        (**self).render_into(buf)
178    }
179}
180
181impl<T: Hemplate> Hemplate for Option<T> {
182    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
183        if let Some(inner) = self {
184            inner.render_into(buf)?;
185        }
186        Ok(())
187    }
188}
189
190impl<T: Hemplate> Hemplate for Vec<T> {
191    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
192        for item in self {
193            item.render_into(buf)?;
194        }
195        Ok(())
196    }
197}
198
199impl<T: Hemplate> Hemplate for [T] {
200    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
201        for item in self {
202            item.render_into(buf)?;
203        }
204        Ok(())
205    }
206}
207
208#[cfg(test)]
209mod tests {
210    use super::*;
211    use alloc::{string::String, vec};
212
213    // A minimal Hemplate type for testing dispatch
214    struct TestComponent(String);
215
216    impl Hemplate for TestComponent {
217        fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
218            buf.write_str("<b>")?;
219            buf.write_str(&self.0)?;
220            buf.write_str("</b>")?;
221            Ok(())
222        }
223    }
224
225    struct FailingComponent;
226
227    impl Hemplate for FailingComponent {
228        fn render_into(&self, _buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
229            Err(fmt::Error.into())
230        }
231    }
232
233    struct FailingDisplay;
234
235    impl fmt::Display for FailingDisplay {
236        fn fmt(&self, _formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
237            Err(fmt::Error)
238        }
239    }
240
241    fn render_to_string(value: &(impl Hemplate + ?Sized)) -> Result<String, RenderError> {
242        let mut buf = String::new();
243        value.render_into(&mut buf)?;
244        Ok(buf)
245    }
246
247    #[test]
248    fn render_into_accepts_custom_writer() -> Result<(), RenderError> {
249        struct Writer(String);
250        impl fmt::Write for Writer {
251            fn write_str(&mut self, value: &str) -> fmt::Result {
252                self.0.push_str(value);
253                Ok(())
254            }
255        }
256        let mut writer = Writer(String::new());
257        TestComponent("caller-owned".into()).render_into(&mut writer)?;
258        assert_eq!(writer.0, "<b>caller-owned</b>");
259        Ok(())
260    }
261
262    #[test]
263    fn escaped_hemplate_renders_directly() -> Result<(), RenderError> {
264        let comp = TestComponent("hello".into());
265        let mut buf = String::new();
266        Escaped::new(&comp).render_to(&mut buf)?;
267        assert_eq!(buf, "<b>hello</b>");
268        Ok(())
269    }
270
271    #[test]
272    fn escaped_display_html_escapes() -> Result<(), RenderError> {
273        let text = "<script>alert('xss')</script>";
274        let mut buf = String::new();
275        EscapedFallback::render_to(&Escaped::new(text), &mut buf)?;
276        assert_eq!(buf, "&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;");
277        Ok(())
278    }
279
280    #[test]
281    fn raw_trusted_html_is_not_escaped() -> Result<(), RenderError> {
282        let mut buf = String::new();
283        render_raw(&crate::TrustedHtml::new_unchecked("<b>bold</b>"), &mut buf)?;
284        assert_eq!(buf, "<b>bold</b>");
285        Ok(())
286    }
287
288    #[test]
289    fn interpolation_fallbacks_propagate_display_failure() {
290        let mut escaped = String::new();
291        assert!(EscapedFallback::render_to(&Escaped::new(&FailingDisplay), &mut escaped).is_err());
292    }
293
294    // Blanket Hemplate impls preserve child render order and emptiness.
295
296    #[test]
297    fn option_some_renders() -> Result<(), RenderError> {
298        let comp = Some(TestComponent("yes".into()));
299        assert_eq!(render_to_string(&comp)?, "<b>yes</b>");
300        Ok(())
301    }
302
303    #[test]
304    fn option_none_renders_empty() -> Result<(), RenderError> {
305        let comp: Option<TestComponent> = None;
306        assert_eq!(render_to_string(&comp)?, "");
307        Ok(())
308    }
309
310    #[test]
311    fn vec_renders_all() -> Result<(), RenderError> {
312        let comps = vec![TestComponent("a".into()), TestComponent("b".into())];
313        assert_eq!(render_to_string(&comps)?, "<b>a</b><b>b</b>");
314        Ok(())
315    }
316
317    #[test]
318    fn vec_empty_renders_empty() -> Result<(), RenderError> {
319        let comps: Vec<TestComponent> = vec![];
320        assert_eq!(render_to_string(&comps)?, "");
321        Ok(())
322    }
323
324    #[test]
325    fn box_renders() -> Result<(), RenderError> {
326        let comp: Box<TestComponent> = Box::new(TestComponent("boxed".into()));
327        assert_eq!(render_to_string(&comp)?, "<b>boxed</b>");
328        Ok(())
329    }
330
331    #[test]
332    fn arc_renders() -> Result<(), RenderError> {
333        let comp: Arc<TestComponent> = Arc::new(TestComponent("shared".into()));
334        assert_eq!(render_to_string(&comp)?, "<b>shared</b>");
335        Ok(())
336    }
337
338    #[test]
339    fn ref_renders() -> Result<(), RenderError> {
340        let comp = TestComponent("ref".into());
341        let r: &TestComponent = &comp;
342        assert_eq!(render_to_string(&r)?, "<b>ref</b>");
343        Ok(())
344    }
345
346    #[test]
347    fn slice_renders() -> Result<(), RenderError> {
348        let comps = vec![TestComponent("x".into()), TestComponent("y".into())];
349        assert_eq!(render_to_string(comps.as_slice())?, "<b>x</b><b>y</b>");
350        Ok(())
351    }
352
353    #[test]
354    fn box_dyn_hemplate_renders() -> Result<(), RenderError> {
355        let comp: Box<dyn Hemplate> = Box::new(TestComponent("dyn".into()));
356        assert_eq!(render_to_string(comp.as_ref())?, "<b>dyn</b>");
357        Ok(())
358    }
359
360    #[test]
361    fn references_box_arc_option_vec_and_slices_render() -> Result<(), RenderError> {
362        let value = TestComponent("one".into());
363        assert_eq!(render_to_string(&&value)?, "<b>one</b>");
364        assert_eq!(
365            render_to_string(&Box::new(TestComponent("two".into())))?,
366            "<b>two</b>"
367        );
368        assert_eq!(
369            render_to_string(&Arc::new(TestComponent("three".into())))?,
370            "<b>three</b>"
371        );
372        assert_eq!(
373            render_to_string(&Some(TestComponent("four".into())))?,
374            "<b>four</b>"
375        );
376        assert_eq!(
377            render_to_string(&vec![TestComponent("five".into())])?,
378            "<b>five</b>"
379        );
380        let slice = [TestComponent("six".into())];
381        assert_eq!(render_to_string(&slice[..])?, "<b>six</b>");
382        let dynamic: Box<dyn Hemplate> = Box::new(TestComponent("seven".into()));
383        assert_eq!(render_to_string(dynamic.as_ref())?, "<b>seven</b>");
384        Ok(())
385    }
386
387    #[test]
388    fn blanket_implementations_propagate_child_failure() {
389        let by_ref = &FailingComponent;
390        assert!(render_to_string(&by_ref).is_err());
391        assert!(render_to_string(&Box::new(FailingComponent)).is_err());
392        assert!(render_to_string(&Arc::new(FailingComponent)).is_err());
393        assert!(render_to_string(&Some(FailingComponent)).is_err());
394        assert!(render_to_string(&vec![FailingComponent]).is_err());
395        assert!(render_to_string([FailingComponent].as_slice()).is_err());
396    }
397}