stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

disabled

Browse source
This commit is contained in:
gwen 2026-01-05 13:59:56 +01:00
parent d47405c61d
commit 0008d03772
5 changed files with 121 additions and 98 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

6
docs/structfile.rst
View file

@ -55,7 +55,7 @@ The structured data
structured data
We sometimes call "structured datas" the datas that are defined in the structure files,
as opposed to :term:`user datas <user datas>`\ .
as opposed to :term:`user datas <user data>`\ .
For example when a value of a variable is defined in the structured datas, that is
in a structured file, the assigned value's status is that the variable's value is a default value.
If the assigned value of the variable is defined in a user data file,
@ -76,10 +76,10 @@ What contains exactly a :term:`structure file`?
A :term:`structure file` is a YAML file whose structure is described in this documentation page.
A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a :term:`template`
A structure file contains a set of variables loaded into :term:`Tiramisu`, usable in your application, for example in a template
to generate configuration files.
:term:`Families` and :term:`variables` can be defined in several structure files. These structure files are then aggregated.
:term:`Families <family>` and :term:`variables <variable>` can be defined in several structure files. These structure files are then aggregated.
If you want to see the contents of a structure file, you can have a look at the :ref:`tutorial with a real world sample. <tutorial>`

164
docs/tutorial/disabled.rst
View file

@ -67,8 +67,10 @@ Here we are going to assign the `disabled` property to the `manual` family:
type: port
default: 8080
We have this `disabled: true` property assigned to the `manual` family.
.. raw:: html
:class: terminal
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt
..
@ -80,7 +82,8 @@ The Rougail CLI outputs this:
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/output_ro.html
:class: output
We can deduce that the `manual` family is not taken into account by Rougail.
We can deduce from the Rougail CLI output that the `manual` family is not taken into account by Rougail.
Let's first examine what this disabled property does.
.. glossary::
@ -111,7 +114,10 @@ It outputs:
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html
:class: output
Let's have a look at come back to our use case, we have a choice between five options
We can see that the Rougail CLI is warning us that the variables we are trying to assign values on are disabled.
That is to say, they are not taken into account at the :term:`configuration` level.
If we have a closer look at our use case, we have a choice between five options
in order to set the proxy mode:
.. image:: images/firefox_01.png
@ -124,31 +130,37 @@ These five choices are:
- Manual proxy configuration
- Automatic proxy configuration URL
If the `Manual proxy configuration` is not selected, we don't need to set
the `address` and `port` variables, there is no point in setting them.
Actually if the `Manual proxy configuration` is not selected, we don't need to set
these `address` and `port` variables, there is no point in setting them in
four out of our five use cases.
We could say that we disable them in order to expose the fact that we don't use them,
but it's not just that: if we fill them in, there might be a problem in the overall integrity of the configuration.
We shall fill and use in these variables in the `Manual proxy configuration` context only.
but it's not just that: if we fill them in, there might be a problem in the overall integrity of the whole :term:`configuration`.
We shall fill and use in these variables in the `Manual proxy configuration` use case context only.
Otherwise, **we need to disable them when they are not necessary**.
If we fill them in, Rougail CLI will output a warning and the :term:`operator` will wonder : "what am I doing?".
I shall fill and use in these variables only in the `Manual proxy configuration` context.
In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it.
He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context.
.. important:: We need to **disable** variables or families that are not used
in a given usage context.
.. type-along:: Disabling a group of variables is disabling a family
.. type-along:: Disabling variables one by one can be replaced by disabling a family
If we don't choose the manual mode, we need to **disable** these variables.
If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable
all the subfamilies and the variables in it.
Note that we've placed theses variables in the `http_proxy`
subfamily. We can then disable the whole `manual` subfamily in order to
disable the `http_proxy` family and all the variables that are placed in it.
subfamily. We can then disable it or even the parent `manual` subfamily in order to
disable the `http_proxy` family and all the variables that are placed in it, because
the `manual` family variables shall be used only in the manual proxy use case context.
Notice the `disabled: true` parameter set in the `manual` family:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml
:linenos:
:language: yaml
:caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file
:caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file is disabled here
..
---
@ -170,9 +182,6 @@ disable the `http_proxy` family and all the variables that are placed in it.
type: port
default: 8080
Notice the `disabled: true` parameter set in the `manual` family.
A conditional disabled family
------------------------------
@ -182,15 +191,16 @@ A conditional disabled family
git switch --detach v1.1_041
What we need is a *dynamic setting* of the disable/enable property of the `manual` family.
The idea in this section is to dynamically set the enable/disable tag according to the chosen context.
What could be usefull here is a *dynamic setting* of the disable/enable property of the `manual` family.
The idea in this section is to dynamically set the enable/disable property according to the chosen use case context.
In rougail, we can set a property's value **depending on** the value of another variable. **It is conditioned by** another variable.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml
:linenos:
:language: yaml
:caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled
..
%YAML 1.2
---
@ -215,12 +225,21 @@ The idea in this section is to dynamically set the enable/disable tag according
type: port
default: 8080
FIXME : trouver une autre formulation et expliquer un peu plus, notamment le "when_not"
.. note:: The `_.` Rougail's notation means the variable in the current workspace.
Now the `disabled` property has some parameter defined. First, let's explaine the `variable` parameter.
This parameter specifies the target variable. The value of this target variable
will be used to dynamically enable or disable our `manual` family.
We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value.
The target variable is `_.proxy_mode`.
The `.` notation means the path of the family or subfamily you're currently in.
The `_.` notation means the parent path of the current family or subfamily path.
Regarding the `when_not` parameter, it means that if the target variable's value
is `Manual proxy configuration` then the `manual` **will not** be disabled (that is, it will be enabled).
Here as the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled.
As the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled.
Let's launch the Rougail CLI on an empty user value file:
@ -234,7 +253,7 @@ Let's launch the Rougail CLI on an empty user value file:
We have this output:
.. raw:: html
:class: output
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html
..
@ -249,12 +268,17 @@ We can see that the `manual` family and all the variables into it are not presen
.. type-along:: Dynamically enabling the `manual` family
Now if we choose **the manual mode**, that is the `Manual proxy configuration` value for the `proxy_mode`, things become slightly different.
If the manual mode for the proxy is not selected, then the `manual` family is disabled.
On the other hand, if the manual proxy's configuration mode is selected,
then the `manual` family is re-activated (enabled).
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yaml
Now we are going to select the ** manual mode**, that is the `Manual proxy configuration`
value for the `proxy_mode` variable, and things will become slightly different.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml
:linenos:
:language: yaml
:caption: The `proxy_mode`'s manual setting in the :file:`config/03/config.yaml` user datas file
:caption: The `proxy_mode`'s manual setting in the :file:`config/02/config.yaml` user datas file
..
---
@ -265,39 +289,85 @@ Now if we choose **the manual mode**, that is the `Manual proxy configuration`
port: 3128
use_for_https: false
If the manual mode for the proxy is not selected, then the `manual` family shall be disabled.
On the other hand, if the manual proxy's configuration mode is selected,
then the `manual` family is activated (enabled).
.. note:: Remember that this activation/deactivation of the `manual` family
depends on the value of the `proxy_mode` variable.
In rougail, we can set a property's value **depending on** the value of another variable. That is, **it is conditioned by** another variable.
FIXME expliquer ici mieux le "when_not"
depends on the value of the `proxy_mode` variable. Here we have
chosen the `Manual proxy configuration` value.
.. rubric:: Explanation
Here we have the `disabled` property like this:
Here the `disabled` property **depends on** the value of the `proxy_mode` variable.
It is the `variable` parameter that allows you to define the name of the target variable on which the `disabled` property depends.
Copy HTTP manual proxy to HTTPS manual proxy
---------------------------------------------
.. type-along:: For those who follow the tutorial with the help of the git repository
Now you need to checkout the `v1.1_042` version::
git switch --detach v1.1_042
We have split the definition of the `manual` familiy into two specific files:
.. raw:: html
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html
Here is the new :file:`20-manual.yml` file:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml
:linenos:
:language: yaml
:caption: The :file:`firefox/20-manual.yml` structure file with the `https_proxy` family.
..
%YAML 1.2
---
version: 1.1
manual:
use_for_https: true # Also use this proxy for HTTPS
https_proxy: # HTTPS Proxy
address:
description: HTTPS address
type: domainname
params:
allow_ip: true
port:
description: HTTPS Port
type: port
default: 8080
This `https_proxy` family is identical to the `http_proxy` family except that it defines variables intended for the HTTPS protocol.
Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, its default value is `True`.
We want to offer the possibility of providing the same proxy configuration for the HTTP and the HTTPS requests.
A conditional hidden family
----------------------------
.. type-along:: For those who follow the tutorial with the help of the git repository
Now you need to checkout the `v1.1_043` version::
git switch --detach v1.1_043
.. code-block:: yaml
disabled:
type: variable
variable: proxy_mode
when_not: 'Manual proxy configuration'
Here the `disabled` property **depends on** the value of another variable.
The `variable` parameter allows you to define the name of the target variable on which the `disabled` property depends.
.. keypoints:: Key points progress
**summary**
We have the ability to build a contextual setting:
We have now the ability to build a contextual setting:
- if `proxy_mode` is not `'Manual proxy configuration'` the `manual` family is disabled
- if `proxy_mode == 'Manual proxy configuration'` the `manual` family is enabled
- if the `proxy_mode` variable's value is not `'Manual proxy configuration'` the `manual` family is disabled
- if the `proxy_mode` variable's value is `'Manual proxy configuration'` then the `manual` family is enabled
**Keywords**

