stpl is a plain-Rust-only template library with some neat properties and
stpl there are no magic macros or DSLs, and no clunky
text-files with weird syntax. Everything is just normal, easy
to understand Rust code.
Let's take a look at a real-life example from the pilot project: an HTML base-skeleton template for a Bootstrap-based UI.
It is just a function. There is no magic, no macros, no textfiles involved.
The whole template was formatted with
rustfmt just like a normal Rust code.
The function accepts arguments:
data: Datacontaining information how to "fill the blanks", and
content: Render- sub-template value that will be used as main page content.
The function returns
Render value that can be rendered as a string or bytes, or
composed with other templates. The value is basically a one big tuple
nesting many other
Render is implemented for many standard types,
can be implemented for new types or can be generated using functions/closures.
Users are free to use any Rust language primitives to generate their templates and structure relationship between them in any way that suits them.
stpl generates Rust code and does not invole "runtime parsing",
it supports doing the actual rendering in a
separate process, thus hot-swapping the templates at runtime. This is very
useful for speeding up development.
The basic mechanism is:
- serialize the template data, and send it to a child process
- read the rendered template back from the child
In the child process:
- identify the template to use,
- read the serialized data from the stdio and deserialize it
- render the template and output it to stdout
In this scheme the binary for parent and child processes can be the same
render_dynamic_self) or different (see `render_dynamic).
Using the same binary is more convenient. Using separate binaries requires structuring the project in a certain way, but can greatly improve iteration time.
The following is an exerpt from
Cargo.toml to support dynamic
rendering in a separate binary:
[[bin]] name = "template" path = "src/main_template.rs" [[bin]] name = "webapp" path = "src/main.rs"
These two programs share many modules (eg. templates and data structures),
main_template does not have to include any heavy-duty libraries like
diesel and similar, thus compiles much faster.
In our tests it takes 11.4 secs to build the main webapp in debug mode, while recompiling all templates is much faster:
$ cargo build --bin template Compiling webapp v0.1.0 (file:///home/dpc/lab/rust/webapp/web) Finished dev [unoptimized + debuginfo] target(s) in 1.04 secs
- robust: template generation can reuse any existing code and data structures
- convenient: Rust tooling can work with plain-Rust-templates just
like any other code;
rustfmttakes care of formatting, typos result in normal error messages etc.
- fast: the compiler optimizes the template code to essential logic necessary to write-out the rendered template data to the IO; there is no parsing involved
- fast iteration: with dynamic loading it's possible to reload templates without waiting for Rust compiler to build the whole app
nightly-only: This library relies on some unstable features (mostly
- immature and incomplete: This library is still work in progress, and will mature with time.
You are most probably interested in reading
html module documentation
./playground subdirectory for example usage.
Use to wrap closures with
Exit code used by the dynamic template binary on failure
Exit code used by the deyamic template binary when template key was not found
Exit code used by the dynamic template binary on success
A value that can be rendered - part or a whole template
Rendering logic responsible for string escaping and such.
A whole template that knows how to render itself
Convinience methods for