Crate minijinja[−][src]
Expand description
MiniJinja: a powerful template engine for Rust with minimal dependencies
MiniJinja is a simple Jinja2 inspired template engine based on serde. It’s light in features and on dependencies but implements a pretty sizable feature set from Jinja2. It attempts to stay largely compatible in Syntax and behavior:
{% for user in users %}
<li>{{ user.name }}</li>
{% endfor %}
Why MiniJinja
Rust already has quite a selection of template engines and there are in fact already a handful of engines which are inspired by Jinja2 including Tera and Askama but they are very heavy in terms of dependencies and usage. MiniJinja by its name does not try to become a replacement for these, but it wants to be a good default choice if you need a little bit of templating with minimal dependencies.
MiniJinja tries to juggle these three goals:
- aim for a high level of compatibility with Jinja2 templates
- provide template rendering and expression evaluation functionality
- achieve above functionality with the lest amount of dependencies possible
Template Usage
To use MiniJinja one needs to create an Environment
and populate it with templates.
Afterwards templates can be loaded and rendered. To pass data one can pass any serde
serializable value:
use minijinja::{Environment, context};
let mut env = Environment::new();
env.add_template("hello", "Hello {{ name }}!").unwrap();
let tmpl = env.get_template("hello").unwrap();
println!("{}", tmpl.render(context!(name => "John")).unwrap());
Hello John!
Expression Usage
MiniJinja — like Jinja2 — allows to be used as expression language. This can be
useful to express logic in configuration files or similar things. For this
purpose the Environment::compile_expression
method can be used. It returns
an expression object that can then be evaluated, returning the result:
use minijinja::{Environment, context};
let env = Environment::new();
let expr = env.compile_expression("number < 42").unwrap();
let result = expr.eval(context!(number => 23)).unwrap();
assert_eq!(result.is_true(), true);
Learn more
syntax
: documentation of the template engine syntax.filters
: for how to write custom filters and to see the list of built-in filters.tests
: for how to write custom test functions and to see the list of built-in tests.functions
: for how to write custom functions and to see the list of built-in functions.value
: for information about the runtime value object.Environment
: the main API entry point.Template
: the template object API.
Optional Features
There are some additional features that can be enabled:
source
: enables theSource
type which helps with dynamic loading of templates.memchr
: enables thememchr
dependency which provides performance improvements for the parser.v_htmlescape
: enables thev_htmlescape
dependency which implements a faster HTML escaping algorithm.unstable_machinery
: provides access to the internal machinery of the engine. This is a forever unstable API which mainly exists to aid debugging complex issues.
Additionally to cut down on size of the engine some default functionality can be removed:
builtin_filters
: if this feature is removed the default filters are not implemented.builtin_tests
: if this feature is removed the default tests are not implemented.builtin_functions
: if this feature is removed the default functions are not implemented.sync
: this feature makes MiniJinja’s typeSend
andSync
. If this feature is disabled sending types across threads is often not possible. Thread bounds of things like callbacks however are not changing which means code that uses MiniJinja still needs to be threadsafe.json
: When enabled thetojson
filter is added as builtin filter.urlencode
: When enabled theurlencode
filter is added as builtin filter.
Modules
Filter functions and abstractions.
Global functions and abstractions.
Documents the syntax for templates.
Test functions and abstractions.
Provides a dynamic value type abstraction.
Macros
Creates a template context with keys and values.
Structs
An abstraction that holds the engine configuration.
Represents template errors.
A handle to a compiled expression.
Helper to HTML escape a string.
source
Utility for dynamic template loading.
Provides access to the current execution state of the engine.
Represents a handle to a template.
Enums
Controls the autoescaping behavior.
An enum describing the error kind.