# Build a simple template engine in <100 lines of Rust code If you've ever built a full-stack web app, you've probably run into a templating engine like the one provided by Django or Flask. These neat utility packages parse your HTML files and "fill-in-the-blanks" (so to speak) with dynamic content. A common example is sending the titles of posts from your back-end to be listed in a `

`. This tutorial is aimed at beginner Rustaceans but you should be familiar with programming and working on the terminal. # Why Rust? [Rust](http://rust-lang.org/) is the modern, memory-safe programming language (with [a fantastic web ecosystem](https://www.arewewebyet.org/)!) that I'll be using in this tutorial. Packages in Rust are called "crates" and are typically published to [crates.io](https://crates.io). If you'd like to learn more about the [most loved language on StackOverflow](https://developers.slashdot.org/story/21/08/03/1756241/rust-is-the-most-loved-language-for-the-6th-year-in-a-row-in-stack-overflow-study), I can't recommend the [Rust Book](https://doc.rust-lang.org/book/ch00-00-introduction.html) and [Rust by Example](https://doc.rust-lang.org/rust-by-example) enough! In line with the notoriously-idiomatic Rust community, the file structure for this example crate will be: ``` template-engine/ ├─ dist/ │ ├─ index.html ├─ src/ │ ├─ lib.rs ├─ Cargo.toml ``` > 🦀 The primary code file for Rust libraries is `src/lib.rs`; for binaries, `src/main.rs` `src/lib.rs` will house the crate's code, while the dependencies and other metadata will be kept neatly tucked away in `Cargo.toml`. # Qu'est-ce que Jinja ? Jinja is a web template engine for Python that uses a simple set of rules for [its syntax](https://documentation.bloomreach.com/engagement/docs/jinja-syntax): | **Delimiter:** | **It is used for:** | |-----------------------------------------------------------|--------------------------------------------------------------------------| | `{{..}}`
Example: `{{ customer }}`. | Print the value of the variable between the braces. | | `{%..%}`
Example: `{% set x = 2 %}`. | Statements that do not have an output. | | `{#..#}`
Example: `{# Blog: #}`. | Comments to explain the code. | This will provide us with a simple, standardized set of methods to implement in our toy template engine. # The Plan The only thing programmers hate more than working with legacy software is having to do a boring, repetitive process. To avoid having to rewrite your code as much—while you come up with *slightly* better names for your variables—it's useful to brainstorm as much as possible before you begin scripting. ## Features By the end of this tutorial, you should have a basic, safe (no Rust code is ever evaluated), and minimal template engine. It will support the following features: 1. Printing variables: ```html Hello, my name is {{ name }}! ``` 2. If statements (only supports boolean expressions currently): ```html {% if allowed %}
Welcome to the internet!
{% else %}
No trespassing.
{% endif %} ``` 3. Repeat statements: ```html {% repeat 3 times %}
{{ date }}

RegEx Breakdown

{{ — Match opening double braces
(.\*?) — Match any text lazily
{{ — Match closing double braces

RegEx Breakdown

{% repeat — Match first part of opening tag
(\\d\*?) — Match digits(s) lazily as capture group
times %} — Match end part of opening tag
((.|\\n)\*?) — Match multi-line string of text lazily
{% endrepeat %} — Match closing tag

().unwrap()) }).to_string(); ``` > Note how after each statement, the template variable is reassigned to the rendered version. ## If/else statements This regular expression will match `{% if KEY %}...{% else %}...{% endif %}`: ```rs let if_else_regex = Regex::new(r"\{% if (.*?) %\}((.|\n)*?)(\{% else %\}((.|\n)*?)\{% endif %\}|\{% endif %\})").unwrap(); ```

RegEx Breakdown

{% if — Match first part of opening tag
(.\*?) — Match any text lazily
%} — Match end part of opening tag
((.|\\n)\*?) — Match multi-line string of text lazily
{% else %} — Match else tag
((.|\\n)\*?) — Match multi-line string of text lazily
{% endif %} — Match closing tag

From there, simply use the `regex` crate's [`.replace_all()`](https://docs.rs/regex/latest/regex/struct.Regex.html#method.replace_all) method to swap the capture with either the parsed `if` code block or the parsed `else` code block, depending on the value of the boolean that matches `key`. ```rs template = if_else_regex.replace_all(&template, |caps: &Captures| { // Extract the name of the bool being tested let key = caps.get(1).unwrap().as_str().trim(); // Parse the 'if' and (optional) 'else' code blocks let if_code = caps.get(2).unwrap().as_str().trim(); let else_code = caps.get(5).map_or("", |m| m.as_str()).trim(); // Find the corresponding key in the Data and return the value if let Data::Boolean(exp) = data[key] { if exp { if_code.to_string() } else { else_code.to_string() } } else { "ERROR PARSING KEY".to_string() } }).to_string(); ``` [`.unwrap()`](https://doc.rust-lang.org/std/option/enum.Option.html#method.unwrap) is one of the many methods for error handling in Rust but it will throw an error if the unwrapped `Option` is `None` (Rust equivalent to null). Using [`.map_or()`](https://doc.rust-lang.org/std/option/enum.Option.html#method.map_or) when handling the 5th capture group (line recreated below) allows us to store an empty string as the `else_code` if there is no else code block in the template. ```rs let else_code = caps.get(5).map_or("", |m| m.as_str()).trim(); ``` ## Comments Lastly, Jinja-style comments should be converted to HTML comments so that they can still be read in the rendered code. Comments are useful to disable parts of the template for debugging or provide documentation to your template code. Here, we don't need to match the key or code block surrounded by `{#` and `#}` so a simple string [`.replace()`](https://doc.rust-lang.org/std/primitive.str.html#method.replace) method will suffice: ```rs template = template.replace("{#", ""); ``` ## Put it all together! Your finished render function should look something like this: ```rust fn render(mut template: String, mut data: HashMap<&str, Data>) -> String { // Render variable printing let print_regex = Regex::new(r"\{\{(.*?)\}\}").unwrap(); template = print_regex.replace_all(&template, |caps: &Captures| { // Extract the text in between the {{ and the }} in the template let key = caps.get(1).unwrap().as_str().trim(); // Find the corresponding key in the Data and return the value data[key].to_string() }).to_string(); // Render repeat statements let repeat_regex = Regex::new(r"\{% repeat (\d*?) times %\}((.|\n)*?)\{% endrepeat %\}").unwrap(); template = repeat_regex.replace_all(&template, |caps: &Captures| { // Extract the number of times to repeat the code let times = caps.get(1).unwrap().as_str().trim(); // Parse the code block to be repeated let code = caps.get(2).unwrap().as_str().trim(); // Repeat the code `times` number of times code.repeat(times.parse::().unwrap()) }).to_string(); // Render for statements let if_else_regex = Regex::new(r"\{% if (.*?) %\}((.|\n)*?)(\{% else %\}((.|\n)*?)\{% endif %\}|\{% endif %\})").unwrap(); template = if_else_regex.replace_all(&template, |caps: &Captures| { // Extract the name of the bool being tested let key = caps.get(1).unwrap().as_str().trim(); // Parse the 'if' and (optional) 'else' code blocks let if_code = caps.get(2).unwrap().as_str().trim(); let else_code = caps.get(5).map_or("", |m| m.as_str()).trim(); // Find the corresponding key in the Data and return the value if let Data::Boolean(exp) = data[key] { if exp { if_code.to_string() } else { else_code.to_string() } } else { "ERROR PARSING KEY".to_string() } }).to_string(); // Process comments template = template.replace("{#", ""); // Return output template } ``` # Testing it out ## Writing a template Inside `dist/index.html`, we'll design a simple template to test documentation comments, code-disabling comments, variable printing, if/else statements, and repeat statements. ```html {# This is a comment! #}

{% if allowed %} {% repeat 3 times %}

Welcome to the {{ hello }}!

{% endrepeat %} {% else %}

No trespassing.

{% endif %} {#

Hidden from the {{ hello }}...

#} ``` ## Create the test Unlike Rust binaries, libraries in Rust have no primary function to run which is why executing `cargo run` in the root directory won't work. Instead, you can play around with your library code using Rust [tests](https://doc.rust-lang.org/book/ch11-01-writing-tests.html). These tests are run independently from your library code meaning you'll need to import the elements of your crate to be used in your test: ```rs #[cfg(test)] mod tests { use crate::{render, Data}; use std::collections::HashMap; #[test] fn basic_template() { ... } } ``` In our `basic_template()` test, we'll use the `fs` module of the Rust standard library to read the contents of our example template and save it as a string: ```rust let input = std::fs::read_to_string("dist/index.html").expect("Something went wrong reading the file"); ``` Next, we'll construct a HashMap of data to pass to the `render()` function: ```rs let data = HashMap::from([ ("hello", Data::Text("internet".to_string())), ("allowed", Data::Boolean(true)) ]); ``` Finally, we'll call our `render()` function and print the output: ```rs println!("{}", render(input, data)); ``` ## Run the test To run a Rust test without hiding printed text, use: ```bash cargo test -- --nocapture ``` Which should successfully run and print to the terminal: ```html

internet

Welcome to the internet!

``` **Congrats on creating your own template engine! 🥳** # What's next? In comparison to most template engines, the toy we built today is pretty bare-bones. Currently, no variables can be set in the template code, nesting only partially(?) works, and few data types are supported. If you're willing to take on the strict typing of Rust, you could expand this project by: - Supporting more operators in the If/Else Statement expression syntax (`<`, `>`, `==`, `!=`, etc.) - Allowing the editing of variables in the templates and rendering the template delimiters as ordered commands rather than simultaneous replacements - Implementing more Jinja features such as macros, importing of other templates, correct escaping, etc. (see [Bloomreach's documentation on Jinja syntax](https://documentation.bloomreach.com/engagement/docs/jinja-syntax)) ------ The code for this project can be found here: %[https://github.com/spikecodes/template-engine] ------ Please leave a like if you enjoyed this post! Let me know in the comments if you have any suggestions or clarifications for making this article accurate, easy to understand, and up-to-date.