Skip to main content

hemplate_runtime/
lib.rs

1//! hemplate-runtime: parser-free rendering contract for hemplate templates.
2//!
3//! This crate contains only the symbols needed to render a generated hemplate
4//! template on a target device. It has no parser or proc-macro dependencies,
5//! so it compiles for constrained targets such as `wasm32-unknown-unknown`.
6//!
7//! Applications normally use the `hemplate` facade crate, which re-exports this
8//! runtime API and optionally enables the `derive` feature for
9//! `#[derive(Hemplate)]`.
10
11#![no_std]
12#![warn(missing_docs)]
13
14extern crate alloc;
15
16use alloc::string::String;
17
18#[cfg(test)]
19extern crate std;
20
21/// Attribute contexts and the typed values that may enter them.
22pub mod context;
23/// Error types.
24pub mod error;
25/// HTML escape utility.
26pub mod escape;
27/// Typed values for HTML's enumerated `hidden` attribute.
28pub mod hidden;
29/// Codegen dispatch helpers for interpolation.
30pub mod render;
31
32pub use context::{
33    AnimationContext, AnimationValue, Context, Descriptor, DocumentContext, DocumentValue,
34    HtmlContext, HtmlValue, NavigationContext, NavigationValue, ResourceContext, ResourceValue,
35    ScriptContext, ScriptValue, Srcset, SrcsetContext, SrcsetValue, StyleContext, StyleValue,
36    Trusted, TrustedAnimation, TrustedDocument, TrustedHtml, TrustedNavigation, TrustedResource,
37    TrustedScript, TrustedSrcset, TrustedStyle, TrustedUrl, Url, UrlContext, UrlError, UrlValue,
38};
39pub use error::RenderError;
40pub use escape::HtmlEscape;
41pub use hidden::{BooleanAttribute, HiddenAttribute, HiddenValue};
42
43/// Trait for types that can render themselves as an HTML string.
44///
45/// `Display` is NOT a supertrait — `Hemplate` types produce safe HTML,
46/// while `Display` types produce text that needs escaping. The derive
47/// macro generates a `Hemplate` impl; it does not generate `Display`.
48/// `render_into` is the required method, while `render` is a top-level
49/// convenience that allocates one output string.
50pub trait Hemplate {
51    /// Render this template into the provided buffer.
52    fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError>;
53
54    /// Estimated output bytes used to pre-size a rendering buffer.
55    ///
56    /// Manual implementations may keep the conservative default. Derived templates use their
57    /// static source length, which avoids repeated growth without promising an exact output size.
58    fn size_hint(&self) -> usize {
59        0
60    }
61
62    /// Render this template to a new string.
63    fn render(&self) -> Result<String, RenderError> {
64        let mut buf = String::with_capacity(self.size_hint());
65        self.render_into(&mut buf)?;
66        Ok(buf)
67    }
68}
69
70#[cfg(test)]
71mod tests {
72    use super::*;
73
74    struct Empty;
75
76    impl Hemplate for Empty {
77        fn render_into(&self, _buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
78            Ok(())
79        }
80    }
81
82    struct Text;
83
84    impl Hemplate for Text {
85        fn render_into(&self, buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
86            buf.write_str("rendered")?;
87            Ok(())
88        }
89    }
90
91    struct Failing;
92
93    impl Hemplate for Failing {
94        fn render_into(&self, _buf: &mut dyn core::fmt::Write) -> Result<(), RenderError> {
95            Err(core::fmt::Error.into())
96        }
97    }
98
99    #[test]
100    fn manual_implementation_defaults_to_no_size_hint() {
101        assert_eq!(Empty.size_hint(), 0);
102    }
103
104    #[test]
105    fn render_returns_generated_output_and_propagates_failure() -> Result<(), RenderError> {
106        assert_eq!(Text.render()?, "rendered");
107        assert!(Failing.render().is_err());
108        Ok(())
109    }
110}