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

disabled family

Browse source
This commit is contained in:
gwen 2025-12-15 08:42:43 +01:00
parent 8b02c79dcc
commit d47405c61d
1 changed files with 190 additions and 119 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

303
docs/tutorial/disabled.rst
View file

@ -1,45 +1,122 @@
The `disabled` property
Disabling things
========================
.. objectives:: Objectives
In this section we will learn:
In this section we will see what a disabled variable or family is, and why it can be interesting
to assign the `disabled` property to a variable or a family.
- what a *property* is (actually we already used one: the :term:`mandatory` property
- how to disable a family (yes, a family can disapear in the outerspace)
- explain the `disabled` property
We will disable a whole family here (yes, a family can disapear in the outerspace).
We will see what is a disabled variable or family is, and why it is interesting to do that.
.. prerequisites:: Prerequisites
.. prerequisites:: Reminder
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
- We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port` placed in the `http_proxy` subfamily.
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
by checking out the corresponding tag of the `rougail-tutorials` git repository.
Each tag corresponds to a stage of progress in the tutorial.
Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
A disabled property assigned to a family
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
this workshop page corresponds to the tags :tutorial:`v1.1_040 <src/tag/v1.1_040>` to :tutorial:`v1.1_044 <src/tag/v1.1_044>`
in the repository.
::
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
git switch --detach v1.1_040
A disabled family
---------------------------------------------
First, a definition:
.. glossary::
property
A property is a state (disabled, frozen, read_write, read_only, hidden ...)
of a family, a subfamily or a variable. These properties may vary
depending on the context.
A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...)
of a family, a subfamily or a variable.
These properties change the usual behavior of a variable or family.
Here we are going to assign the `disabled` property to the `manual` family:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml
:language: yaml
:caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file
..
%YAML 1.2
---
version: 1.1
manual:
description: Manual proxy configuration
disabled: true
http_proxy: # HTTP Proxy
address:
description: HTTP address
type: domainname
params:
allow_ip: true
port:
description: HTTP Port
type: port
default: 8080
.. raw:: html
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt
..
rougail -m firefox/ -u yaml -yf config/02/config.yml
The Rougail CLI outputs this:
.. raw:: html
: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.
.. glossary::
disabled
The disabled property is a property of a variable or a family that is kind of deactivated
for the whole configuration.
The disabled property is a property that can be assigned to a variable or a family.
It makes the :term:`configuration` act as if the variable or family that has this property has not even been defined.
It simply doesn't exist. It is deactivated for the whole configuration.
Let's come back to our use case, we have a choice between five options
.. note:: Note that if a family has been disabled, all variables and sub-families that it contains are disabled.
If we still wanna try to assign values to variables that have been disabled:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/config.yml
:language: yaml
:caption: Here in the :file:`config/02/config.yml` user data file, we assign values to disabled variables
If we launch the Rougail CLI:
.. raw:: html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/cmd_ro.txt
:class: terminal
It outputs:
.. raw:: html
: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
in order to set the proxy mode:
.. image:: images/firefox_01.png
The five choices are:
These five choices are:
- No proxy
- Auto-detect proxy settings for this network
@ -48,23 +125,27 @@ The five choices are:
- Automatic proxy configuration URL
If the `Manual proxy configuration` is not selected, we don't need to set
the :confval:`address` and :confval:`port` variables, there is no point
in setting them. 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
only in the `Manual proxy configuration` context. Otherwise, **we need to disable them when they are not necessary**.
the `address` and `port` variables, there is no point in setting them.
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.
Otherwise, **we need to disable them when they are not necessary**.
.. important:: We need to have the ability to **disable** variables that are not used
in a given context.
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.
.. type-along:: disabling the :confval:`address` and :confval:`port` variables
.. 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
If we don't choose the manual mode, we need to **disable** these variables.
They are not used anymore.
Note that we've placed theses variables in the `http_proxy`
subfamily. We can then disable the whole `http_proxy` subfamily in order to
disable the variables that are placed in it.
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.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/firefox/10-manual.yml
.. 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
@ -89,100 +170,39 @@ disable the variables that are placed in it.
type: port
default: 8080
Notice the `disabled: true` parameter set in the `manual` family.
We can see here the `disabled: true` parameter set in the `manual` family.
A conditional disabled family
------------------------------
.. warning:: In this section, we will **intentionally** create an inconsistency in the configuration
in order to explore the `disabled` property's behavior.
.. type-along:: For those who follow the tutorial with the help of the git repository
Now you need to checkout the `v1.1_041` version::
We are going to
git switch --detach v1.1_041
- select **the manual mode** value for the `proxy_mode`
- assing the `example.net` value to the `address` validate in the user data file.
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.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/config.yaml
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml
:linenos:
:language: yaml
:caption: The manual setting in the :file:`config/03/config.yaml` user datas file
:caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled
..
%YAML 1.2
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: example.net
version: 1.1
.. warning:: Remember that the `manual` family is disabled, so are the variables it contains.
Now let's validate the consitency of the configuration:
.. code-block:: text
:class: terminal
rougail -v 1.1 -m firefox/ -u file -ff config/03/config.yaml
As expected, we encounter an error:
.. raw:: html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_027/config/03/output_ro.html
:class: error-box
..
<pre>🛑 ERRORS
<span style="color: #ff0000">┗━━ </span>cannot access to optiondescription "manual" (Manual proxy configuration) because has property
<span style="color: #ff0000"> </span>"disabled"
╭────────────────────────── Caption ──────────────────────────╮
│ Variable <span style="color: #ffd700">Default value</span> │
│ <span style="color: #5c5cff">Undocumented variable</span> Modified value │
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
╰─────────────────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
</pre>
.. questions:: Question
How to avoid these error messages?
Contextual setting of a property
------------------------------------
To avoid this type of error, what we need is a *dynamic setting* of the disable/enable property of the `manual` family.
.. type-along:: The conditional disabled property
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 we need to activate (enable) the `manual` family.
And we understand 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.
Here is how we can achieve this:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_028/firefox/10-manual.yml
:linenos:
:language: yaml
:caption: The `manual` family in the :file:`firefox/10-manual.yml` structure file with a conditional disabled property
..
---
manual:
description: Manual proxy configuration
disabled:
type: variable
variable: proxy_mode
when_not: 'Manual proxy configuration'
variable: _.proxy_mode
when_not: Manual proxy configuration
http_proxy:
description: HTTP Proxy
http_proxy: # HTTP Proxy
address:
description: HTTP address
@ -195,6 +215,67 @@ Here is how we can achieve this:
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.
We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value.
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:
.. raw:: html
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/cmd_ro.txt
..
rougail -m firefox/ -u yaml -yf config/01/config.ym
We have this output:
.. raw:: html
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html
..
<pre>╭──────────────────── Caption ─────────────────────╮
│ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #ffd700">Default value</span> │
╰──────────────────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">No proxy</span>
</pre>
We can see that the `manual` family and all the variables into it are not present.
.. 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.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yaml
:linenos:
:language: yaml
:caption: The `proxy_mode`'s manual setting in the :file:`config/03/config.yaml` user datas file
..
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: http.proxy.net
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"
.. rubric:: Explanation
Here we have the `disabled` property like this:
@ -209,28 +290,18 @@ Here we have the `disabled` property like this:
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:
- if `proxy_mode` is not `'Manual proxy configuration'` it disables the `manual` family
- if `proxy_mode == 'Manual proxy configuration'` it enables the `manual` family
- if `proxy_mode` is not `'Manual proxy configuration'` the `manual` family is disabled
- if `proxy_mode == 'Manual proxy configuration'` the `manual` family is enabled
**Keywords**
- the :term:`property` concept
- the `disabled` property
- the `variable` target property
- a disabled variable or family
- raising a configuration's consistency error
- a variable based contextual disabled family
**Progress**
- we have a :term:`family` named `manual` and a sub family named `http_proxy`
- And we have now two variables: :confval:`proxy_mode` and :confval:`address`.
- We have dynamically disabled the `manual` family (and the `http_proxy` sub family).
- We now know what a *property* is, we have seen in details the :term:`disabled` property
- We can target a variable's value in the `disabled` property's value,
we call it a variable based contextual disabled family