incrust

26 releases

Uses old Rust 2015

0.2.15	Apr 11, 2017
0.2.12	Jan 12, 2017
0.2.10	Dec 22, 2016
0.1.4	May 23, 2016
0.0.15	May 20, 2016

#372 in Template engine

MIT/Apache

130KB
3K SLoC

{% Incrust %}

Incrust is a template engine inspired by Jinja2 and written in Rust.

In fact it is a Jinja2, Django, Twig, Swig, Liquid (and probably others) template engines constellation, which uses similar methodologies.

Unstable

The implementation is at a very early stage and the API is a subject of changes.

Note that Incrust currently requires the nightly version of the Rust compiler.

Installation

Incrust is available on crates.io and can be included in your Cargo enabled project like this:

[dependencies]
incrust = "=0.2.15"

For ease of use hashmaps you may use the maplit

Then you need to setup your environment:

#[macro_use]
extern crate maplit;
extern crate incrust;

use incrust::ex;

fn create_env() -> Incrust {
    use incrust::{Incrust, FilesystemLoader};

    let mut instance = Incrust::default();
    instance.loaders.push(FilesystemLoader::new("./assets/tpl"));
    instance
}

fn main() {
    let incrust = create_env();
    let args = hashmap!{ "name".into() => ex("World") };
    incrust.render("hello", &args).unwrap();
}

Though Incrust has smart loaders, it may be used just as advanced formatter to render directly from string template

let args = hashmap!{ "name".into() => ex("World") };
incrust.render_text("Hello, {{ name | e }}!", &args).unwrap();
// or with prepared template
let hello = incrust.parse("Hello, {{ name | e }}!");
incrust.render_parsed(&hello, &args).unwrap();

Syntax examples

Comments

<p>Visible {# partially #} paragraph</p>

<p>Visible  paragraph</p>

Escaping

Example: {% raw %}{{ mustaches }}{% endraw %}

Example: {{ mustaches }}

Literals

Braces: {{ "{{" }}
Pi: {{ 3.1415926 }}

Braces: {{
Pi: 3.1415926

Filters

let args = hashmap!{ "title".into() => ex("<Cats & Dogs>") };

<h1>{{ title | escape }}</h1>

<h1>&lt;Cats &amp; Dogs&gt;</h1>

Expressions

let args = hashmap!{
    "what".into() => ex("Hello"),
    "who".into() => ex("World")
};

Say: "{{ what + ", " + who }}!"

Say: "Hello, World!"

let args = hashmap!{
    "alpha".into() => ex(6isize),
    "omega".into() => ex(7f64)
};

The answer is {{ alpha * omega }}

The answer is 42

Lazy boolean evaluation

Amount: {{ amount and ("" + amount + " pcs") or "-" }}

assert_eq!("Amount: 6 pcs", incrust.render("tpl", &hashmap!{ "amount".into() => ex(6isize) }).unwrap());
assert_eq!("Amount: -", incrust.render("tpl", &hashmap!{ "amount".into() => ex(0isize) }).unwrap());

Conditional statements

String {% if "" %}has chars{% else %}is empty{% endif %}
It's {% if False %}false{% elif True %}true{% endif %}

String is empty
It's true

For-Loop statements

let args = hashmap!{ "fruits".into() => ex(vec![ex("Orange"), ex("Apple"), ex("Banana")]) };

    <ul>
    {%- for fruit in fruits %}
        <li>{{ loop.index }}. {{ fruit | e }}</li>
    {%- endfor %}
    </ul>

    <ul>
        <li>1. Orange</li>
        <li>2. Apple</li>
        <li>3. Banana</li>
    </ul>

Template inheritance

let args = hashmap!{ "parent_layout".into() => ex("default") };
incrust.render("template", &args).unwrap()

default.tpl

<body>
    <h1>{% block title %}Default title{% endblock %}</h1>
    <main>
    {%- block body %}
        <p>Default body<p>
    {%- endblock %}
    </main>
</body>

template.tpl

{% extends parent_layout %}
{% block title -%}
    New title
{%- endblock %}

Output

<body>
    <h1>New title</h1>
    <main>
        <p>Default body<p>
    </main>
</body>

Include

let args = hashmap!{ "menu".into() => ex("default_menu") };
assert_eq!(expected, incrust.render("tpl", &args).unwrap());

default_menu.tpl

    <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About Us</a></li>
    </ul>

template.tpl

<nav>
    {%- include menu -%}
</nav>

<h1>Body</h1>

Output

<nav>
    <ul>
        <li><a href="/">Home</a></li>
        <li><a href="/about">About Us</a></li>
    </ul>
</nav>

<h1>Body</h1>

Alternatives

If you are looking for a template engine for your project, you may also look at these projects.

With a similar syntax

cobalt-org/liquid-rust Liquid templating for Rust
colin-kiegel/twig-rust Rust port of the twig-php template library
Nercury/twig-rs The Twig templating engine for Rust (work in progress)
Keats/tera A template engine for Rust

Others

sunng87/handlebars-rust Rust templating with Handlebars
nickel-org/rust-mustache Mustache template library for rust

License

Licensed under either of

Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT) at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.

Dependencies

~1.5MB
~17K SLoC