minijinja/syntax.rs
1//! Documents the syntax for templates and provides ways to reconfigure it.
2//!
3//! <details><summary><strong style="cursor: pointer">Table of Contents</strong></summary>
4//!
5//! - [Synopsis](#synopsis)
6//! - [Trailing Newlines](#trailing-newlines)
7//! - [Expressions](#expressions)
8//! - [Literals](#literals)
9//! - [Math](#math)
10//! - [Comparisons](#comparisons)
11//! - [Logic](#logic)
12//! - [Other Operators](#other-operators)
13//! - [If Expressions](#if-expressions)
14//! - [Tags](#tags)
15//! - [`{% for %}`](#-for-)
16//! - [`{% if %}`](#-if-)
17//! - [`{% extends %}`](#-extends-)
18//! - [`{% block %}`](#-block-)
19//! - [`{% include %}`](#-include-)
20//! - [`{% import %}`](#-import-)
21//! - [`{% with %}`](#-with-)
22//! - [`{% set %}`](#-set-)
23//! - [`{% filter %}`](#-filter-)
24//! - [`{% macro %}`](#-macro-)
25//! - [`{% call %}`](#-call-)
26//! - [`{% do %}`](#-do-)
27//! - [`{% autoescape %}`](#-autoescape-)
28//! - [`{% raw %}`](#-raw-)
29//! - [`{% break %} / {% continue %}`](#-break----continue-)
30//! - [Custom Delimiters](#custom-delimiters)
31//! - [Whitespace Control](#whitespace-control)
32//!
33//! </details>
34//!
35//! # Synopsis
36//!
37//! A MiniJinja template is simply a text file. MiniJinja can generate any text-based
38//! format (HTML, XML, CSV, LaTeX, etc.). A template doesn’t need to have a specific extension
39//! and in fact MiniJinja does not understand much about the file system. However the default
40//! configuration for [auto escaping](crate::Environment::set_auto_escape_callback) uses file
41//! extensions to configure the initial behavior.
42//!
43//! A template contains [**expressions**](#expressions), which get replaced with values when a
44//! template is rendered; and [**tags**](#tags), which control the logic of the template. The
45//! template syntax is heavily inspired by Jinja2, Django and Python.
46//!
47//! This is a minimal template that illustrates a few basics:
48//!
49//! ```jinja
50//! <!doctype html>
51//! <title>{% block title %}My Website{% endblock %}</title>
52//! <ul id="navigation">
53//! {% for item in navigation %}
54//! <li><a href="{{ item.href }}">{{ item.caption }}</a></li>
55//! {% endfor %}
56//! </ul>
57//!
58//! <h1>My Webpage</h1>
59//! {% block body %}{% endblock %}
60//!
61//! {# a comment #}
62//! ```
63//!
64//! # Trailing Newlines
65//!
66//! MiniJinja, like Jinja2, will remove one trailing newline from the end of the file automatically
67//! on parsing. This lets templates produce a consistent output no matter if the editor adds a
68//! trailing newline or not. If one wants a trailing newline an extra newline can be added or the
69//! code rendering it adds it manually.
70//!
71//! # Expressions
72//!
73//! MiniJinja allows basic expressions everywhere. These work largely as you expect from Jinja2.
74//! Even if you have not used Jinja2 you should feel comfortable with it. To output the result
75//! of an expression wrap it in `{{ .. }}`.
76//!
77//! ## Literals
78//!
79//! The simplest form of expressions are literals. Literals are representations for
80//! objects such as strings and numbers. The following literals exist:
81//!
82//! - `"Hello World"`: Everything between two double or single quotes is a string. They are
83//! useful whenever you need a string in the template (e.g. as arguments to function calls
84//! and filters, or just to extend or include a template).
85//! - `42`: Integers are whole numbers without a decimal part. They can be prefixed with
86//! `0b` to indicate binary, `0o` to indicate octal and `0x` to indicate hexadecimal.
87//! Underscores are tolerated (and ignored) everywhere a digit is except in the last place.
88//! - `42.0`: Floating point numbers can be written using a `.` as a decimal mark.
89//! Underscores are tolerated (and ignored) everywhere a digit is except in the last place.
90//! - `['list', 'of', 'objects']`: Everything between two brackets is a list. Lists are useful
91//! for storing sequential data to be iterated over.
92//! for compatibility with Jinja2 `('list', 'of', 'objects')` is also allowed.
93//! - `{'map': 'of', 'key': 'and', 'value': 'pairs'}`: A map is a structure that combines keys
94//! and values. Keys must be unique and always have exactly one value. Maps are rarely
95//! created in templates.
96//! - `true` / `false` / `none`: boolean values and the special `none` value which maps to the
97//! unit type in Rust.
98//!
99//! ## Math
100//!
101//! MiniJinja allows you to calculate with values. The following operators are supported:
102//!
103//! - ``+``: Adds two numbers up. ``{{ 1 + 1 }}`` is ``2``.
104//! - ``-``: Subtract the second number from the first one. ``{{ 3 - 2 }}`` is ``1``.
105//! - ``/``: Divide two numbers. ``{{ 1 / 2 }}`` is ``0.5``. See note on divisions below.
106//! - ``//``: Integer divide two numbers. ``{{ 5 // 3 }}`` is ``1``. See note on divisions below.
107//! - ``%``: Calculate the remainder of an integer division. ``{{ 11 % 7 }}`` is ``4``.
108//! - ``*``: Multiply the left operand with the right one. ``{{ 2 * 2 }}`` would return ``4``.
109//! - ``**``: Raise the left operand to the power of the right operand. ``{{ 2**3 }}``
110//! would return ``8``.
111//!
112//! Note on divisions: divisions in Jinja2 are flooring, divisions in MiniJinja
113//! are at present using euclidean division. They are almost the same but not quite.
114//!
115//! ## Comparisons
116//!
117//! - ``==``: Compares two objects for equality.
118//! - ``!=``: Compares two objects for inequality.
119//! - ``>``: ``true`` if the left hand side is greater than the right hand side.
120//! - ``>=``: ``true`` if the left hand side is greater or equal to the right hand side.
121//! - ``<``:``true`` if the left hand side is less than the right hand side.
122//! - ``<=``: ``true`` if the left hand side is less or equal to the right hand side.
123//!
124//! ## Logic
125//!
126//! For ``if`` statements it can be useful to combine multiple expressions:
127//!
128//! - ``and``: Return true if the left and the right operand are true.
129//! - ``or``: Return true if the left or the right operand are true.
130//! - ``not``: negate a statement (see below).
131//! - ``(expr)``: Parentheses group an expression.
132//!
133//! ## Other Operators
134//!
135//! The following operators are very useful but don't fit into any of the other
136//! two categories:
137//!
138//! - ``is``/``is not``: Performs a [test](crate::tests).
139//! - ``in``/``not in``: Performs a containment check.
140//! - ``|`` (pipe, vertical bar): Applies a [filter](crate::filters).
141//! - ``~`` (tilde): Converts all operands into strings and concatenates them.
142//! ``{{ "Hello " ~ name ~ "!" }}`` would return (assuming `name` is set
143//! to ``'John'``) ``Hello John!``. With auto escaping enabled, combining a
144//! [safe](crate::filters::safe) string with another value escapes that value
145//! and returns a safe string. The same applies to ``+`` on two strings.
146//! - ``()``: Call a callable: ``{{ super() }}``. Inside of the parentheses you
147//! can use positional arguments. Additionally keyword arguments are supported
148//! which are treated like a dict syntax. Eg: `foo(a=1, b=2)` is the same as
149//! `foo({"a": 1, "b": 2})`.
150//! - ``.`` / ``[]``: Get an attribute of an object. If an object does not have a specific
151//! attribute or item then `undefined` is returned. Accessing a property of an already
152//! undefined value will result in an error.
153//! - ``[start:stop]`` / ``[start:stop:step]``: slices a list or string. All three expressions
154//! are optional (`start`, `stop`, `step`). For instance ``"Hello World"[:5]`` will return
155//! just `"Hello"`. Likewise ``"Hello"[1:-1]`` will return `"ell"`. The step component can
156//! be used to change the step size. `"12345"[::2]` will return `"135"`.
157//!
158//! ### If Expressions
159//!
160//! It is also possible to use inline _if_ expressions. These are useful in some situations.
161//! For example, you can use this to extend from one template if a variable is defined,
162//! otherwise from the default layout template:
163//!
164//! ```jinja
165//! {% extends layout_template if layout_template is defined else 'default.html' %}
166//! ```
167//!
168//! The `else` part is optional. If not provided, the else block implicitly evaluates
169//! into an undefined value:
170//!
171//! ```jinja
172//! {{ title|upper if title }}
173//! ```
174//!
175//! Note that for compatibility with Jinja2, when the `else` block is missing the undefined
176//! value will be marked as "silent". This means even if strict undefined behavior is
177//! requested, this undefined value will print to an empty string. This means
178//! that this is always valid:
179//!
180//! ```jinja
181//! {{ value if false }} -> prints an empty string (silent undefined returned from else)
182//! ```
183//!
184//! # Tags
185//!
186//! Tags control logic in templates. The following tags exist:
187//!
188//! ## `{% for %}`
189//!
190//! The for tag loops over each item in a sequence. For example, to display a list
191//! of users provided in a variable called `users`:
192//!
193//! ```jinja
194//! <h1>Members</h1>
195//! <ul>
196//! {% for user in users %}
197//! <li>{{ user.username }}</li>
198//! {% endfor %}
199//! </ul>
200//! ```
201//!
202//! It's also possible to unpack tuples while iterating:
203//!
204//! ```jinja
205//! <h1>Members</h1>
206//! <ul>
207//! {% for (key, value) in list_of_pairs %}
208//! <li>{{ key }}: {{ value }}</li>
209//! {% endfor %}
210//! </ul>
211//! ```
212//!
213//! Inside of the for block you can access some special variables:
214//!
215//! - `loop.index`: The current iteration of the loop. (1 indexed)
216//! - `loop.index0`: The current iteration of the loop. (0 indexed)
217//! - `loop.revindex`: The number of iterations from the end of the loop (1 indexed)
218//! - `loop.revindex0`: The number of iterations from the end of the loop (0 indexed)
219//! - `loop.first`: True if this is the first iteration.
220//! - `loop.last`: True if this is the last iteration.
221//! - `loop.length`: The number of items in the sequence.
222//! - `loop.cycle`: A helper function to cycle between a list of sequences. See the explanation below.
223//! - `loop.depth`: Indicates how deep in a recursive loop the rendering currently is. Starts at level 1
224//! - `loop.depth0`: Indicates how deep in a recursive loop the rendering currently is. Starts at level 0
225//! - `loop.previtem`: The item from the previous iteration of the loop. `Undefined` during the first iteration.
226//! - `loop.nextitem`: The item from the previous iteration of the loop. `Undefined` during the last iteration.
227//! - `loop.changed(...args)`: Returns true if the passed values have changed since the last time it was called with the same arguments.
228//! - `loop.cycle(...args)`: Returns a value from the passed sequence in a cycle.
229//!
230//! A special note on iterators: in the current version of MiniJinja, some sequences are actually
231//! lazy iterators. They behave a bit like sequences not not entirely. They can be iterated over,
232//! will happily serialize once into a a list etc. However when iterating over an actual iterator,
233//! `last`, `revindex` and `revindex0` will always be undefined.
234//!
235//! Within a for-loop, it’s possible to cycle among a list of strings/variables each time through
236//! the loop by using the special `loop.cycle` helper:
237//!
238//! ```jinja
239//! {% for row in rows %}
240//! <li class="{{ loop.cycle('odd', 'even') }}">{{ row }}</li>
241//! {% endfor %}
242//! ```
243//!
244//! A `loop.changed()` helper is also available which can be used to detect when
245//! a value changes between the last iteration and the current one. The method
246//! takes one or more arguments that are all compared.
247//!
248//! ```jinja
249//! {% for entry in entries %}
250//! {% if loop.changed(entry.category) %}
251//! <h2>{{ entry.category }}</h2>
252//! {% endif %}
253//! <p>{{ entry.message }}</p>
254//! {% endfor %}
255//! ```
256//!
257//! Unlike in Rust or Python, it’s not possible to break or continue in a loop. You can,
258//! however, filter the sequence during iteration, which allows you to skip items. The
259//! following example skips all the users which are hidden:
260//!
261//! ```jinja
262//! {% for user in users if not user.hidden %}
263//! <li>{{ user.username }}</li>
264//! {% endfor %}
265//! ```
266//!
267//! If no iteration took place because the sequence was empty or the filtering
268//! removed all the items from the sequence, you can render a default block by
269//! using else:
270//!
271//! ```jinja
272//! <ul>
273//! {% for user in users %}
274//! <li>{{ user.username }}</li>
275//! {% else %}
276//! <li><em>no users found</em></li>
277//! {% endfor %}
278//! </ul>
279//! ```
280//!
281//! It is also possible to use loops recursively. This is useful if you are
282//! dealing with recursive data such as sitemaps. To use loops recursively, you
283//! basically have to add the ``recursive`` modifier to the loop definition and
284//! call the loop variable with the new iterable where you want to recurse.
285//!
286//! ```jinja
287//! <ul class="menu">
288//! {% for item in menu recursive %}
289//! <li><a href="{{ item.href }}">{{ item.title }}</a>
290//! {% if item.children %}
291//! <ul class="submenu">{{ loop(item.children) }}</ul>
292//! {% endif %}</li>
293//! {% endfor %}
294//! </ul>
295//! ```
296//!
297//! The loop can also be recursed from templates included within the loop and
298//! from blocks within the loop. Macros however cannot recurse loops, not even
299//! if the loop is passed to them.
300//!
301//! **Special note:** the `previtem` and `nextitem` attributes are available by default
302//! but can be disabled by removing the `adjacent_loop_items` crate feature. Removing
303//! these attributes can provide meaningful speedups for templates with a lot of loops.
304//!
305//! ## `{% if %}`
306//!
307//! The `if` statement is comparable with the Python if statement. In the simplest form,
308//! you can use it to test if a variable is defined, not empty and not false:
309//!
310//! ```jinja
311//! {% if users %}
312//! <ul>
313//! {% for user in users %}
314//! <li>{{ user.username }}</li>
315//! {% endfor %}
316//! </ul>
317//! {% endif %}
318//! ```
319//!
320//! For multiple branches, `elif` and `else` can be used like in Python. You can use more
321//! complex expressions there too:
322//!
323//! ```jinja
324//! {% if kenny.sick %}
325//! Kenny is sick.
326//! {% elif kenny.dead %}
327//! You killed Kenny! You bastard!!!
328//! {% else %}
329//! Kenny looks okay --- so far
330//! {% endif %}
331//! ```
332//!
333//! ## `{% extends %}`
334//!
335//! **Feature:** `multi_template` (included by default)
336//!
337//! The `extends` tag can be used to extend one template from another. You can have multiple
338//! `extends` tags in a file, but only one of them may be executed at a time. For more
339//! information see [block](#-block-).
340//!
341//! ## `{% block %}`
342//!
343//! Blocks are used for inheritance and act as both placeholders and replacements at the
344//! same time:
345//!
346//! The most powerful part of MiniJinja is template inheritance. Template inheritance allows
347//! you to build a base "skeleton" template that contains all the common elements of your
348//! site and defines **blocks** that child templates can override.
349//!
350//! **Base Template:**
351//!
352//! This template, which we'll call ``base.html``, defines a simple HTML skeleton
353//! document that you might use for a simple two-column page. It's the job of
354//! "child" templates to fill the empty blocks with content:
355//!
356//! ```jinja
357//! <!doctype html>
358//! {% block head %}
359//! <title>{% block title %}{% endblock %}</title>
360//! {% endblock %}
361//! {% block body %}{% endblock %}
362//! ```
363//!
364//! **Child Template:**
365//!
366//! ```jinja
367//! {% extends "base.html" %}
368//! {% block title %}Index{% endblock %}
369//! {% block head %}
370//! {{ super() }}
371//! <style type="text/css">
372//! .important { color: #336699; }
373//! </style>
374//! {% endblock %}
375//! {% block body %}
376//! <h1>Index</h1>
377//! <p class="important">
378//! Welcome to my awesome homepage.
379//! </p>
380//! {% endblock %}
381//! ```
382//!
383//! The ``{% extends %}`` tag is the key here. It tells the template engine that
384//! this template "extends" another template. When the template system evaluates
385//! this template, it first locates the parent. The extends tag should be the
386//! first tag in the template.
387//!
388//! As you can see it's also possible to render the contents of the parent block by calling
389//! ``super()``. You can’t define multiple ``{% block %}`` tags with the same name in
390//! the same template. This limitation exists because a block tag works in “both”
391//! directions. That is, a block tag doesn’t just provide a placeholder to fill -
392//! it also defines the content that fills the placeholder in the parent. If
393//! there were two similarly-named ``{% block %}`` tags in a template, that
394//! template’s parent wouldn’t know which one of the blocks’ content to use.
395//!
396//! If you want to print a block multiple times, you can, however, use the
397//! special self variable and call the block with that name:
398//!
399//! ```jinja
400//! <title>{% block title %}{% endblock %}</title>
401//! <h1>{{ self.title() }}</h1>
402//! {% block body %}{% endblock %}
403//! ```
404//!
405//! MiniJinja allows you to put the name of the block after the end tag for better
406//! readability:
407//!
408//! ```jinja
409//! {% block sidebar %}
410//! {% block inner_sidebar %}
411//! ...
412//! {% endblock inner_sidebar %}
413//! {% endblock sidebar %}
414//! ```
415//!
416//! However, the name after the `endblock` word must match the block name.
417//!
418//! ## `{% include %}`
419//!
420//! **Feature:** `multi_template` (included by default)
421//!
422//! The `include` tag is useful to include a template and return the rendered contents of that file
423//! into the current namespace:
424//!
425//! ```jinja
426//! {% include 'header.html' %}
427//! Body
428//! {% include 'footer.html' %}
429//! ```
430//!
431//! Optionally `ignore missing` can be added in which case non existing templates
432//! are silently ignored.
433//!
434//! ```jinja
435//! {% include 'customization.html' ignore missing %}
436//! ```
437//!
438//! You can also provide a list of templates that are checked for existence
439//! before inclusion. The first template that exists will be included. If `ignore
440//! missing` is set, it will fall back to rendering nothing if none of the
441//! templates exist, otherwise it will fail with an error.
442//!
443//! ```jinja
444//! {% include ['page_detailed.html', 'page.html'] %}
445//! {% include ['special_sidebar.html', 'sidebar.html'] ignore missing %}
446//! ```
447//!
448//! Included templates have access to the variables of the active context.
449//!
450//! ## `{% import %}`
451//!
452//! **Feature:** `multi_template` (included by default)
453//!
454//! MiniJinja supports the `{% import %}` and `{% from ... import ... %}`
455//! syntax. With it variables or macros can be included from other templates:
456//!
457//! ```jinja
458//! {% from "my_template.html" import my_macro, my_variable %}
459//! ```
460//!
461//! Imports can also be aliased:
462//!
463//! ```jinja
464//! {% from "my_template.html" import my_macro as other_name %}
465//! {{ other_name() }}
466//! ```
467//!
468//! Full modules can be imported with `{% import ... as ... %}`:
469//!
470//! ```jinja
471//! {% import "my_template.html" as helpers %}
472//! {{ helpers.my_macro() }}
473//! ```
474//!
475//! Note that unlike Jinja2, exported modules do not contain any template code. Only
476//! variables and macros that are defined can be imported. Also imports unlike in Jinja2
477//! are not cached and they get access to the full template context.
478//!
479//! Like in Jinja2, macros and variables starting with one or more underscores
480//! are private and cannot be imported. They are not exported as attributes of
481//! the module, and attempting to import them with `{% from ... import ... %}` is
482//! a syntax error.
483//!
484//! ## `{% with %}`
485//!
486//! The with statement makes it possible to create a new inner scope. Variables set within
487//! this scope are not visible outside of the scope:
488//!
489//! ```jinja
490//! {% with foo = 42 %}
491//! {{ foo }} foo is 42 here
492//! {% endwith %}
493//! foo is not visible here any longer
494//! ```
495//!
496//! Multiple variables can be set at once and unpacking is supported:
497//!
498//! ```jinja
499//! {% with a = 1, (b, c) = [2, 3] %}
500//! {{ a }}, {{ b }}, {{ c }} (outputs 1, 2, 3)
501//! {% endwith %}
502//! ```
503//!
504//! ## `{% set %}`
505//!
506//! The `set` statement can be used to assign to variables on the same scope. This is
507//! similar to how `with` works but it won't introduce a new scope.
508//!
509//! ```jinja
510//! {% set navigation = [('index.html', 'Index'), ('about.html', 'About')] %}
511//! ```
512//!
513//! Please keep in mind that it is not possible to set variables inside a block
514//! and have them show up outside of it. This also applies to loops. The only
515//! exception to that rule are if statements which do not introduce a scope.
516//!
517//! It's also possible to capture blocks of template code into a variable by using
518//! the `set` statement as a block. In that case, instead of using an equals sign
519//! and a value, you just write the variable name and then everything until
520//! `{% endset %}` is captured.
521//!
522//! ```jinja
523//! {% set navigation %}
524//! <li><a href="/">Index</a>
525//! <li><a href="/downloads">Downloads</a>
526//! {% endset %}
527//! ```
528//!
529//! The `navigation` variable then contains the navigation HTML source.
530//!
531//! This can also be combined with applying a filter:
532//!
533//! ```jinja
534//! {% set title | upper %}Title of the page{% endset %}
535//! ```
536//!
537//! More complex use cases can be handled using namespace objects which allow
538//! propagating of changes across scopes:
539//!
540//! ```jinja
541//! {% set ns = namespace(found=false) %}
542//! {% for item in items %}
543//! {% if item.check_something() %}
544//! {% set ns.found = true %}
545//! {% endif %}
546//! * {{ item.title }}
547//! {% endfor %}
548//! Found item having something: {{ ns.found }}
549//! ```
550//!
551//! Note that the `obj.attr` notation in the set tag is only allowed for namespace
552//! objects; attempting to assign an attribute on any other object will cause
553//! an error.
554//!
555//! ## `{% filter %}`
556//!
557//! Filter sections allow you to apply regular [filters](crate::filters) on a
558//! block of template data. Just wrap the code in the special filter block:
559//!
560//! ```jinja
561//! {% filter upper %}
562//! This text becomes uppercase
563//! {% endfilter %}
564//! ```
565//!
566//! ## `{% macro %}`
567//!
568//! **Feature:** `macros` (included by default)
569//!
570//! MiniJinja has limited support for macros. They allow you to write reusable
571//! template functions. They are useful to put often used idioms into reusable
572//! functions so you don't repeat yourself (“DRY”).
573//!
574//! Here’s a small example of a macro that renders a form element:
575//!
576//! ```jinja
577//! {% macro input(name, value="", type="text") -%}
578//! <input type="{{ type }}" name="{{ name }}" value="{{ value }}">
579//! {%- endmacro %}
580//! ```
581//!
582//! The macro can then be called like a function in the namespace:
583//!
584//! ```jinja
585//! <p>{{ input('username') }}</p>
586//! <p>{{ input('password', type='password') }}</p>
587//! ```
588//!
589//! The behavior of macros with regards to undefined variables is that they capture
590//! them at macro declaration time (eg: they use a closure).
591//!
592//! Macros can be imported via `{% import %}` or `{% from ... import %}`.
593//!
594//! Macros also accept a hidden `caller` keyword argument for the use with
595//! `{% call %}`.
596//!
597//! ## `{% call %}`
598//!
599//! **Feature:** `macros` (included by default)
600//!
601//! This tag functions similar to a macro that is passed to another macro. You can
602//! think of it as a way to declare an anonymous macro and pass it to another macro
603//! with the `caller` keyword argument. The following example shows a macro that
604//! takes advantage of the call functionality and how it can be used:
605//!
606//! ```jinja
607//! {% macro dialog(title) %}
608//! <div class="dialog">
609//! <h3>{{ title }}</h3>
610//! <div class="contents">{{ caller() }}</div>
611//! </div>
612//! {% endmacro %}
613//!
614//! {% call dialog(title="Hello World") %}
615//! This is the dialog body.
616//! {% endcall %}
617//! ```
618//!
619//! <details><summary><strong style="cursor: pointer">Macro Alternative:</strong></summary>
620//!
621//! The above example is more or less equivalent with the following:
622//!
623//! ```jinja
624//! {% macro dialog(title) %}
625//! <div class="dialog">
626//! <h3>{{ title }}</h3>
627//! <div class="contents">{{ caller() }}</div>
628//! </div>
629//! {% endmacro %}
630//!
631//! {% macro caller() %}
632//! This is the dialog body.
633//! {% endmacro %}
634//! {{ dialog(title="Hello World", caller=caller) }}
635//! ```
636//!
637//! </details>
638//!
639//! It’s also possible to pass arguments back to the call block. This makes it
640//! useful to build macros that behave like if statements or loops. Arguments
641//! are placed surrounded in parentheses right after the `call` keyword and
642//! is followed by the macro to be called.
643//!
644//! ```jinja
645//! {% macro render_user_list(users) %}
646//! <ul>
647//! {% for user in users %}
648//! <li><p>{{ user.username }}</p>{{ caller(user) }}</li>
649//! {% endfor %}
650//! </ul>
651//! {% endmacro %}
652//!
653//! {% call(user) render_user_list(list_of_user) %}
654//! <dl>
655//! <dt>Name</dt>
656//! <dd>{{ user.name }}</dd>
657//! <dt>E-Mail</dt>
658//! <dd>{{ user.email }}</dd>
659//! </dl>
660//! {% endcall %}
661//! ```
662//!
663//! ## `{% do %}`
664//!
665//! The do tag has the same functionality as regular template tags (`{{ ... }}`);
666//! except it doesn't output anything when called.
667//!
668//! This is useful if you have a function or macro that has a side-effect, and
669//! you don’t want to display output in the template. The following example
670//! shows a macro that uses the do functionality, and how it can be used:
671//!
672//! ```jinja
673//! {% macro dialog(title) %}
674//! Dialog is {{ title }}
675//! {% endmacro %}
676//!
677//! {% do dialog(title="Hello World") %} <- does not output anything
678//! ```
679//!
680//! The above example will not output anything when using the `do` tag.
681//!
682//! This tag exists for consistency with Jinja2 and can be useful if you have
683//! custom functionality in templates that uses side-effects. For instance if
684//! you expose a function to templates that can be used to log warnings:
685//!
686//! ```jinja
687//! {% for user in users %}
688//! {% if user.deleted %}
689//! {% log warn("Found unexpected deleted user in template") %}
690//! {% endif %}
691//! ...
692//! {% endfor %}
693//! ```
694//!
695//! ## `{% autoescape %}`
696//!
697//! If you want you can activate and deactivate the autoescaping from within
698//! the templates.
699//!
700//! Example:
701//!
702//! ```jinja
703//! {% autoescape true %}
704//! Autoescaping is active within this block
705//! {% endautoescape %}
706//!
707//! {% autoescape false %}
708//! Autoescaping is inactive within this block
709//! {% endautoescape %}
710//! ```
711//!
712//! After an `endautoescape` the behavior is reverted to what it was before.
713//!
714//! The exact auto escaping behavior is determined by the value of
715//! [`AutoEscape`](crate::AutoEscape) set to the template.
716//!
717//! ## `{% raw %}`
718//!
719//! A raw block is a special construct that lets you ignore the embedded template
720//! syntax. This is particularly useful if a segment of template code would
721//! otherwise require constant escaping with things like `{{ "{{" }}`:
722//!
723//! Example:
724//!
725//! ```jinja
726//! {% raw %}
727//! <ul>
728//! {% for item in seq %}
729//! <li>{{ item }}</li>
730//! {% endfor %}
731//! </ul>
732//! {% endraw %}
733//! ```
734//!
735//! ## `{% break %}` / `{% continue %}`
736//!
737//! If MiniJinja was compiled with the `loop_controls` feature, it’s possible to
738//! use `break` and `continue` in loops. When break is reached, the loop is
739//! terminated; if continue is reached, the processing is stopped and continues
740//! with the next iteration.
741//!
742//! Here’s a loop that skips every second item:
743//!
744//! ```jinja
745//! {% for user in users %}
746//! {%- if loop.index is even %}{% continue %}{% endif %}
747//! ...
748//! {% endfor %}
749//! ```
750//!
751//! Likewise, a loop that stops processing after the 10th iteration:
752//!
753//! ```jinja
754//! {% for user in users %}
755//! {%- if loop.index >= 10 %}{% break %}{% endif %}
756//! {%- endfor %}
757//! ```
758//!
759//! **Note on one-shot iterators:** if you break from a loop but you have
760//! accessed the `loop.nextitem` special variable, then you will lose one item.
761//! This is because accessing that attribute will peak into the iterator and
762//! there is no support for "putting values back".
763//!
764//! # Custom Delimiters
765//!
766//! It's possible to reconfigure the delimiters of the templates (see
767//! [`SyntaxConfig`]). This is generally not recommended but it's useful for situations
768//! where Jinja templates are used to generate files with a syntax that would be
769//! conflicting for Jinja. With custom delimiters it can for instance be more
770//! convenient to generate LaTeX files:
771//!
772//! ```
773//! # use minijinja::{Environment, syntax::SyntaxConfig};
774//! let mut environment = Environment::new();
775//! environment.set_syntax(SyntaxConfig::builder()
776//! .block_delimiters("\\BLOCK{", "}")
777//! .variable_delimiters("\\VAR{", "}")
778//! .comment_delimiters("\\#{", "}")
779//! .build()
780//! .unwrap()
781//! );
782//! ```
783//!
784//! And then a template might look like this instead:
785//!
786//! ```latex
787//! \begin{itemize}
788//! \BLOCK{for item in sequence}
789//! \item \VAR{item}
790//! \BLOCK{endfor}
791//! \end{itemize}
792//! ```
793//!
794//! # Line Statements and Comments
795//!
796//! MiniJinja supports line statements and comments like Jinja2 does. Line statements
797//! and comments are an alternative syntax feature where blocks can be placed on their
798//! own line if they are opened with a configured prefix. They must appear on their own
799//! line but can be prefixed with whitespace. Line comments are similar but they can
800//! also be trailing. These syntax features need to be configured explicitly.
801//! There are however small differences with regards to whitespace compared to
802//! Jinja2.
803//!
804//! To use line statements and comments they need to be configured (see
805//! [`SyntaxConfig`]).
806//!
807//! ```
808//! # use minijinja::{Environment, syntax::SyntaxConfig};
809//! let mut environment = Environment::new();
810//! environment.set_syntax(SyntaxConfig::builder()
811//! .line_statement_prefix("#")
812//! .line_comment_prefix("##")
813//! .build()
814//! .unwrap()
815//! );
816//! ```
817//!
818//! With the above config you can render a template like this:
819//!
820//! ```jinja
821//! ## This block is
822//! ## completely removed
823//! <ul>
824//! # for item in [1, 2]
825//! ## this is a comment that is also removed including leading whitespace
826//! <li>{{ item }}
827//! # endfor
828//! </ul>
829//! ```
830//!
831//! Renders into the following HTML:
832//!
833//! ```html
834//! <ul>
835//! <li>1
836//! <li>2
837//! </ul>
838//! ```
839//!
840//! Note that this is slightly different than in Jinja2. Specifically the following
841//! rules apply with regards to whitespace:
842//!
843//! * line statements remove all whitespace before and after including the newline
844//! * line comments remove the trailing newline and leading whitespace.
845//!
846//! This is different than in Jinja2 where empty lines can remain from line comments.
847//! Additionally whitespace control is not available for line statements.
848//!
849//! # Whitespace Control
850//!
851//! MiniJinja shares the same behavior with Jinja2 when it comes to
852//! whitespace handling. By default a single trailing newline is stripped if present
853//! and all other whitespace is returned unchanged.
854//!
855//! If an application configures Jinja to [`trim_blocks`](SyntaxConfigBuilder::trim_blocks),
856//! the first newline after a template tag is removed automatically (like in PHP). The
857//! [`lstrip_blocks`](SyntaxConfigBuilder::lstrip_blocks) option can also be set to strip
858//! tabs and spaces from the beginning of a line to the start of a block. (Nothing will be
859//! stripped if there are other characters before the start of the block.)
860//!
861//! With both `trim_blocks` and `lstrip_blocks` enabled, you can put block tags on their
862//! own lines, and the entire block line will be removed when rendered, preserving the
863//! whitespace of the contents.
864//!
865//! For example, without the `trim_blocks` and `lstrip_blocks` options, this template:
866//!
867//! ```jinja
868//! <div>
869//! {% if True %}
870//! yay
871//! {% endif %}
872//! </div>
873//! ```
874//!
875//! gets rendered with blank lines inside the div:
876//!
877//! ```jinja
878//! <div>
879//!
880//! yay
881//!
882//! </div>
883//! ```
884//!
885//! But with both `trim_blocks` and `lstrip_blocks` enabled, the template block lines
886//! are removed and other whitespace is preserved:
887//!
888//! ```jinja
889//! <div>
890//! yay
891//! </div>
892//! ````
893//!
894//! You can manually disable the `lstrip_blocks` behavior by putting a plus sign (`+`)
895//! at the start of a block:
896//!
897//! ```jinja
898//! <div>
899//! {%+ if something %}yay{% endif %}
900//! </div>
901//! ```
902//!
903//! Similarly, you can manually disable the `trim_blocks` behavior by putting a plus
904//! sign (`+`) at the end of a block:
905//!
906//! ```jinja
907//! <div>
908//! {% if something +%}
909//! yay
910//! {% endif %}
911//! </div>
912//! ```
913//!
914//! You can also strip whitespace in templates by hand. If you add a minus sign (`-`) to the
915//! start or end of a block (e.g. a for tag), a comment, or a variable expression, the
916//! whitespaces before or after that block will be removed:
917//!
918//! ```jinja
919//! {% for item in range(1, 10) -%}
920//! {{ item }}
921//! {%- endfor %}
922//! ```
923//!
924//! This will yield all elements without whitespace between them, in this case
925//! the output would be `123456789`.
926//!
927//! By default, MiniJinja also removes trailing newlines. To keep single trailing newlines,
928//! configure MiniJinja to [`keep_trailing_newline`](SyntaxConfigBuilder::keep_trailing_newline).
929//!
930//! All of these options are part of the [`SyntaxConfig`]:
931//!
932//! ```
933//! # use minijinja::{Environment, syntax::SyntaxConfig};
934//! let mut env = Environment::new();
935//! env.set_syntax(
936//! SyntaxConfig::builder()
937//! .trim_blocks(true)
938//! .lstrip_blocks(true)
939//! .build()
940//! .unwrap(),
941//! );
942//! ```
943
944use std::borrow::Cow;
945use std::sync::{Arc, OnceLock};
946
947use crate::compiler::lexer::{StartMarker, WhitespaceConfig};
948use crate::error::{Error, ErrorKind};
949use crate::utils::memchr_any;
950
951#[derive(Debug, PartialEq, Clone)]
952pub(crate) struct Delims {
953 block_start: Cow<'static, str>,
954 block_end: Cow<'static, str>,
955 variable_start: Cow<'static, str>,
956 variable_end: Cow<'static, str>,
957 comment_start: Cow<'static, str>,
958 comment_end: Cow<'static, str>,
959 line_statement_prefix: Cow<'static, str>,
960 line_comment_prefix: Cow<'static, str>,
961}
962
963const DEFAULT_DELIMS: Delims = Delims {
964 block_start: Cow::Borrowed("{%"),
965 block_end: Cow::Borrowed("%}"),
966 variable_start: Cow::Borrowed("{{"),
967 variable_end: Cow::Borrowed("}}"),
968 comment_start: Cow::Borrowed("{#"),
969 comment_end: Cow::Borrowed("#}"),
970 line_statement_prefix: Cow::Borrowed(""),
971 line_comment_prefix: Cow::Borrowed(""),
972};
973
974fn default_delims() -> Arc<Delims> {
975 static DEFAULT_DELIMS_ARC: OnceLock<Arc<Delims>> = OnceLock::new();
976 DEFAULT_DELIMS_ARC
977 .get_or_init(|| Arc::new(DEFAULT_DELIMS))
978 .clone()
979}
980
981/// Finds the leftmost (and at that position longest) start marker.
982///
983/// There are at most five start patterns and they are typically very short,
984/// so instead of a full multi-pattern automaton this scans for the (at most
985/// five) possible first bytes to find candidate positions and then checks the
986/// patterns (longest first) at those positions.
987#[derive(Debug)]
988pub(crate) struct StartMarkerMatcher {
989 /// Start patterns sorted by length, longest first.
990 patterns: Vec<(Cow<'static, str>, StartMarker)>,
991 /// All bytes a start pattern can begin with. Unused slots repeat
992 /// an existing byte.
993 first_bytes: [u8; 5],
994}
995
996impl StartMarkerMatcher {
997 fn new(delims: &Delims) -> Result<StartMarkerMatcher, Error> {
998 if delims.block_end.is_empty()
999 || delims.variable_end.is_empty()
1000 || delims.comment_end.is_empty()
1001 {
1002 return Err(ErrorKind::InvalidDelimiter.into());
1003 }
1004
1005 let mut patterns = Vec::<(Cow<'static, str>, StartMarker)>::with_capacity(5);
1006 for (delim, marker, required) in [
1007 (&delims.variable_start, StartMarker::Variable, true),
1008 (&delims.block_start, StartMarker::Block, true),
1009 (&delims.comment_start, StartMarker::Comment, true),
1010 (
1011 &delims.line_statement_prefix,
1012 StartMarker::LineStatement,
1013 false,
1014 ),
1015 (&delims.line_comment_prefix, StartMarker::LineComment, false),
1016 ] {
1017 if delim.is_empty() {
1018 if required {
1019 return Err(ErrorKind::InvalidDelimiter.into());
1020 }
1021 } else if patterns.iter().any(|(x, _)| x == delim) {
1022 return Err(ErrorKind::InvalidDelimiter.into());
1023 } else {
1024 patterns.push((delim.clone(), marker));
1025 }
1026 }
1027
1028 // stable sort keeps the declaration order for equally long patterns
1029 patterns.sort_by_key(|(x, _)| std::cmp::Reverse(x.len()));
1030 let mut first_bytes = [patterns[0].0.as_bytes()[0]; 5];
1031 for (idx, (pattern, _)) in patterns.iter().enumerate() {
1032 first_bytes[idx] = pattern.as_bytes()[0];
1033 }
1034
1035 Ok(StartMarkerMatcher {
1036 patterns,
1037 first_bytes,
1038 })
1039 }
1040
1041 /// Finds the leftmost start marker at or after `offset`.
1042 ///
1043 /// Returns the position (relative to `offset`), the marker and the
1044 /// length of the marker. Line statements are only matched if they are
1045 /// only preceded by spaces or tabs on their line.
1046 pub(crate) fn find(&self, source: &str, offset: usize) -> Option<(usize, StartMarker, usize)> {
1047 let all_bytes = source.as_bytes();
1048 let bytes = &all_bytes[offset..];
1049 let mut pos = 0;
1050 loop {
1051 pos += some!(memchr_any(&bytes[pos..], self.first_bytes));
1052 let rest = &bytes[pos..];
1053 for (pattern, marker) in &self.patterns {
1054 if !rest.starts_with(pattern.as_bytes()) {
1055 continue;
1056 }
1057 if *marker == StartMarker::LineStatement
1058 && !matches!(
1059 all_bytes[..offset + pos]
1060 .iter()
1061 .rev()
1062 .find(|&&x| x != b' ' && x != b'\t'),
1063 None | Some(b'\r') | Some(b'\n')
1064 )
1065 {
1066 continue;
1067 }
1068 return Some((pos, *marker, pattern.len()));
1069 }
1070 pos += 1;
1071 }
1072 }
1073}
1074
1075/// Builder helper to reconfigure the syntax.
1076///
1077/// A new builder is returned by [`SyntaxConfig::builder`]. To modify an
1078/// existing configuration use [`SyntaxConfig::to_builder`].
1079#[derive(Debug, Clone)]
1080pub struct SyntaxConfigBuilder {
1081 delims: Arc<Delims>,
1082 whitespace: WhitespaceConfig,
1083}
1084
1085impl SyntaxConfigBuilder {
1086 /// Sets the block start and end delimiters.
1087 pub fn block_delimiters<S, E>(&mut self, s: S, e: E) -> &mut Self
1088 where
1089 S: Into<Cow<'static, str>>,
1090 E: Into<Cow<'static, str>>,
1091 {
1092 let delims = Arc::make_mut(&mut self.delims);
1093 delims.block_start = s.into();
1094 delims.block_end = e.into();
1095 self
1096 }
1097
1098 /// Sets the variable start and end delimiters.
1099 pub fn variable_delimiters<S, E>(&mut self, s: S, e: E) -> &mut Self
1100 where
1101 S: Into<Cow<'static, str>>,
1102 E: Into<Cow<'static, str>>,
1103 {
1104 let delims = Arc::make_mut(&mut self.delims);
1105 delims.variable_start = s.into();
1106 delims.variable_end = e.into();
1107 self
1108 }
1109
1110 /// Sets the comment start and end delimiters.
1111 pub fn comment_delimiters<S, E>(&mut self, s: S, e: E) -> &mut Self
1112 where
1113 S: Into<Cow<'static, str>>,
1114 E: Into<Cow<'static, str>>,
1115 {
1116 let delims = Arc::make_mut(&mut self.delims);
1117 delims.comment_start = s.into();
1118 delims.comment_end = e.into();
1119 self
1120 }
1121
1122 /// Sets the line statement prefix.
1123 ///
1124 /// By default this is the empty string which disables the line
1125 /// statement prefix feature.
1126 pub fn line_statement_prefix<S>(&mut self, s: S) -> &mut Self
1127 where
1128 S: Into<Cow<'static, str>>,
1129 {
1130 let delims = Arc::make_mut(&mut self.delims);
1131 delims.line_statement_prefix = s.into();
1132 self
1133 }
1134
1135 /// Sets the line comment prefix.
1136 ///
1137 /// By default this is the empty string which disables the line
1138 /// comment prefix feature.
1139 pub fn line_comment_prefix<S>(&mut self, s: S) -> &mut Self
1140 where
1141 S: Into<Cow<'static, str>>,
1142 {
1143 let delims = Arc::make_mut(&mut self.delims);
1144 delims.line_comment_prefix = s.into();
1145 self
1146 }
1147
1148 /// Remove the first newline after a block.
1149 ///
1150 /// If this is set to `true` then the first newline after a block is removed
1151 /// (block, not variable tag!). Defaults to `false`.
1152 pub fn trim_blocks(&mut self, yes: bool) -> &mut Self {
1153 self.whitespace.trim_blocks = yes;
1154 self
1155 }
1156
1157 /// Remove leading spaces and tabs from the start of a line to a block.
1158 ///
1159 /// If this is set to `true` then leading spaces and tabs from the start of a line
1160 /// to the block tag are removed. Defaults to `false`.
1161 pub fn lstrip_blocks(&mut self, yes: bool) -> &mut Self {
1162 self.whitespace.lstrip_blocks = yes;
1163 self
1164 }
1165
1166 /// Preserve the trailing newline when rendering templates.
1167 ///
1168 /// The default is `false`, which causes a single newline, if present, to be
1169 /// stripped from the end of the template.
1170 pub fn keep_trailing_newline(&mut self, yes: bool) -> &mut Self {
1171 self.whitespace.keep_trailing_newline = yes;
1172 self
1173 }
1174
1175 /// Builds the final syntax config.
1176 ///
1177 /// This fails if the configured delimiters are invalid.
1178 pub fn build(&self) -> Result<SyntaxConfig, Error> {
1179 if *self.delims == DEFAULT_DELIMS {
1180 return Ok(SyntaxConfig {
1181 delims: default_delims(),
1182 start_marker_matcher: None,
1183 whitespace: self.whitespace,
1184 });
1185 }
1186 let matcher = ok!(StartMarkerMatcher::new(&self.delims));
1187 Ok(SyntaxConfig {
1188 delims: self.delims.clone(),
1189 start_marker_matcher: Some(Arc::new(matcher)),
1190 whitespace: self.whitespace,
1191 })
1192 }
1193}
1194
1195/// The syntax configuration for the environment and the parser.
1196///
1197/// The syntax configuration controls how templates are tokenized. This
1198/// includes the whitespace behavior ([`trim_blocks`](SyntaxConfigBuilder::trim_blocks),
1199/// [`lstrip_blocks`](SyntaxConfigBuilder::lstrip_blocks) and
1200/// [`keep_trailing_newline`](SyntaxConfigBuilder::keep_trailing_newline)) and
1201/// the delimiters.
1202///
1203/// ```
1204/// # use minijinja::{Environment, syntax::SyntaxConfig};
1205/// let mut environment = Environment::new();
1206/// environment.set_syntax(
1207/// SyntaxConfig::builder()
1208/// .trim_blocks(true)
1209/// .lstrip_blocks(true)
1210/// .build()
1211/// .unwrap()
1212/// );
1213/// ```
1214///
1215/// The delimiters can be customized as well. The end markers can be shared,
1216/// but the start markers need to be distinct. It would thus not be valid to
1217/// configure `{{` to be the marker for both variables and blocks.
1218///
1219/// ```
1220/// # use minijinja::{Environment, syntax::SyntaxConfig};
1221/// let mut environment = Environment::new();
1222/// environment.set_syntax(
1223/// SyntaxConfig::builder()
1224/// .block_delimiters("\\BLOCK{", "}")
1225/// .variable_delimiters("\\VAR{", "}")
1226/// .comment_delimiters("\\#{", "}")
1227/// .build()
1228/// .unwrap()
1229/// );
1230/// ```
1231#[derive(Clone, Debug)]
1232pub struct SyntaxConfig {
1233 delims: Arc<Delims>,
1234 pub(crate) start_marker_matcher: Option<Arc<StartMarkerMatcher>>,
1235 whitespace: WhitespaceConfig,
1236}
1237
1238impl Default for SyntaxConfig {
1239 fn default() -> Self {
1240 Self {
1241 delims: default_delims(),
1242 start_marker_matcher: None,
1243 whitespace: WhitespaceConfig::default(),
1244 }
1245 }
1246}
1247
1248impl SyntaxConfig {
1249 /// Creates a syntax builder with the default configuration.
1250 pub fn builder() -> SyntaxConfigBuilder {
1251 SyntaxConfig::default().to_builder()
1252 }
1253
1254 /// Creates a syntax builder initialized from this configuration.
1255 ///
1256 /// This is useful to change individual settings of an existing
1257 /// configuration:
1258 ///
1259 /// ```
1260 /// # use minijinja::Environment;
1261 /// let mut env = Environment::new();
1262 /// let syntax = env.syntax().to_builder().trim_blocks(true).build().unwrap();
1263 /// env.set_syntax(syntax);
1264 /// ```
1265 pub fn to_builder(&self) -> SyntaxConfigBuilder {
1266 SyntaxConfigBuilder {
1267 delims: self.delims.clone(),
1268 whitespace: self.whitespace,
1269 }
1270 }
1271
1272 /// Returns the block delimiters.
1273 #[inline(always)]
1274 pub fn block_delimiters(&self) -> (&str, &str) {
1275 (&self.delims.block_start, &self.delims.block_end)
1276 }
1277
1278 /// Returns the variable delimiters.
1279 #[inline(always)]
1280 pub fn variable_delimiters(&self) -> (&str, &str) {
1281 (&self.delims.variable_start, &self.delims.variable_end)
1282 }
1283
1284 /// Returns the comment delimiters.
1285 #[inline(always)]
1286 pub fn comment_delimiters(&self) -> (&str, &str) {
1287 (&self.delims.comment_start, &self.delims.comment_end)
1288 }
1289
1290 /// Returns the line statement prefix.
1291 #[inline(always)]
1292 pub fn line_statement_prefix(&self) -> Option<&str> {
1293 Some(&self.delims.line_statement_prefix as &str).filter(|x| !x.is_empty())
1294 }
1295
1296 /// Returns the line comment prefix.
1297 #[inline(always)]
1298 pub fn line_comment_prefix(&self) -> Option<&str> {
1299 Some(&self.delims.line_comment_prefix as &str).filter(|x| !x.is_empty())
1300 }
1301
1302 /// Returns `true` if the first newline after a block is removed.
1303 #[inline(always)]
1304 pub fn trim_blocks(&self) -> bool {
1305 self.whitespace.trim_blocks
1306 }
1307
1308 /// Returns `true` if leading spaces and tabs before a block are removed.
1309 #[inline(always)]
1310 pub fn lstrip_blocks(&self) -> bool {
1311 self.whitespace.lstrip_blocks
1312 }
1313
1314 /// Returns `true` if a single trailing newline is preserved.
1315 #[inline(always)]
1316 pub fn keep_trailing_newline(&self) -> bool {
1317 self.whitespace.keep_trailing_newline
1318 }
1319
1320 /// Returns the whitespace configuration.
1321 #[inline(always)]
1322 pub(crate) fn whitespace(&self) -> WhitespaceConfig {
1323 self.whitespace
1324 }
1325}