Crate leon

Dead-simple string templating.

Leon parses a template string into a list of tokens, and then substitutes provided values in. Unlike other templating engines, it is extremely simple: it supports no logic, only replaces. It is even simpler than format!(), albeit with a similar syntax.

Syntax

it is better to rule { group }
one can live {adverb} without power

A replacement is denoted by { and }. The contents of the braces, trimmed of any whitespace, are the key. Any text outside of braces is left as-is.

To escape a brace, use \{ or \}. To escape a backslash, use \\. Keys cannot contain escapes.

\{ leon \}

The above examples, given the values group = "no one" and adverb = "honourably", would render to:

it is better to rule no one
one can live honourably without power
{ leon }

Usage

A template is first parsed to a token list:

use leon::Template;

let template = Template::parse("hello {name}").unwrap();

The template can be inspected, for example to check if a key is present:

assert!(template.has_key("name"));

The template can be rendered to a string:

use leon::vals;
assert_eq!(
    template.render(
        &&vals(|_key| Some("marcus".into()))
    ).unwrap().as_str(),
    "hello marcus",
);

…or to a writer:

use std::io::Write;
use leon::vals;
let mut buf: Vec<u8> = Vec::new();
template.render_into(
    &mut buf,
    &&vals(|key| if key == "name" {
        Some("julius".into())
    } else {
        None
    })
).unwrap();
assert_eq!(buf.as_slice(), b"hello julius");

…with a map:

use std::collections::HashMap;
let mut values = HashMap::new();
values.insert("name", "brutus");
assert_eq!(template.render(&values).unwrap().as_str(), "hello brutus");

…or with your own type, if you implement the Values trait:

use std::borrow::Cow;
use leon::Values;

struct MyMap {
  name: &'static str,
}
impl Values for MyMap {
   fn get_value(&self, key: &str) -> Option<Cow<'_, str>> {
      if key == "name" {
        Some(self.name.into())
     } else {
       None
    }
   }
}
let values = MyMap { name: "pontifex" };
assert_eq!(template.render(&values).unwrap().as_str(), "hello pontifex");

Compile-time parsing

You can either use leon-macros’s template!, a proc-macro, with the exact same syntax as the normal parser, or this crate’s template! rules-macro, which requires a slightly different syntax but doesn’t bring in additional dependencies. In either case, the leon library is required as a runtime dependency.

Errors

Leon will return a ParseError if the template fails to parse. This can happen if there are unbalanced braces, or if a key is empty.

Leon will return a RenderError::MissingKey if a key is missing from keyed values passed to Template::render(), unless a default value is provided with [Template.default].

It will also pass through I/O errors when using Template::render_into().

Macros

template

Construct a template constant using syntax similar to the template to be passed to Template::parse.

Structs

ParseError

An error that can occur when parsing a template.

Template

ValuesFn

Workaround to allow using functions as Values.

Enums

Item

RenderError

Traits

Values

Functions

vals

Wraps your function so it implements Values, though it only works if your function returns Cow<'static, str>.