Skip to main content

typed_handlebars_macros/
lib.rs

1//! The proc-macro half of [`typed-handlebars`](https://docs.rs/typed-handlebars).
2//!
3//! This crate is an implementation detail: it is a `proc-macro` crate, so it cannot re-export the
4//! runtime items the code it generates needs. Depend on `typed-handlebars` instead, which
5//! re-exports these three macros under shorter names and documents them with worked examples:
6//!
7//! | Here                            | What you use            |
8//! |---------------------------------|-------------------------|
9//! | [`typed_handlebars_directory!`] | `typed_handlebars::directory!` |
10//! | [`typed_handlebars_file!`]      | `typed_handlebars::file!`      |
11//! | [`typed_handlebars_str!`]       | `typed_handlebars::str!`       |
12//!
13//! Generated code refers to the runtime crate by whatever name the consumer gave it, so renaming
14//! the dependency is fine.
15
16// The parser and code generator are ordinary safe Rust; the inherited parser carried no unsafe
17// either, and this keeps it that way.
18#![forbid(unsafe_code)]
19#![warn(missing_docs)]
20
21mod assemble;
22mod codegen;
23mod parser;
24
25use crate::assemble::Assembly;
26use crate::parser::block::add_builtins;
27use crate::parser::compiler::{Compiler, Options};
28use crate::parser::context;
29use crate::parser::error::ParseError;
30use proc_macro::TokenStream;
31use quote::{format_ident, quote};
32use std::collections::HashMap;
33use std::fs;
34use std::path::Path;
35use syn::{LitStr, Token, parse::Parse, parse::ParseStream, parse_macro_input};
36use walkdir::WalkDir;
37
38/// The path generated code should use to reach the runtime crate.
39///
40/// A consumer may rename the dependency (`hb = { package = "typed-handlebars" }`), in which case
41/// `::typed_handlebars` does not resolve for them. Asking Cargo what they called it keeps generated
42/// code working without them having to know it needed a particular name.
43fn runtime_crate() -> proc_macro2::TokenStream {
44    match proc_macro_crate::crate_name("typed-handlebars") {
45        Ok(proc_macro_crate::FoundCrate::Name(name)) => {
46            let ident = format_ident!("{}", name);
47            quote! { ::#ident }
48        }
49        // Inside `typed-handlebars` itself, which is how its own tests expand.
50        //
51        // Not `crate`: a doctest is compiled as its own crate that *depends* on
52        // `typed-handlebars`, yet `CARGO_MANIFEST_DIR` still points at this manifest, so
53        // `crate_name` answers `Itself` for it too. `crate::Truthy` would then look for the trait
54        // in the doctest. `extern crate self as typed_handlebars` in the runtime crate makes the
55        // absolute path resolve from inside and outside alike.
56        Ok(proc_macro_crate::FoundCrate::Itself) => quote! { ::typed_handlebars },
57        // Not in the dependency list at all. Emitting the canonical name gives the developer a
58        // "use of undeclared crate" pointing at the right name to add.
59        Err(_) => quote! { ::typed_handlebars },
60    }
61}
62
63/// Rust's keywords, which a Handlebars author has no reason to avoid.
64///
65/// Includes the reserved ones, so a template does not start failing when a future edition takes a
66/// word into use.
67const KEYWORDS: &[&str] = &[
68    "as", "async", "await", "become", "box", "break", "const", "continue", "crate", "do", "dyn",
69    "else", "enum", "extern", "false", "final", "fn", "for", "gen", "if", "impl", "in", "let",
70    "loop", "macro", "match", "mod", "move", "mut", "override", "priv", "pub", "ref", "return",
71    "self", "Self", "static", "struct", "super", "trait", "true", "try", "type", "typeof",
72    "unsafe", "unsized", "use", "virtual", "where", "while", "yield",
73];
74
75/// Turns a name from a template or a filename into a usable Rust identifier.
76///
77/// The person writing `.hbs` files picks these names and has no reason to know what Rust reserves,
78/// so a variable called `type` or a file called `mod.hbs` has to work. Raw identifiers would cover
79/// most of it, but `r#self` and `r#crate` are not legal, so a trailing underscore is used
80/// throughout instead — one rule rather than two, and the setter shows up in autocomplete either
81/// way.
82pub(crate) fn sanitise_ident(name: &str) -> String {
83    let mut out = String::with_capacity(name.len() + 1);
84    for (index, character) in name.chars().enumerate() {
85        if index == 0 && character.is_numeric() {
86            // An identifier cannot start with a digit, but `2col.hbs` is a reasonable file name.
87            out.push('_');
88        }
89        if character.is_alphanumeric() || character == '_' {
90            out.push(character);
91        } else {
92            out.push('_');
93        }
94    }
95    if out.is_empty() {
96        out.push('_');
97    }
98    if KEYWORDS.contains(&out.as_str()) {
99        out.push('_');
100    }
101    out
102}
103
104/// Shortens a path for display, relative to the crate being built.
105///
106/// Absolute paths to a build directory are noise in an error message; `templates/results.hbs` is
107/// what the developer recognises.
108pub(crate) fn relative(path: &str) -> &str {
109    let Ok(root) = std::env::var("CARGO_MANIFEST_DIR") else {
110        return path;
111    };
112    match path.strip_prefix(root.as_str()) {
113        Some(rest) => match rest.trim_start_matches(['/', '\\']) {
114            "" => path,
115            trimmed => trimmed,
116        },
117        None => path,
118    }
119}
120
121/// Renders a template error the way a Handlebars author needs to read it: their file, their line,
122/// and nothing about Rust.
123///
124/// The position is mapped back through the assembly, so an error inside a partial names the
125/// partial's own file rather than wherever it happened to be spliced.
126fn describe(error: &ParseError, assembly: &Assembly) -> String {
127    let position = match error
128        .offset_in(&assembly.text)
129        .and_then(|o| assembly.locate(o))
130    {
131        Some(location) => match &location.path {
132            Some(path) => format!("{}:{}:{}: ", relative(path), location.line, location.column),
133            None => format!("line {}, column {}: ", location.line, location.column),
134        },
135        None => match assembly.path() {
136            Some(path) => format!("{}: ", relative(path)),
137            None => String::new(),
138        },
139    };
140    format!("{}{}", position, error)
141}
142
143/// The name `register_helper!` gives the frame type, and generated code reaches it by.
144///
145/// Fixed rather than configurable because two macro invocations cannot see each other: `str!` has
146/// already decided what to emit by the time `register_helper!` expands, so the only thing the two
147/// can agree on is a name that Rust's own resolution closes over afterwards.
148pub(crate) const FRAME_TYPE: &str = "Frame";
149
150/// Generated code, plus whether the template called a helper.
151struct Generated {
152    tokens: proc_macro2::TokenStream,
153    uses_frame: bool,
154}
155
156fn generate_code_for_content(name: &str, assembly: &Assembly) -> Result<Generated, String> {
157    let content = &assembly.text;
158    let template_name = sanitise_ident(name);
159    // Everything a template generates lives in a module of its own, so a template with a `rows`
160    // list cannot collide with a template called `rows_item`, and the names stay readable.
161    let module_name = format_ident!("{}", template_name);
162    let struct_name = format_ident!("Vars");
163
164    let mut block_map = HashMap::new();
165    add_builtins(&mut block_map);
166
167    // The template states its own contract; read it before generating anything.
168    let context = context::build(content).map_err(|e| describe(&e, assembly))?;
169    let runtime = runtime_crate();
170
171    let options = Options {
172        root_var_name: Some("self"),
173        write_var_name: "f",
174        runtime: runtime.to_string(),
175    };
176    let compiler = Compiler::new(options, block_map);
177    let rust_code = compiler
178        .compile(content)
179        .map_err(|e| describe(&e, assembly))?;
180
181    // A template that calls a helper needs the frame — the type `register_helper!` named — passed
182    // in beside the data, and one that calls none never mentions it. The asymmetry is the point:
183    // adding `{{ t "…" }}` to a template stops its call sites compiling until they say which frame
184    // to render against, exactly as adding a variable does. Only compiling the template says which
185    // it is, so the types are generated after that rather than before.
186    let uses_frame = rust_code.uses_frame;
187    let frame = if uses_frame {
188        let frame_var = format_ident!("{}", crate::parser::compiler::FRAME_VAR);
189        let frame_type = format_ident!("{}", FRAME_TYPE);
190        codegen::FrameTokens {
191            param: quote! { #frame_var: &super::#frame_type },
192            argument: quote! { #frame_var },
193        }
194    } else {
195        codegen::FrameTokens::default()
196    };
197    let frame_param = &frame.param;
198    let frame_argument = &frame.argument;
199
200    let types = codegen::generate(&context, &runtime, &frame);
201    let render_body: proc_macro2::TokenStream = rust_code.code.parse().map_err(|_| {
202        // Reaching here means the parser accepted something code generation could not express.
203        // That is a bug in this crate rather than in the template, so say so.
204        format!(
205            "{}internal error: typed-handlebars generated invalid Rust for this template. \
206             Please report it at https://github.com/paultuckey/typed-handlebars/issues",
207            assembly
208                .path()
209                .map(|path| format!("{}: ", relative(path)))
210                .unwrap_or_default()
211        )
212    })?;
213
214    let codegen::Types {
215        nested,
216        builder,
217        params,
218        method_params,
219        predicates,
220        declarations,
221    } = types;
222
223    // Every bound in the subtree lives on the render methods rather than on the type, so that the
224    // type stays plain enough to be written as a struct literal. See `codegen`.
225    let where_clause = codegen::where_clause(&predicates);
226
227    // Generated items carry documentation so that a consumer denying `missing_docs` needs no
228    // `#[allow]`, and so IDE autocomplete says what each setter is for.
229    let module_doc = format!("Types generated from the `{}` template.", template_name);
230    let struct_doc = format!(
231        "Every variable the `{}` template uses. Write it as a struct literal, or reach for \
232         [`builder()`] when you do not have them all.",
233        template_name
234    );
235
236    // A template with no variables at all has no fields to name, and a unit struct is a shorter
237    // thing to write than an empty pair of braces.
238    let struct_def = if declarations.is_empty() {
239        quote! {
240            #[doc = #struct_doc]
241            pub struct #struct_name;
242        }
243    } else {
244        quote! {
245            #[doc = #struct_doc]
246            pub struct #struct_name<#(#params),*> {
247                #(#declarations),*
248            }
249        }
250    };
251
252    // Every file that went into this template, partials included, so editing any of them triggers
253    // a rebuild of the code generated from it.
254    let includes = &assembly.includes;
255    let include_bytes_stmt = quote! {
256        #(const _: &[u8] = ::core::include_bytes!(#includes);)*
257    };
258
259    let module = quote! {
260        #[doc = #module_doc]
261        pub mod #module_name {
262        #include_bytes_stmt
263
264        #(#nested)*
265
266        #builder
267
268        #struct_def
269
270        impl<#(#params),*> #struct_name<#(#params),*> {
271            /// Writes the template into any sink — a `String`, a response buffer, anything
272            /// implementing `fmt::Write`.
273            ///
274            /// This is where the rendering actually happens; `render` is a convenience over it.
275            pub fn render_to<#(#method_params),*>(
276                &self,
277                f: &mut impl ::core::fmt::Write,
278                #frame_param
279            ) -> ::core::fmt::Result
280            #where_clause
281            {
282                // Written values go through `Render`, which generated code reaches by method
283                // syntax so that method lookup can step through the references a loop body holds.
284                // Anonymous, so it can never collide with a name from the template.
285                #[allow(unused_imports)]
286                use #runtime::{Length as _, RenderExt as _};
287                // A template with no variables writes nothing, so the sink can go unused.
288                let _ = &f;
289                #render_body
290                ::core::result::Result::Ok(())
291            }
292
293            /// Renders the template to a new `String`.
294            pub fn render<#(#method_params),*>(&self, #frame_param) -> ::std::string::String
295            #where_clause
296            {
297                let mut out = ::std::string::String::new();
298                // Writing into a `String` cannot fail, so there is no error to propagate.
299                let _ = self.render_to(&mut out, #frame_argument);
300                out
301            }
302        }
303        }
304    };
305
306    Ok(Generated {
307        tokens: module,
308        uses_frame,
309    })
310}
311
312fn generate_code_for_file(path: &Path, partials: &Path) -> Result<Generated, String> {
313    let path_str = path.to_string_lossy();
314    let file_stem = match path.file_stem() {
315        Some(stem) => stem.to_string_lossy(),
316        None => return Err(format!("{}: not a usable template file name", path_str)),
317    };
318    let content = fs::read_to_string(path)
319        .map_err(|e| format!("{}: could not be read: {}", relative(&path_str), e))?;
320    let assembly = Assembly::build(&content, Some(&path_str), Some(partials))
321        .map_err(|e| format!("{}: {}", relative(&path_str), e))?;
322    generate_code_for_content(&file_stem, &assembly)
323}
324
325struct StrInput {
326    name: LitStr,
327    content: LitStr,
328}
329
330impl Parse for StrInput {
331    fn parse(input: ParseStream) -> syn::Result<Self> {
332        let name: LitStr = input.parse()?;
333        input.parse::<Token![,]>()?;
334        let content: LitStr = input.parse()?;
335        // A trailing comma is allowed, so the template can sit on its own line.
336        if input.peek(Token![,]) {
337            input.parse::<Token![,]>()?;
338        }
339        Ok(StrInput { name, content })
340    }
341}
342
343/// Templates grouped the way the directory groups them.
344#[derive(Default)]
345struct Tree {
346    templates: Vec<proc_macro2::TokenStream>,
347    children: std::collections::BTreeMap<String, Tree>,
348    /// Whether anything in this subtree calls a helper, and so needs `Frame` reachable from here.
349    uses_frame: bool,
350}
351
352impl Tree {
353    fn insert(&mut self, branch: &[String], generated: Generated) {
354        self.uses_frame |= generated.uses_frame;
355        match branch.split_first() {
356            None => self.templates.push(generated.tokens),
357            Some((head, rest)) => self
358                .children
359                .entry(head.clone())
360                .or_default()
361                .insert(rest, generated),
362        }
363    }
364
365    fn emit(&self) -> proc_macro2::TokenStream {
366        let templates = &self.templates;
367        let children = self.children.iter().map(|(name, child)| {
368            let ident = format_ident!("{}", crate::sanitise_ident(name));
369            let doc = format!("Templates from the `{}` directory.", name);
370            let inner = child.emit();
371            // A template reaches the frame as `super::Frame`, so every directory between it and
372            // the module `register_helper!` was invoked in has to pass the name along. Carrying it
373            // one level at a time keeps the templates themselves free of any depth arithmetic.
374            let frame = child.uses_frame.then(|| {
375                let frame_type = format_ident!("{}", FRAME_TYPE);
376                quote! { #[allow(unused_imports)] use super::#frame_type; }
377            });
378            quote! {
379                #[doc = #doc]
380                pub mod #ident {
381                    #frame
382                    #inner
383                }
384            }
385        });
386        quote! {
387            #(#templates)*
388            #(#children)*
389        }
390    }
391}
392
393// Documented on the re-export in the runtime crate, where the examples can actually run. Docs
394// here would be concatenated onto those by `#[doc(inline)]`, so they are deliberately absent.
395#[allow(missing_docs)]
396#[proc_macro]
397pub fn typed_handlebars_directory(input: TokenStream) -> TokenStream {
398    let dir_lit = parse_macro_input!(input as LitStr);
399    let dir_str = dir_lit.value();
400
401    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set");
402    let root_path = Path::new(&manifest_dir).join(&dir_str);
403
404    if !root_path.exists() {
405        return syn::Error::new(
406            dir_lit.span(),
407            format!("Directory not found: {:?}", root_path),
408        )
409        .to_compile_error()
410        .into();
411    }
412
413    let mut tree = Tree::default();
414    let mut errors = Vec::new();
415
416    for entry in WalkDir::new(&root_path).sort_by_file_name() {
417        let entry = match entry {
418            Ok(e) => e,
419            Err(_) => continue,
420        };
421
422        let path = entry.path();
423        if !path.is_file() || path.extension().is_none_or(|ext| ext != "hbs") {
424            continue;
425        }
426
427        // The directory layout is something the template author expressed, so mirror it as modules
428        // rather than flattening it — `templates/admin/row.hbs` becomes `templates::admin::row`.
429        let branch = match path
430            .parent()
431            .and_then(|dir| dir.strip_prefix(&root_path).ok())
432        {
433            Some(relative) => relative
434                .components()
435                .map(|c| c.as_os_str().to_string_lossy().to_string())
436                .collect(),
437            None => Vec::new(),
438        };
439
440        // One broken template reports itself and the rest still compile, so a single typo
441        // doesn't bury the whole directory in errors.
442        match generate_code_for_file(path, &root_path) {
443            Ok(generated) => tree.insert(&branch, generated),
444            Err(message) => {
445                errors.push(syn::Error::new(dir_lit.span(), message).to_compile_error())
446            }
447        }
448    }
449
450    let templates = tree.emit();
451    let expanded = quote! {
452        #(#errors)*
453        #templates
454    };
455
456    TokenStream::from(expanded)
457}
458
459// Documented on the re-export in the runtime crate — see `typed_handlebars_directory` above.
460#[allow(missing_docs)]
461#[proc_macro]
462pub fn typed_handlebars_file(input: TokenStream) -> TokenStream {
463    let file_lit = parse_macro_input!(input as LitStr);
464    let file_str = file_lit.value();
465
466    let manifest_dir = std::env::var("CARGO_MANIFEST_DIR").expect("CARGO_MANIFEST_DIR not set");
467    let path = Path::new(&manifest_dir).join(&file_str);
468
469    if !path.exists() {
470        return syn::Error::new(file_lit.span(), format!("File not found: {:?}", path))
471            .to_compile_error()
472            .into();
473    }
474
475    let partials = path.parent().unwrap_or(Path::new(".")).to_path_buf();
476    let expanded = match generate_code_for_file(&path, &partials) {
477        Ok(generated) => generated.tokens,
478        Err(message) => {
479            return syn::Error::new(file_lit.span(), message)
480                .to_compile_error()
481                .into();
482        }
483    };
484
485    TokenStream::from(expanded)
486}
487
488// Documented on the re-export in the runtime crate — see `typed_handlebars_directory` above.
489#[allow(missing_docs)]
490#[proc_macro]
491pub fn typed_handlebars_register_helper(input: TokenStream) -> TokenStream {
492    let frame = parse_macro_input!(input as syn::Type);
493    let frame_type = format_ident!("{}", FRAME_TYPE);
494    let doc = "The frame every template in this module renders against — the value passed to \
495               `render` beside the data, and the type a helper call resolves its method on.";
496    // Nothing here checks that the type has the methods the templates call. A proc macro sees
497    // tokens rather than types, so it could not; the generated call is what checks, and rustc's
498    // own "no method named `t` found for struct `Ctx`" names both the helper and the frame.
499    TokenStream::from(quote! {
500        #[doc = #doc]
501        #[allow(dead_code)]
502        pub type #frame_type = #frame;
503    })
504}
505
506// Documented on the re-export in the runtime crate — see `typed_handlebars_directory` above.
507#[allow(missing_docs)]
508#[proc_macro]
509pub fn typed_handlebars_str(input: TokenStream) -> TokenStream {
510    let StrInput { name, content } = parse_macro_input!(input as StrInput);
511    // A `str!` template has no directory, so it has nowhere to resolve partials from.
512    let assembled = Assembly::build(&content.value(), None, None)
513        .and_then(|assembly| generate_code_for_content(&name.value(), &assembly));
514    let expanded = match assembled {
515        Ok(generated) => generated.tokens,
516        Err(message) => {
517            return syn::Error::new(content.span(), message)
518                .to_compile_error()
519                .into();
520        }
521    };
522
523    TokenStream::from(expanded)
524}