Skip to main content

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}