tour_parser/lib.rs
1//! Macros for [`tour`] template
2//!
3//! # `tour::Template` Trait
4//!
5//! The goal is to generate `tour::Template` trait implementation.
6//!
7//! All code generation requires [`Template`] struct. To build it, requires [`Metadata`] and
8//! [`File`].
9//!
10//! # [`Metadata`]
11//!
12//! `Metadata` contains template identity that explicitly set by user.
13//!
14//! `Metadata` can be represented by:
15//!
16//! - [`Attribute`], e.g. `#[template(path = "index.html")]`
17//! - [`LayoutTempl`], e.g. `{{ layout "layout.html" }}`
18//! - [`RenderTempl`], e.g. `{{ render "navbar.html" }}`
19//! - [`UseTempl`], e.g. `{{ use "button.html" as Button }}`
20//!
21//! # [`File`]
22//!
23//! `File` contains the actual template content.
24//!
25//! `File` can be created using [`Metadata`].
26//!
27//! # Code generation
28//!
29//! For the `tour::Template` trait, code will be generated for the following methods:
30//!
31//! ## `render_into()`, `render_block_into()` and `contains_block()`
32//!
33//! `render_into()` is the main template rendering logic. Generated code includes:
34//!
35//! - destructured fields, for convenient
36//! - `include_str!()` the template file, to trigger recompile when changed
37//! - static content reparsing for runtime reload
38//! - the main template content rendering
39//!
40//! `render_block_into()` contains the same code but for selected block only.
41//!
42//! Block can be rendered at runtime only when declared with the `pub` keyword.
43//!
44//! `contains_block()` contains basic check whether a block is available to be rendered at runtime.
45//!
46//! ## `size_hint()` and `size_hint_block()`
47//!
48//! `size_hint()` will calculate the lower and upper bounds of the rendered template length.
49//!
50//! `size_hint_block()` is the same but for selected block only.
51//!
52//! Note that currently, size hint calculation does not do any runtime check. So rendered template
53//! may exceed the upper bounds. But lower bounds is pretty much accurate.
54//!
55//! Runtime check like an `if` branch expression that have been evaluated in struct field, can
56//! produce much more accurate size hints. This will be improved in the future.
57//!
58//! For now, size hint is statically calculated. Its better than nothing.
59//!
60//! # External template
61//!
62//! Other external template that is referenced will also be generated.
63//!
64//! External template can be referenced by:
65//!
66//! - [`LayoutTempl`], e.g. `{{ layout "layout.html" }}`
67//! - [`RenderTempl`], e.g. `{{ render "navbar.html" }}`
68//! - [`UseTempl`], e.g. `{{ use "button.html" as Button }}`
69//!
70//! [`tour`]: <https://docs.rs/tour>
71//! [`Template`]: data::Template
72//! [`Metadata`]: metadata::Metadata
73//! [`File`]: file::File
74//! [`Attribute`]: syn::Attribute
75//! [`LayoutTempl`]: syntax::LayoutTempl
76//! [`RenderTempl`]: syntax::RenderTempl
77//! [`UseTempl`]: syntax::UseTempl
78
79pub mod syntax;
80pub mod ast;
81pub mod common;
82
83// ===== Input =====
84pub mod config;
85
86// ===== Data =====
87pub mod metadata;
88pub mod file;
89pub mod data;
90
91// ===== Output =====
92pub mod codegen;
93