diff options
| -rw-r--r-- | askama/src/lib.rs | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/askama/src/lib.rs b/askama/src/lib.rs index dae237d..8cfe79c 100644 --- a/askama/src/lib.rs +++ b/askama/src/lib.rs @@ -1,3 +1,186 @@ +//! Askama implements a type-safe compiler for Jinja-like templates. +//! It lets you write templates in a Jinja-like syntax, +//! which are linked to a `struct` defining the template context. +//! This is done using a custom derive implementation (implemented +//! in [askama_derive](https://crates.io/crates/askama_derive)). +//! +//! # Example template +//! +//! ```text +//! {% extends "layout.html" %} +//! {% block body %} +//! <ul> +//! {% for user in users %} +//! <li><a href="{{ user.url }}">{{ user.username }}</a></li> +//! {% endfor %} +//! </ul> +//! {% endblock %} +//! ``` +//! +//! # Feature highlights +//! +//! * Construct templates using a familiar, easy-to-use syntax +//! * Fully benefit from the safety provided by Rust's type system +//! * Templates do not perform eager conversion to strings or other types +//! * Template code is compiled into your crate for optimal performance +//! * Templates can directly access your Rust types, according to Rust's +//! privacy rules +//! * Debugging features to assist you in template development +//! * Included filter functions will provide easy access to common functions +//! * Templates must be valid UTF-8 and produce UTF-8 when rendered +//! +//! # Creating Askama templates +//! +//! An Askama template is just a text file, in the UTF-8 encoding. +//! It can be used to generate any kind of text-based format. +//! You can use whatever extension you like. +//! +//! A template consists of **text contents**, which are passed through as-is, +//! **expressions**, which get replaced with content while being rendered, and +//! **tags**, which control the template's logic. +//! The template syntax is very similar to [Jinja](http://jinja.pocoo.org/), +//! as well as Jinja-derivatives like [Twig](http://twig.sensiolabs.org/) or +//! [Tera](https://github.com/Keats/tera). +//! +//! ## Variables +//! +//! Template variables are defined by the template context linked to the +//! template by deriving a `struct`'s implementation for `Template` from +//! a template file's contents. +//! You can use a dot (`.`) to get a variable's attributes. +//! Reading from variables is subject to the usual borrowing policies. +//! For example, `{{ name }}` will get the ``name`` field from the template +//! context, +//! while `{{ user.name }}` will get the ``name`` field of the `user` +//! ``field`` of the template context. +//! +//! ## Filters +//! +//! Values such as those obtained from variables can be post-processed +//! using **filters**. +//! Filters are applied to values using the pipe symbol (`|`) and may +//! have optional extra arguments in parentheses. +//! Filters can be chained, in which case the output from one filter +//! is passed to the next. +//! +//! For example, `{{ "{:?}"|format(name|escape) }}` will escape HTML +//! characters from the value obtained by accessing the `name` field, +//! and print the resulting string as a Rust literal. +//! +//! Consult the [filters module documentation](filters/index.html) for a list +//! of available filters. User-defined filters are currently not supported. +//! +//! ## Whitespace control +//! +//! Askama preserves all whitespace in template code by default, +//! except that final trailing newline characters are suppressed. +//! However, whitespace before and after expression and block delimiters +//! can be suppressed by writing a minus sign directly following a +//! start delimiter or leading into an end delimiter. +//! Askama considers all tabs, spaces, newlines and carriage returns to be +//! whitespace. +//! +//! ## Template inheritance +//! +//! Template inheritance allows you to build a base template with common +//! elements that can then be shared by all inheriting templates. +//! A base template defines **blocks** that child templates can then override. +//! +//! ### Base template +//! +//! ```text +//! <!DOCTYPE html> +//! <html lang="en"> +//! <head> +//! <title>{{ block title %}{{ title }}{% endblock %} - My Site</title> +//! {% block head %}{% endblock %} +//! </head> +//! <body> +//! <div id="content"> +//! {% block content %}{% endblock %} +//! </div> +//! </body> +//! </html> +//! ``` +//! +//! The `block` tags define three blocks that can be filled in by child +//! templates. The base template defines a default version of the block. +//! +//! ### Child template +//! +//! Here's an example child template: +//! +//! ```text +//! {% extends "base.html" %} +//! +//! {% block title %}Index{% endblock %} +//! +//! {% block head %} +//! <style> +//! </style> +//! {% endblock %} +//! +//! {% block content %} +//! <h1>Index</h1> +//! <p>Hello, world!</p> +//! {% endblock %} +//! ``` +//! +//! The `extends` tag tells the code generator that this template inherits +//! from another template. It will render the top-level content from the +//! base template, and substitute blocks from the base template with those +//! from the child template. The inheriting template context `struct` must +//! have a field called `_parent` of the type used as the base template +//! context. Blocks can only refer to the context of their own template. +//! +//! ## HTML escaping +//! +//! Askama does not yet support automatic escaping. Care must be taken to +//! escape content that may contain HTML control characters. You can use +//! the `escape` filter (or its `e` alias) to escape data for use in HTML. +//! +//! ## Control structures +//! +//! ### For +//! +//! Loop over each item in an iterator. For example: +//! +//! ```text +//! <h1>Users</h1> +//! <ul> +//! {% for user in users %} +//! <li>{{ user.name|e }}</li> +//! {% endfor %} +//! </ul> +//! ``` +//! +//! Inside for-loop blocks, some useful variables are accessible: +//! +//! * *loop.index*: current loop iteration (starting from 1) +//! * *loop.index0*: current loop iteration (starting from 0) +//! +//! ### If +//! +//! The *if* statement is used as you might expect: +//! +//! ```text +//! {% if users.len() == 0 %} +//! No users +//! {% else if users.len() == 1 %} +//! 1 user +//! {% else %} +//! {{ users.len() }} users +//! {% endif %} +//! ``` +//! +//! ## Expressions +//! +//! Askama supports string literals (`"foo"`) and integer literals (`1`). +//! It supports almost all binary operators that Rust supports, +//! including arithmetic, comparison and logic operators. +//! The same precedence order as Rust uses is applied. +//! Expressions can be grouped using parentheses. + #[macro_use] extern crate nom; extern crate syn; |