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

309
docs/tutorial/disabled.rst
View file

@ -1,45 +1,122 @@
The `disabled` property
Disabling things
========================
.. objectives:: Objectives
In this section we will learn:
- 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
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.
We will see what is a disabled variable or family is, and why it is interesting to do that.
We will disable a whole family here (yes, a family can disapear in the outerspace).
.. prerequisites:: Reminder
.. prerequisites:: Prerequisites
- We have three variables: :confval:`proxy_mode`, :confval:`address` and :confval:`port` placed in the `http_proxy` subfamily.
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
A disabled property assigned to a family
- 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.
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.
Let's come back to our use case, we have a choice between five options
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.
.. 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::
git switch --detach v1.1_041
We are going to
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.
- select **the manual mode** value for the `proxy_mode`
- assing the `example.net` value to the `address` validate in the user data file.
.. 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 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
- 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).