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

macro no-std boilerplate

Minimal compile-time Rust template engine

11 releases (1 stable)

1.0.0 Jul 5, 2023
0.2.5 Jan 2, 2023
0.2.4 Dec 28, 2022
0.2.1 Oct 4, 2022
0.0.0 Feb 13, 2017

#394 in Template engine

Download history 392/week @ 2023-11-23 454/week @ 2023-11-30 307/week @ 2023-12-07 504/week @ 2023-12-14 341/week @ 2023-12-21 435/week @ 2023-12-28 533/week @ 2024-01-04 537/week @ 2024-01-11 725/week @ 2024-01-18 1190/week @ 2024-01-25 693/week @ 2024-02-01 593/week @ 2024-02-08 668/week @ 2024-02-15 474/week @ 2024-02-22 428/week @ 2024-02-29 446/week @ 2024-03-07

2,093 downloads per month
Used in 6 crates (5 directly)

CC0 license

30KB
433 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
~30K SLoC