#compile-time #macro-derive #run-time #statically-checked

macro no-std boilerplate

Minimal compile-time Rust template engine

12 releases (2 stable)

1.0.1 Aug 17, 2024
1.0.0 Jul 5, 2023
0.2.5 Jan 2, 2023
0.2.4 Dec 28, 2022
0.0.0 Feb 13, 2017

#80 in Template engine

Download history 432/week @ 2024-07-08 451/week @ 2024-07-15 320/week @ 2024-07-22 315/week @ 2024-07-29 269/week @ 2024-08-05 438/week @ 2024-08-12 371/week @ 2024-08-19 383/week @ 2024-08-26 571/week @ 2024-09-02 774/week @ 2024-09-09 515/week @ 2024-09-16 643/week @ 2024-09-23 560/week @ 2024-09-30 601/week @ 2024-10-07 566/week @ 2024-10-14 368/week @ 2024-10-21

2,165 downloads per month
Used in 9 crates (8 directly)

CC0 license

31KB
431 lines

boilerplate


boilerplate is a statically-checked Rust template engine with no runtime dependencies. There are two ways to use boilerplate, boilerplate::boilerplate, a function-like macro, and boilerplate::Boilerplate, a derive macro.

Function-like Macro

use boilerplate::boilerplate;

let foo = true;
let bar: Result<&str, &str> = Ok("yassss");

let output = boilerplate!(
"%% if foo {
Foo was true!
%% }
%% match bar {
%%   Ok(ok) => {
Pretty good: {{ ok }}
%%   }
%%   Err(err) => {
Not so great: {{ err }}
%%   }
%% }
");

assert_eq!(output, "Foo was true!\nPretty good: yassss\n");

Derive Macro

Derive Boilerplate on the type you want to use as a template context:

use boilerplate::Boilerplate;

#[derive(Boilerplate)]
struct MyTemplateTxt {
  foo: bool,
  bar: Result<String, Box<dyn std::error::Error>>,
}

boilerplate template code and interpolations are Rust, so errors are checked at compile time and the template language is easy to learn:

%% if self.foo {
Foo was true!
%% }
%% match &self.bar {
%%   Ok(ok) => {
Pretty good: {{ ok }}
%%   }
%%   Err(err) => {
Not so great: {{ err }}
%%   }
%% }

The Boilerplate macro provides a Display implementation, so you can instantiate a template context and convert it to a string:

let rendered = MyTemplateTxt { foo: true, bar: Ok("hello".into()) }.to_string();

Or use it in a format string:

println!("The output is: {}", MyTemplateTxt { foo: false, bar: Err("hello".into()) });

boilerplate's implementation is exceedingly simple. Try using cargo-expand to expand the Boilerplate macro and inspect derived Display implementations and debug template issues.

Quick Start

Add boilerplate to your project's Cargo.toml:

[dependencies]
boilerplate = "*"

Create a template in templates/my-template.txt:

Foo is {{self.n}}!

Define, instantiate, and render the template context:

use boilerplate::Boilerplate;

#[derive(Boilerplate)]
struct MyTemplateTxt {
  n: u32,
}

assert_eq!(MyTemplateTxt  { n: 10 }.to_string(), "Foo is 10!\n");

Examples

See the docs for more information and examples.

Dependencies

~0.8–1.3MB
~29K SLoC