Crate rubble_templates

General purpose API for rubble-templates.

Allows to quickly compile a text output of out a template.

Syntax

By default, rubble-templates while parsing a template looks for all blocks starting {{ and ending with }} those are marked as an evaluation spots with code that can be evaluated by an Evaluator.

Given the following example:

Hello there, {{ name }}!

This template contains three parts:

• Hello there, - raw text
• {{ name }} - code
• ! - raw text

The second part will be passed to a given Evaluator by the Compiler in order to get a String output. The code fragment will be substituted with the output.

The rubble-templates library can also evaluate more sophisticated code. You can pass your own functions that can enrich the template.

This library uses Lisp-like syntax during evaluation. All function calls look like the following:

function_name arg0 arg1 arg2

To call a plus function (that can be hypothetically implemented) to calculate the result of 2 + 2 you will need to write

The result is: {{ plus 2 2 }}

The parameters can also be grouped using parenthesis. This can be helpful in certain cases. For example, given plus and multiply functions, you will need to use the following code to calculate (1 + 2) * 3:

The result is: {{ multiply (plus 1 2) 3 }}

Sample

use rubble_templates::std_fun::std_functions;
use std::collections::HashMap;

use rubble_templates::compile_template_from_string;

let template = "{{ hello }}. 2 + 2 = {{ + 2 2 }}".to_string();

let mut variables: HashMap<String, String> = HashMap::new();
variables.insert("hello".to_string(), "Hello world!".to_string());

let result = compile_template_from_string(template, variables, std_functions());

assert_eq!(
    result.ok(),
    Some("Hello world!. 2 + 2 = 4".to_string())
);

Customizing

Compilation contains three phases:

• parsing - done by the template iterator, which can extract template parts (eg. raw text, code, etc) that can be further interpreted,
• evaluation - done by the Evaluator, which evaluates all code found by the iterator,
• compiling - done by the Compiler, which uses iterator to parse the content, feeds the Evaluator and then joins everything into output text.

You can implement your own iterators, evaluators or compilers. To modify the compilation process, you just need to use your own trait implementations instead of the default ones.

To show you how it works, here is what compile_template_from_string does in practice:

use std::collections::HashMap;
use rubble_templates::std_fun::std_functions;
use rubble_templates_evaluators::simple::template::Template;
use rubble_templates_evaluators::simple::evaluator::SimpleEvaluationEngine;
use rubble_templates_evaluators::simple::compiler::TemplateCompiler;
use rubble_templates_core::compiler::Compiler;
use rubble_templates_core::evaluator::Context;

// compile_template_from_string parameters
let raw_input = "2 + 3 = {{ + 2 3 }}".to_string();
let functions = std_functions();
let variables = HashMap::new();

// compilation process
let template = Template::from(raw_input);
let engine = SimpleEvaluationEngine::from(functions);
let compiler = TemplateCompiler::new(engine);

// the result
let result = compiler.compile(&template, Context::with_variables(variables));

assert_eq!(result.unwrap(), "2 + 3 = 5".to_string());

Modules

std_fun

This module contains standard functions for rubble-templates. Use std_functions to get a copy of map with those functions.

Functions

compile_template_from	Compiles template from Template.
compile_template_from_file	Compiles template from file.
compile_template_from_string	Compiles template from String.