/boilerplate

Statically-checked Rust template engine

Primary LanguageRustCreative Commons Zero v1.0 UniversalCC0-1.0

boilerplate

crates.io version docs ci status

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.