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, Render};

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

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

print!("{}", hello_world.render()?);

Ok::<(), ::core::fmt::Error>(())

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, Render};

#[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.render()?);

Ok::<(), ::core::fmt::Error>(())

<!-- 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.

filters

Built-in filters.

prelude

Default Oxiplate experience that uses only built-in filters.

Structs

CowStrWrapper

Struct used in generated templates that is intended to be passed to filters asking for CowStr that will immediately extract the contained Cow<str>.

ToCowStrWrapper

Wrapper around text that will implement CowStr via FastCowStr when possible, otherwise via ::std::fmt::Display. Must borrow twice before calling to_cow_str().

UnescapedTextWrapper

Wrapper around unescaped text that will implement UnescapedText via FastEscape when possible, otherwise via Display. Must borrow twice before calling oxiplate_escape() or oxiplate_raw().

Traits

CowStr

A trait intended to be used by filters for any string-like arguments to deal with them more efficiently than str or impl Display. Any expression or filter prefixed by > in a template will convert the value to CowStrWrapper which implements this trait.

Escaper

Trait for an Oxiplate-compatible escaper group.

FastCowStr

Trait that allows for more efficient conversions to &str.

FastEscape

Trait that allows for more efficient conversions to &str.

Render

Optimized render function trait.

ToCowStr

Trait with a specialized implementation for items that implement FastCowStr, a trait that allows for more efficient conversions to Cow<'a, str>.

UnescapedText

Trait with a specialized implementation for items that implement FastEscape, a trait that allows for more efficient conversions to &str.

Derive Macros

Oxiplate

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