oxiplate 0.16.4

Compile-time template engine with a focus on escaping, helpful error messages, and whitespace control.
Documentation

Oxiplate

Latest Version MIT OR Apache-2.0 License MSRV Coverage Status Open Issues Repository Docs Build Status

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

Hacking on Oxiplate

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>{{ message }}</p>

use oxiplate::prelude::*;

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

let hello_world = HelloWorld {
    title: "Oxiplate error handling",
    messages: "Hello world!",
};

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

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

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

#[derive(Oxiplate)]
#[oxiplate = "profile-link.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><!-- -->"#
};

assert_eq!(
    profile_link.render()?,
    r#"<!-- 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>
"#,
);

Ok::<(), ::std::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.

License

Licensed under either of

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.