Skip to main content

hemplate/
lib.rs

1//! hemplate: facade crate for the hemplate template language.
2//!
3//! `hemplate-runtime` is always available. The default `host` feature exposes
4//! AST/build APIs, while the independent `derive` feature exposes
5//! `#[derive(Hemplate)]`. Constrained targets can disable defaults and enable
6//! only `derive`, keeping parser and Tree-sitter dependencies host-only.
7//!
8//! Dynamic native HTML Boolean attributes require a `bool`: false omits the
9//! attribute, true emits its name. Strings such as `"false"` are not accepted.
10//! Global HTML Booleans also apply to custom and unknown HTML elements.
11//!
12//! HTML `+hidden` is different: it binds an enumerated attribute using
13//! [`HiddenAttribute`]. Boolean false omits it, true emits its name, and string
14//! states (including `"until-found"` and `"false"`) remain escaped values.
15//! References forward these semantics. Generic templates must require
16//! `HiddenAttribute`, not just `Display`. Foreign content keeps ordinary escaped
17//! value interpolation; ambiguous namespaces reject Boolean and `+hidden`
18//! bindings. Use ordinary `hidden="{+ value +}"` for purely textual values there.
19//!
20//! Escaping protects text, not attributes the browser reads as code. A plain
21//! value interpolated into `on*`, `style`, `srcdoc`, a script or stylesheet URL,
22//! or as the whole value of a URL attribute does not compile; use
23//! [`Url::parse`], a type implementing the context's trait ([`UrlValue`],
24//! [`ScriptValue`], ...), or an explicit [`Trusted`] value. Fixed text that
25//! settles a URL's destination (`href="/users/{+ id +}"`) takes plain values.
26//! See the repository README, "Untrusted values and attribute contexts".
27//!
28//! ```compile_fail
29//! use hemplate::Hemplate;
30//! // templates/boolean_attrs.heml includes <input +checked="self.enabled">.
31//! #[derive(Hemplate)]
32//! struct BooleanAttrs {
33//!     enabled: &'static str,
34//!     value: &'static str,
35//!     hidden: bool,
36//! }
37//! impl BooleanAttrs {
38//!     fn next_hidden(&self) -> &bool { &self.hidden }
39//! }
40//! ```
41//!
42//! A generic `Display` bound cannot silently stringify a Boolean hidden value:
43//!
44//! ```compile_fail,E0277
45//! use hemplate::{HiddenAttribute, HiddenValue};
46//! fn hidden_state<T: core::fmt::Display>(value: &T) -> HiddenValue<'_> {
47//!     HiddenAttribute::hidden_value(value)
48//! }
49//! ```
50
51#![warn(missing_docs)]
52
53/// Stable runtime path used by derive-generated code.
54#[doc(hidden)]
55pub mod __runtime {
56    pub use hemplate_runtime::*;
57}
58
59pub use hemplate_runtime::*;
60
61#[cfg(feature = "host")]
62pub use hemplate_core::{ast, BuildError, ExtractionError, ParseError};
63
64#[cfg(feature = "derive")]
65pub use hemplate_derive::Hemplate;