From c7156ea6385e0ae76d4dc58e543a4f2ce4059115 Mon Sep 17 00:00:00 2001 From: gwen Date: Wed, 18 Mar 2026 12:22:45 +0100 Subject: [PATCH] add jinja section --- docs/tutorial/jinja.rst | 142 +++++++++++++++++++++++++++++++++++++++- 1 file changed, 140 insertions(+), 2 deletions(-) diff --git a/docs/tutorial/jinja.rst b/docs/tutorial/jinja.rst index 42b7598ce..434bdb61e 100644 --- a/docs/tutorial/jinja.rst +++ b/docs/tutorial/jinja.rst @@ -23,7 +23,7 @@ Playing with Jinja Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps. If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository `, - this workshop page corresponds to the tags :tutorial:`v1.1_070 ` to :tutorial:`v1.1_072 ` + this workshop page corresponds to the tags :tutorial:`v1.1_070 ` to :tutorial:`v1.1_073 ` in the repository. :: @@ -33,7 +33,7 @@ Playing with Jinja .. type-along:: Why the Jinja templating engine ? -We are going to embed some `Hinja templating code `_ in our structure file. +We are going to embed some `Jinja templating code `_ in our structure file. .. glossary:: @@ -438,6 +438,143 @@ So the Jinja code worked well since the `https_proxy` family is hidden only when the `use_for_https` variable is set to `true` and the identifier is HTTPS (the `socks_proxy` family, however, is not hidden). +Jinja could returns a boolean +--------------------------------- + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_073` version:: + + git switch --detach v1.1_073 + +So far, we have used a Jinja expression that could have a `True` value, +otherwise it returned nothing (i.e., None, that is a `False` value): + +.. code-block:: jinja + + {% if my_identifier == 'HTTPS' and _.use_for_https %} + HTTPS is same has HTTP + {% endif %} + +We have implicitly used the truthiness capabilities of Jinja, because the +`HTTPS is same has HTTP` expression is interpreted by Jinja as the `True` value and +the `""` (empty string) expression is interpreted by Jinja as the `False` value. +This behavior is known as implicit boolean coercion (or truthiness). + +.. type-along:: The truthiness of python or Jinja + +In Python or in Jinja, **every value has an inherent Boolean interpretation**—it +can be treated as either `True` or `False` in contexts that expect a Boolean +(like `if`, `while`, or logical operators). +This is often referred to as “truthiness.” +However, **not every value is an instance of the `bool` type**; +the `bool` type itself has only two instances: `True` and `False`. + +.. rubric:: Truthiness Rules + +- A value is considered **falsy** if it evaluates to `False` in a Boolean context. +- Otherwise, it is **truthy**. + +.. rubric:: Common Falsy Values + +- `None` +- `False` +- Zero of any numeric type: `0`, `0.0`, `0j`, `Decimal(0)`, `Fraction(0, 1)` +- Empty sequences/collections: `''`, `[]`, `()`, `{}`, `set()`, `range(0)` +- Objects that define `__bool__()` returning `False`, or `__len__()` returning `0` + +Everything else is truthy, including: + +- Non‑zero numbers +- Non‑empty strings, lists, tuples, dictionaries, etc. +- Most user‑defined class instances (unless they override `__bool__` or `__len__`) + +.. rubric:: Using truthiness in Code + +You can directly use any value in a conditional: + +.. code-block:: python + + if some_value: + print("Truthy") + else: + print("Falsy") + +.. type-along:: Jinja calcuation without truthiness + +This is truthiness capability is entirely possible with Rougail +but, in programming language theory, +it is a form of **implicit** type conversion +where a value of any type is automatically +interpreted as a boolean in contexts that expect one (e.g., conditionals). + +We like things to be declared explicitly. +It is a better practice to simply avoid this implicit coercion +and instead: + +- return a boolean value as the result of the Jinja expression +- explicitly declare that this expression shall return a boolean type + +Here is a Jinja code that return a boolean value: + + +.. code-block:: jinja + + {{ my_identifier == 'HTTPS' and _.use_for_https }} + +And in order to declare explicitly the use of this explicit non-truthiness pratice, +we add a `return_type` parameter in the `hiden` property: + + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_073/firefox/20-manual.yml + :language: yaml + :caption: The :file:`firefox/20-manual.yml` structure file with an explicit boolean declaration + + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + '{{ identifier }}_proxy': + description: '{{ identifier }} Proxy' + hidden: + jinja: |- + {{ my_identifier == 'HTTPS' and _.use_for_https }} + return_type: boolean + description: in HTTPS case if "_.use_for_https" is set to "true" + params: + my_identifier: + type: identifier + dynamic: + - HTTPS + - SOCKS + + address: + description: '{{ identifier }} address' + default: + variable: __.http_proxy.address + + port: + description: '{{ identifier }} port' + default: + variable: __.http_proxy.port + + version: + description: SOCKS host version used by proxy + choices: + - v4 + - v5 + default: v5 + disabled: + type: identifier + when: HTTPS + ... + .. keypoints:: Key points We have seen that the `disabled` or `hidden` properties could be calculated. @@ -449,6 +586,7 @@ the `use_for_https` variable is set to `true` and the identifier is HTTPS - we know how to describe a calcuation - we know how to output some documentation (in markdown or in html) of the :term:`configuration` - we can calculate with a dynamic family identifer + - we can set an explicit boolean jinja expression in a jinja calcuation **keywords**