Add HTML safe types

book/src/filters.md

@@ -48,6 +48,10 @@ Enable it with Cargo features (see below for more information).
 
 * **[Custom filters][#custom-filters]**
 
+* **[HTML-safe types][#html-safe-types]**
+
+  * **[Safe output of custom filters][#safe-output-of-custom-filters]**
+
 ## Built-In Filters
 [#built-in-filters]: #built-in-filters
 
@@ -552,3 +556,60 @@ fn main() {
     assert_eq!(t.render().unwrap(), "faaaa");
 }
 ```
+
+## HTML-safe types
+[#html-safe-types]: #html-safe-types
+
+Rinja will try to avoid escaping types that generate string representations that do not contain
+"HTML-unsafe characters".
+HTML-safe characters are characters that can be used in any context in HTML texts and attributes.
+The "unsafe" characters are: `<`, `>`, `&`, `"` and `'`.
+
+In order to know which types do not need to be escaped, rinja has the marker trait
+`rinja::filters::HtmlSafe`, and any type that implements that trait won't get automatically
+escaped in a `{{expr}}` expression.
+By default e.g. all primitive integer types are marked as HTML-safe.
+
+You can also mark your custom type `MyStruct` as HTML-safe using:
+
+```rust
+impl rinja::filters::HtmlSafe for MyStruct {}
+```
+
+This automatically marks references `&MyStruct` as HTML-safe, too.
+
+### Safe output of custom filters
+[#safe-output-of-custom-filters]: #safe-output-of-custom-filters
+
+Say, you have a custom filter `|strip` that removes all HTML-unsafe characters:
+
+```rust
+fn strip(s: impl ToString) -> Result<String, rinja::Error> {
+    Ok(s.to_string()
+        .chars()
+        .filter(|c| !matches!(c, '<' | '>' | '&' | '"' | '\''))
+        .collect()
+    )
+}
+```
+
+Then you can also mark the output as safe using `rinja::filters::Safe`:
+
+```rust
+fn strip(s: impl ToString) -> Result<Safe<String>, rinja::Error> {
+    Ok(Safe(...))
+}
+```
+
+There also is `rinja::filters::MaybeSafe` that can be used to mark *some* output as safe,
+if you know that *some* inputs for our filter will always result in a safe output:
+
+```rust
+fn as_sign(i: i32) -> Result<MaybeSafe<&'static str>, rinja::Error> {
+    match i.into() {
+        i if i < 0 => Ok(MaybeSafe { text: "<0", needs_escaping: true }),
+        i if i > 0 => Ok(MaybeSafe { text: ">0", needs_escaping: true }),
+        _          => Ok(MaybeSafe { text: "=0", needs_escaping: false }),
+    }
+}
+```

examples/actix-web-app/templates/_layout.html

@@ -17,7 +17,7 @@
             E.g. maybe you would like to have "Rinja example application" as default title for
             your pages, then simply add this text (without quotation marks) in the block!
 
-            The default content can be as complex as you need to to be.
+            The default content can be as complex as you need it to be.
             E.g. it may contain any nodes like `{% if … %}`, and even other blocks.
         ~#}
         <title>{% block title %}{% endblock %}</title>
@@ -55,13 +55,13 @@
 {%- macro lang_select(handler, query) -%}
     <ul id="lang-select">
         {%- if lang != Lang::en -%}
-            <li><a href="{{ req.url_for(handler, [Lang::en])? }}{{ query|safe }}">This page in English</a></li>
+            <li><a href="{{ req.url_for(handler, [Lang::en])? }}{{ query }}">This page in English</a></li>
         {%- endif -%}
         {%- if lang != Lang::de -%}
-            <li><a href="{{ req.url_for(handler, [Lang::de])? }}{{ query|safe }}">Diese Seite auf deutsch.</a></li>
+            <li><a href="{{ req.url_for(handler, [Lang::de])? }}{{ query }}">Diese Seite auf deutsch.</a></li>
         {%- endif -%}
         {%- if lang != Lang::fr -%}
-            <li><a href="{{ req.url_for(handler, [Lang::fr])? }}{{ query|safe }}">Cette page est en français.</a></li>
+            <li><a href="{{ req.url_for(handler, [Lang::fr])? }}{{ query }}">Cette page est en français.</a></li>
         {%- endif -%}
     </ul>
 {%- endmacro lang_select -%}