Crate handybars

Handybars

Introduction

This is a small library for template expansion. The syntax is based on handlebars, but it only support expansion of variables. No #if or #each, only {{ variable }}. If you need actual handlebars support consider the handlebars crate.

It has no dependencies and is designed to have a very simple API.

A simple companion attribute macro allows you to automatically turn enums and structs into Handybar Value variants.

Basic Usage

use handybars::{Context, Variable};
let ctx = Context::new().with_define("hello".parse().unwrap(), "world");
assert_eq!(ctx.render("hello {{ hello }}"), Ok("hello world".to_owned()));

You can also define objects

ctx.define("obj".parse().unwrap(), Object::new().with_property("a", "value"));
assert_eq!(ctx.render("object a: {{ obj.a }}"), Ok("object a: value".to_owned()));

You can even have nested objects

ctx.define("obj".parse().unwrap(), Object::new().with_property("b", Object::new().with_property("c", "value")));
assert_eq!(ctx.render("nested: {{ obj.b.c }}"), Ok("nested: value".to_owned()));

Note that objects cannot be directly expanded:

use handybars::{Context, Variable, Object, Error};
let ctx = Context::new().with_define("world".parse().unwrap(), Object::new().with_property("a", "p1"));
assert_eq!(ctx.render("{{world}}"), Err(Error::TriedToExpandObject(Variable::single("world"))));

Macros Usage

Usage of these requires the macros feature.

Enums are converted to Value::String variants:

use handybars::handybars_value;
#[handybars_value]
enum SimpleEnumProp {
    A,
    B,
}

Use structs as Value::Object variants::

#[handybars_value]
struct StructVal<'a> {
    field_1: u16,
    field_2: String,
    field_3: &'a str,
    field_4: SimpleEnumProp,
}

Combine enums and structs into more complex objects:

#[handybars_value]
struct TestObject<'a> {
    prop_0: String,
    prop_1: u64,
    prop_2: &'a str,
    prop_3: StructVal<'a>,
    prop_4: SimpleEnumProp,
}

It also works on nested structs:

let v = TestObject {
    prop_0: "p0_val".to_owned(),
    prop_1: 1,
    prop_2: "p2_val",
    prop_3: StructVal {
        field_1: 30,
        field_2: "f32_val".to_owned(),
        field_3: "f33_val",
        field_4: SimpleEnumProp::A,
    },
    prop_4: SimpleEnumProp::B,
};
let c = Context::new().with_define(Variable::single("obj"), v);
assert_eq!("1", c.render("{{ obj.prop_1 }}").unwrap());
assert_eq!("A", c.render("{{ obj.prop_3.field_4 }}").unwrap());
assert_eq!("f33_val", c.render("{{ obj.prop_3.field_3 }}").unwrap());

Enums with variant values are currently not supported. Enum with variants like the following will not compile:

#[handybars_value]
enum ComplexEnumProp<'a> {
    Var1(SimpleEnumProp),
    Var2(String),
    Var3(StructVal<'a>),
}

Modules

parse

Parsing utilities for templates

Structs

Context

Context for expanding templates

Object

Object value with 0 or more properties

Variable

Variable that can be used in templates

Enums

Error

Errors that may happen during rendering

Value

Value that variables can be expanded to

Attribute Macros

handybars_value