see docs at https://nicolas-cherel.github.io/rumblebars

lib.rs:

rumblebars — a handlebars template expansion library

This crates provides a library for parsing and expanding handlebars template

to use with rust nighly feature build with cargo build --features nightly --no-default-features

Rumblebars passes all mustaches specs [1] and 272 handlebars tests [2]. Template evaluation is rendered to a io::Writer, so that you can choose wether if you hold result in memory or not. It also input data angostic, given that your data structure implements the HBData trait (Json implementation provided).

[1] except delimiter changes test suite and one test failing because of a trailing space [2] all tests that does not involves javascript in data and partials, and see the comments for other cases

HMTL escaping safety

All output is filtered by being written to the SafeWriting trait. Helpers, just as regular evaluation do for unescaped content, have to opt out escaped writing by calling SafeWriting::into_unsafe() that will return the underlying unfiltered writer.

Quick start

Examples

The API shortcuts are provided by object oriented code design.

You can render directly into a String :

extern crate rustc_serialize as serialize;
extern crate rumblebars;
use serialize::json::Json;
use rumblebars::Template;

let data = Json::from_str(r##"{"hello": "hi"}"##).unwrap();

if let Ok(template) = Template::new("{{hello}}") {
  let res = template.eval_to_string(&data).unwrap_or("".to_string());
  assert_eq!(&res, "hi");
}

For template parsing, you can also use rust's usual patterns that leverage type inference :

use rumblebars::Template;
let template: Template = "{{hello}}".parse().unwrap(); // thanks to FromStr

You can just call the parse() function too :

rumblebars::parse("{{hello}}").unwrap();

Same with eval() :

extern crate rustc_serialize as serialize;
extern crate rumblebars;
use serialize::json::Json;
use rumblebars::{EvalContext};

let mut out = Vec::new();
rumblebars::eval(&rumblebars::parse("{{hello}}").unwrap(), &Json::Null, &mut out, &EvalContext::new());

helpers

Helpers are registered to the evaluation context. They are boxed closures (you can hold bare function in them too) that have to write their content on the out: &mut Writer. If you need to processed content before rendering it to the final Writer, just render it to a buffer put into a safe writter.

To use your hepler you just have to register it before evaluating your template:

You can control the EvalContext (for custom helpers) and output using eval()

use rumblebars::{Template, HBData, EvalContext};

if let Ok(template) = Template::new("{{hello}}") {
  let mut context = EvalContext::new();
  let mut buf = Vec::new();

  context.register_helper("hello".to_string(), Box::new(
    |params, options, out, hb_context| {
      "hi".write_value(out)
  }));

  if let Ok(_) = template.eval(&"", &mut buf, &context) {
     assert_eq!(String::from_utf8_lossy(&buf), "hi");
  }
}