0
docs/tutorial/boolean.rst → docs/tutorial/hidden.rst
View file

2
docs/tutorial/index.rst
View file

@ -52,7 +52,7 @@ Let's dive into this **configuration options validation** use case.
family
domainname
disabled
boolean
hidden
dynfam
calculation

47
docs/tutorial/tutorial.rst
View file

@ -1,52 +1,5 @@
:orphan:
The HTTP proxy configuration
------------------------------
In this family let's add a *subfamily* named `http_proxy`, containing the address and port configuration variables.
Let's create the :file:`dict/03-proxy_manual_http_proxy.yml` dictionary:
.. code-block:: yaml
:caption: the the :file:`dict/02-proxy_manual.yml` file
:linenos:
---
version: '1.1'
proxy:
manual:
http_proxy:
description: HTTP Proxy
address:
description: HTTP address
type: domainname
port:
description: HTTP Port
type: port
default: '8080'
Both variables `address` and `port` have particular types (respectively `domainname` line 9 and `port` line 12) to validate the values configured by the user.
.. note:: No need to specify the type of the `http_proxy` as a family type, because here we have declared variables inside of it.
Duplicating the HTTP configuration to HTTPS
---------------------------------------------
We then want to offer the user the possibility of providing the same proxy for the HTTPS requests. Let's create the :file:`dict/04-proxy_manual_http_use_for_https.yml` file:
.. code-block:: yaml
:caption: the :file:`dict/04-proxy_manual_http_use_for_https.yml` file
version: '1.1'
proxy:
manual:
use_for_https:
description: Also use this proxy for HTTPS
type: boolean
This variable is a `boolean` type, its default value is `True`.
HTTPS proxy configuration detail
-----------------------------------