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::error::RenderError;
13use crate::escape::HtmlEscape;
14use alloc::{boxed::Box, sync::Arc, vec::Vec};
15use core::fmt;
16
17struct RenderBuffer<'a>(&'a mut dyn fmt::Write);
18
19impl fmt::Write for RenderBuffer<'_> {
20    fn write_str(&mut self, text: &str) -> fmt::Result {
21        self.0.write_str(text)
22    }
23}
24
25// ---------------------------------------------------------------------------
26// Escaped interpolation: {+ expr +}
27// ---------------------------------------------------------------------------
28
29/// Wrapper emitted by codegen for `{+ expr +}`.
30#[doc(hidden)]
31pub struct Escaped<'a, T: ?Sized>(pub &'a T);
32
33// Priority 1 (inherent): Hemplate types render directly — output is safe HTML.
34impl<T: Hemplate + ?Sized> Escaped<'_, T> {
35    /// Render a Hemplate component into the buffer (no escaping).
36    #[doc(hidden)]
37    pub fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
38        self.0.render_into(buf)
39    }
40}
41
42/// Fallback for `Display` types in escaped context.
43#[doc(hidden)]
44pub trait EscapedFallback {
45    /// Render a Display value into the buffer with HTML escaping.
46    fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError>;
47}
48
49// Priority 2 (trait): Display types get HTML-escaped.
50impl<T: fmt::Display + ?Sized> EscapedFallback for Escaped<'_, T> {
51    fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
52        use fmt::Write as _;
53        write!(RenderBuffer(buf), "{}", HtmlEscape(self.0))?;
54        Ok(())
55    }
56}
57
58// ---------------------------------------------------------------------------
59// Raw interpolation: {+= expr =+}
60// ---------------------------------------------------------------------------
61
62/// Wrapper emitted by codegen for `{+= expr =+}`.
63#[doc(hidden)]
64pub struct Raw<'a, T: ?Sized>(pub &'a T);
65
66// Priority 1 (inherent): Hemplate types should NOT use raw interpolation.
67// The autoref dispatch means `{+ +}` already calls `render_into` for
68// Hemplate types.  Using `{+= =+}` with a Hemplate type is always a
69// mistake — it bypasses the safe dispatch for no benefit.
70impl<T: Hemplate + ?Sized> Raw<'_, T> {
71    /// Compile-time guard: raw interpolation is not allowed for Hemplate types.
72    #[doc(hidden)]
73    pub fn render_to(&self, _buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
74        panic!(
75            "hemplate: raw interpolation must not be used with Hemplate types. \
76             Use escaped interpolation instead. \
77             This should have been caught at compile time via RawGuard."
78        );
79    }
80}
81
82/// Fallback for `Display` types in raw context.
83#[doc(hidden)]
84pub trait RawFallback {
85    /// Render a Display value into the buffer without escaping.
86    fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError>;
87}
88
89// Priority 2 (trait): Display types output verbatim (no escaping).
90impl<T: fmt::Display + ?Sized> RawFallback for Raw<'_, T> {
91    fn render_to(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
92        use fmt::Write as _;
93        write!(RenderBuffer(buf), "{}", self.0)?;
94        Ok(())
95    }
96}
97
98// ---------------------------------------------------------------------------
99// Raw interpolation guard: compile error for Hemplate types in {+= =+}
100// ---------------------------------------------------------------------------
101
102/// Emitted by codegen before `Raw::render_to` to catch Hemplate types at
103/// compile time.  The inherent impl returns a distinct type that fails the
104/// `let _: () = ...` assignment, producing a clear type-mismatch error
105/// whose type name IS the error message.
106#[doc(hidden)]
107pub struct RawGuard<'a, T: ?Sized>(pub &'a T);
108
109/// Appears in the compiler error when `{+= =+}` is used with a Hemplate type.
110#[doc(hidden)]
111pub struct RawInterpolationNotAllowedForHemplateTypes;
112
113// Priority 1 (inherent): Hemplate types → return the "error message" type.
114impl<T: Hemplate + ?Sized> RawGuard<'_, T> {
115    #[doc(hidden)]
116    pub fn check(&self) -> RawInterpolationNotAllowedForHemplateTypes {
117        RawInterpolationNotAllowedForHemplateTypes
118    }
119}
120
121/// Fallback: Display types pass the guard (no-op).
122#[doc(hidden)]
123pub trait RawGuardFallback {
124    fn check(&self);
125}
126
127impl<T: fmt::Display + ?Sized> RawGuardFallback for RawGuard<'_, T> {
128    #[inline(always)]
129    fn check(&self) {}
130}
131
132// ---------------------------------------------------------------------------
133// Blanket Hemplate impls
134// ---------------------------------------------------------------------------
135
136impl<T: Hemplate + ?Sized> Hemplate for &T {
137    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
138        (*self).render_into(buf)
139    }
140}
141
142impl<T: Hemplate + ?Sized> Hemplate for Box<T> {
143    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
144        (**self).render_into(buf)
145    }
146}
147
148impl<T: Hemplate + ?Sized> Hemplate for Arc<T> {
149    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
150        (**self).render_into(buf)
151    }
152}
153
154impl<T: Hemplate> Hemplate for Option<T> {
155    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
156        if let Some(inner) = self {
157            inner.render_into(buf)?;
158        }
159        Ok(())
160    }
161}
162
163impl<T: Hemplate> Hemplate for Vec<T> {
164    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
165        for item in self {
166            item.render_into(buf)?;
167        }
168        Ok(())
169    }
170}
171
172impl<T: Hemplate> Hemplate for [T] {
173    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
174        for item in self {
175            item.render_into(buf)?;
176        }
177        Ok(())
178    }
179}
180
181#[cfg(test)]
182mod tests {
183    use super::*;
184    use alloc::{string::String, vec};
185
186    // A minimal Hemplate type for testing dispatch
187    struct TestComponent(String);
188
189    impl Hemplate for TestComponent {
190        fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
191            buf.write_str("<b>")?;
192            buf.write_str(&self.0)?;
193            buf.write_str("</b>")?;
194            Ok(())
195        }
196    }
197
198    struct FailingComponent;
199
200    impl Hemplate for FailingComponent {
201        fn render_into(&self, _buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
202            Err(fmt::Error.into())
203        }
204    }
205
206    struct FailingDisplay;
207
208    impl fmt::Display for FailingDisplay {
209        fn fmt(&self, _formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
210            Err(fmt::Error)
211        }
212    }
213
214    fn render_to_string(value: &(impl Hemplate + ?Sized)) -> Result<String, RenderError> {
215        let mut buf = String::new();
216        value.render_into(&mut buf)?;
217        Ok(buf)
218    }
219
220    #[test]
221    fn render_into_accepts_custom_writer() -> Result<(), RenderError> {
222        struct Writer(String);
223        impl fmt::Write for Writer {
224            fn write_str(&mut self, value: &str) -> fmt::Result {
225                self.0.push_str(value);
226                Ok(())
227            }
228        }
229        let mut writer = Writer(String::new());
230        TestComponent("caller-owned".into()).render_into(&mut writer)?;
231        assert_eq!(writer.0, "<b>caller-owned</b>");
232        Ok(())
233    }
234
235    #[test]
236    fn escaped_hemplate_renders_directly() -> Result<(), RenderError> {
237        let comp = TestComponent("hello".into());
238        let mut buf = String::new();
239        Escaped(&comp).render_to(&mut buf)?;
240        assert_eq!(buf, "<b>hello</b>");
241        Ok(())
242    }
243
244    #[test]
245    fn escaped_display_html_escapes() -> Result<(), RenderError> {
246        let text = "<script>alert('xss')</script>";
247        let mut buf = String::new();
248        EscapedFallback::render_to(&Escaped(text), &mut buf)?;
249        assert_eq!(buf, "&lt;script&gt;alert(&#x27;xss&#x27;)&lt;/script&gt;");
250        Ok(())
251    }
252
253    #[test]
254    #[should_panic(expected = "must not be used with Hemplate types")]
255    fn raw_hemplate_panics() {
256        let comp = TestComponent("world".into());
257        let mut buf = String::new();
258        let _ = Raw(&comp).render_to(&mut buf);
259    }
260
261    #[test]
262    fn raw_guard_hemplate_returns_marker_type() {
263        let comp = TestComponent("test".into());
264        // Inherent impl is selected for Hemplate types, returning the marker type.
265        // In codegen, `let _: () = RawGuard(&expr).check()` causes a type mismatch
266        // that prevents compilation of {+= =+} with Hemplate types.
267        let _marker = RawGuard(&comp).check();
268        // If this compiles, the inherent impl was selected (returns marker, not ()).
269        assert_eq!(
270            core::any::type_name_of_val(&_marker),
271            core::any::type_name::<RawInterpolationNotAllowedForHemplateTypes>()
272        );
273    }
274
275    #[test]
276    fn raw_guard_display_is_noop() {
277        let text = "hello";
278        // Trait fallback is selected for Display-only types, returning ().
279        let result: () = RawGuardFallback::check(&RawGuard(text));
280        assert_eq!(result, ());
281    }
282
283    #[test]
284    fn raw_display_no_escaping() -> Result<(), RenderError> {
285        let text = "<b>bold</b>";
286        let mut buf = String::new();
287        RawFallback::render_to(&Raw(text), &mut buf)?;
288        assert_eq!(buf, "<b>bold</b>");
289        Ok(())
290    }
291
292    #[test]
293    fn interpolation_fallbacks_propagate_display_failure() {
294        let mut escaped = String::new();
295        assert!(EscapedFallback::render_to(&Escaped(&FailingDisplay), &mut escaped).is_err());
296        let mut raw = String::new();
297        assert!(RawFallback::render_to(&Raw(&FailingDisplay), &mut raw).is_err());
298    }
299
300    // Blanket Hemplate impls preserve child render order and emptiness.
301
302    #[test]
303    fn option_some_renders() -> Result<(), RenderError> {
304        let comp = Some(TestComponent("yes".into()));
305        assert_eq!(render_to_string(&comp)?, "<b>yes</b>");
306        Ok(())
307    }
308
309    #[test]
310    fn option_none_renders_empty() -> Result<(), RenderError> {
311        let comp: Option<TestComponent> = None;
312        assert_eq!(render_to_string(&comp)?, "");
313        Ok(())
314    }
315
316    #[test]
317    fn vec_renders_all() -> Result<(), RenderError> {
318        let comps = vec![TestComponent("a".into()), TestComponent("b".into())];
319        assert_eq!(render_to_string(&comps)?, "<b>a</b><b>b</b>");
320        Ok(())
321    }
322
323    #[test]
324    fn vec_empty_renders_empty() -> Result<(), RenderError> {
325        let comps: Vec<TestComponent> = vec![];
326        assert_eq!(render_to_string(&comps)?, "");
327        Ok(())
328    }
329
330    #[test]
331    fn box_renders() -> Result<(), RenderError> {
332        let comp: Box<TestComponent> = Box::new(TestComponent("boxed".into()));
333        assert_eq!(render_to_string(&comp)?, "<b>boxed</b>");
334        Ok(())
335    }
336
337    #[test]
338    fn arc_renders() -> Result<(), RenderError> {
339        let comp: Arc<TestComponent> = Arc::new(TestComponent("shared".into()));
340        assert_eq!(render_to_string(&comp)?, "<b>shared</b>");
341        Ok(())
342    }
343
344    #[test]
345    fn ref_renders() -> Result<(), RenderError> {
346        let comp = TestComponent("ref".into());
347        let r: &TestComponent = &comp;
348        assert_eq!(render_to_string(&r)?, "<b>ref</b>");
349        Ok(())
350    }
351
352    #[test]
353    fn slice_renders() -> Result<(), RenderError> {
354        let comps = vec![TestComponent("x".into()), TestComponent("y".into())];
355        assert_eq!(render_to_string(comps.as_slice())?, "<b>x</b><b>y</b>");
356        Ok(())
357    }
358
359    #[test]
360    fn box_dyn_hemplate_renders() -> Result<(), RenderError> {
361        let comp: Box<dyn Hemplate> = Box::new(TestComponent("dyn".into()));
362        assert_eq!(render_to_string(comp.as_ref())?, "<b>dyn</b>");
363        Ok(())
364    }
365
366    #[test]
367    fn references_box_arc_option_vec_and_slices_render() -> Result<(), RenderError> {
368        let value = TestComponent("one".into());
369        assert_eq!(render_to_string(&&value)?, "<b>one</b>");
370        assert_eq!(
371            render_to_string(&Box::new(TestComponent("two".into())))?,
372            "<b>two</b>"
373        );
374        assert_eq!(
375            render_to_string(&Arc::new(TestComponent("three".into())))?,
376            "<b>three</b>"
377        );
378        assert_eq!(
379            render_to_string(&Some(TestComponent("four".into())))?,
380            "<b>four</b>"
381        );
382        assert_eq!(
383            render_to_string(&vec![TestComponent("five".into())])?,
384            "<b>five</b>"
385        );
386        let slice = [TestComponent("six".into())];
387        assert_eq!(render_to_string(&slice[..])?, "<b>six</b>");
388        let dynamic: Box<dyn Hemplate> = Box::new(TestComponent("seven".into()));
389        assert_eq!(render_to_string(dynamic.as_ref())?, "<b>seven</b>");
390        Ok(())
391    }
392
393    #[test]
394    fn blanket_implementations_propagate_child_failure() {
395        let by_ref = &FailingComponent;
396        assert!(render_to_string(&by_ref).is_err());
397        assert!(render_to_string(&Box::new(FailingComponent)).is_err());
398        assert!(render_to_string(&Arc::new(FailingComponent)).is_err());
399        assert!(render_to_string(&Some(FailingComponent)).is_err());
400        assert!(render_to_string(&vec![FailingComponent]).is_err());
401        assert!(render_to_string([FailingComponent].as_slice()).is_err());
402    }
403}