Crate oxiplate

Oxiplate

Oxiplate is an experimental compile-time template system for Rust with a focus on helpful error messages, escaping, and whitespace control. Use at your own risk.

Using Oxiplate in your project

• Oxiplate overview
• Getting started guide
• Release notes
• API docs

Hacking on Oxiplate

• How to contribute

Helpful error messages

Position information is tracked across files and passed onto Rust. This results in debuggable error messages even when issues are caught by Rust instead of Oxiplate.

<h1>{{ title }}</h1>
<p>{{ messages }}</p>

use oxiplate::Oxiplate;

#[derive(Oxiplate)]
#[oxiplate = "external.html.oxip"]
struct HelloWorld {
    title: &'static str,
    message: &'static str,
}

let hello_world = HelloWorld {
    title: "Hello world",
};

print!("{hello_world}");

error[E0609]: no field `messages` on type `&HelloWorld`
 --> /templates/external.html.oxip:2:7
  |
2 | <p>{{ messages }}</p>
  |       ^^^^^^^^ unknown field
  |
help: a field with a similar name exists
  |
2 - <p>{{ messages }}</p>
2 + <p>{{ message }}</p>
  |

Check out the broken tests directory of oxiplate and oxiplate-derive for (tested) example error messages.

Escaping

Escaping is arguably the most important feature of a template system. The escaper name appears first to make it easier to spot, and always runs last to ensure the output is always safe. Creating templates in a language not supported by Oxiplate? You can add your own escapers!

<!-- Profile link for {{ comment: name }} -->
<a href="{{ attr: url }}">{{ text: name }}</a>

use oxiplate::Oxiplate;

#[derive(Oxiplate)]
#[oxiplate = "external.html.oxip"]
struct ProfileLink {
    url: &'static str,
    name: &'static str,
}

let profile_link = ProfileLink {
    url: r#""><script>alert("hacked!");</script>"#,
    name: r#"<!-- --><script>alert("hacked!");</script><!-- -->"#
};

print!("{profile_link}");

<!-- Profile link for ‹ǃ−− −−›‹script›alert("hackedǃ");‹/script›‹ǃ−− −−› -->
<a href="&#34;><script>alert(&#34;hacked!&#34;);</script>">&lt;!-- -->&lt;script>alert("hacked!");&lt;/script>&lt;!-- --></a>

Read the full escaping chapter for more information.

Whitespace control

Oxiplate supports removing trailing/leading/surrounding whitespace, or even collapsing it down to a single space.

{# Say hi and bye -#}
<a href="#">{-}
    Hello {{ name -}}
</a>{_}
<a href="#">{-}
    Goodbye
    {{_ name -}}
</a>

<a href="#">Hello Bell</a> <a href="#">Goodbye Bell</a>

Read the full whitespace control chapter for more information.

Modules

escapers

Built-in escapers.

Traits

Render

Optimized render function trait.

Derive Macros

Oxiplate

Derives the ::std::fmt::Display implementation for a template’s struct.