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

disabled ok

Browse source
This commit is contained in:
gwen 2026-01-06 11:48:15 +01:00
parent 9f2299ee3e
commit eeba802047
1 changed files with 113 additions and 64 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

177
docs/tutorial/disabled.rst
View file

@ -75,7 +75,8 @@ 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.
Notice that we have this `disabled: true` property assigned to the `manual` family.
Let's launch the Rougail CLI on this structure file (whith an empty user data file):
.. raw:: html
:class: terminal
@ -91,7 +92,7 @@ The Rougail CLI outputs this:
:class: output
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.
So what does this disabled property exactly?
.. glossary::
@ -99,16 +100,15 @@ Let's first examine what this disabled property does.
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.
It simply doesn't exist (it is deactivated) for the whole configuration.
.. note:: Note that, as with any property, if a family has been disabled, all variables and sub-families that it contains are disabled.
.. 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:
And if we try to assign values to variables that have been disabled, here is what happens:
.. 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
:caption: In this :file:`config/02/config.yml` user data file, we assign values to variables that have been disabled
If we launch the Rougail CLI:
@ -123,9 +123,9 @@ It outputs:
:class: output
We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which are disabled.
That is to say, they are not taken into account at the :term:`configuration` level.
Because it is not logical. We are trying to assign values to variables that 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
Let's look again at our use case. We have a choice between five options
in order to set the proxy mode:
.. image:: images/firefox_01.png
@ -142,10 +142,10 @@ Actually if the `Manual proxy configuration` is not selected, we don't need to s
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,
The first point is 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 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**.
Otherwise, **we need to disable them when they are not used**.
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.
@ -153,8 +153,9 @@ He will wonder : "oh, what am I doing?", I shall fill and use in these variables
.. important:: We need to **disable** variables or families that are not used
in a given usage context.
.. type-along:: Disabling variables one by one can be replaced by disabling a family
.. type-along:: Disabling a family
Disabling variables one by one can be replaced by disabling a whole family.
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.
@ -199,10 +200,11 @@ A conditional disabled family
git switch --detach v1.1_041
What could be usefull here is a *dynamic setting* of the disable/enable property of the `manual` family.
What could be usefull here is a *dynamically* disable or enable 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.
In rougail, we can set a property's value **depending on** the value of another variable.
**The property's value is conditioned by** another variable.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml
:linenos:
@ -243,11 +245,12 @@ 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.
Now regarding the `when_not` parameter, this means that if the target variable's value
is `Manual proxy configuration` then the `manual` familiy **will not** be disabled
(that is, it will be **enabled**).
Regarding as the default value use case, the `proxy_mode`'s variable is `No proxy` by default.
The `manual` familiy is then **disabled by default**.
Let's launch the Rougail CLI on an empty user value file:
@ -276,12 +279,12 @@ We can see that the `manual` family and all the variables into it are not presen
.. type-along:: Dynamically enabling the `manual` family
Now we are going to choose the **manual mode**, that is the `Manual proxy configuration`
value for the `proxy_mode` variable, and things will 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).
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.
then the `manual` family **is enabled**:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml
:linenos:
@ -297,15 +300,49 @@ value for the `proxy_mode` variable, and things will become slightly different.
port: 3128
use_for_https: false
.. note:: Remember that this activation/deactivation of the `manual` family
depends on the value of the `proxy_mode` variable. Here we have
chosen the `Manual proxy configuration` value.
Let's launch the Rougail CLI to verify this:
.. raw:: html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/cmd_ro.txt
:class: terminal
..
rougail -m firefox/ -u yaml -yf config/02/config.yml
It outputs:
.. raw:: html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/output_ro.html
:class: output
..
<pre>╭────────────── Caption ───────────────╮
│ Variable <span style="color: #00aa00">Modified value</span> │
│ (⏳ Original default value) │
╰──────────────────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
<span style="color: #5c5cff">┃ </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/02/config.yml" (⏳ No
<span style="color: #5c5cff">┃ </span>proxy)
<span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┃ </span>file "config/02/config.yml"
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span><span style="color: #5c5cff"> </span>"config/02/config.yml" (⏳ 8080)
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span>the YAML file "config/02/config.yml" (⏳ true)
</pre>
.. rubric:: Explanation
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.
Please remember that this activation/deactivation of the `manual` family
depends on the value of the `proxy_mode` variable. Here we have
chosen the `Manual proxy configuration` value, so the `address` and `port` variables appear.
Copy HTTP manual proxy to HTTPS manual proxy
---------------------------------------------
@ -322,7 +359,8 @@ We have split the definition of the `manual` familiy into two specific files:
: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:
Here is the new :file:`20-manual.yml` file, which looks like the :file:`10-manual.yml` file
except that it is dedicated to the HTTPS protocol:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml
:linenos:
@ -450,22 +488,22 @@ We have this output:
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html
FIXME: il y a un <span> dans le <pre>
..
<pre>&gt; [!CAUTION]
&gt;
&gt; - manual (Manual proxy configuration)
&gt; - https_proxy (HTTPS Proxy)
&gt; - address (HTTPS address): :stop_sign: &lt;span style="color: #C23636"&gt;mandatory variable but is inaccessible and has no value&lt;/span&gt;
<pre><span style="font-weight: bold; color: #ff0000">🛑 Caution</span>
<span style="color: #ff0000">┗━━ </span>manual (Manual proxy configuration)
<span style="color: #ff0000"> </span><span style="color: #ff0000">┗━━ </span>https_proxy (HTTPS Proxy)
<span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000">┗━━ </span>address (HTTPS address): <span style="color: #ff0000">🛑 mandatory variable but is inaccessible </span>
<span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000"> </span><span style="color: #ff0000">and has no value</span>
</pre>
We are going to see how to point HTTPS variables to HTTPS variables
Which is logical, HTTPS proxy variables have no values set yet.
We are going to see how to point HTTPS variables to HTTP variables.
A conditional hidden family
----------------------------
Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.
Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen,
let's have a look at our use case again:
.. image:: images/firefox_manual_https.png
@ -494,7 +532,9 @@ Let's introduce a new Rougail concept here:
Sometimes somes minor changes in the :term:`user datas <user data>` may involve chain reactions
in the whole :term:`configuration`.
The **context** is the state of the user datas at one moment, the set of the values of the variables
at a given moment. This term also refers to the ability of a system to handle
at a given moment.
This term refers in Rougail to the ability of a system to handle
the *statefull* state of a configuration.
It expresses the transition between one situation to another situation,
that is, the deeply **statefull** aspects of a data set.
@ -503,7 +543,7 @@ Let's introduce a new Rougail concept here:
.. type-along:: A new variable which has the `boolean` type
The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.
is to add this `use_for_https` variable in our structure file. This boolean variable can reproduce this binary choice option.
Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
Well, it depends on the :term:`context`.
@ -531,8 +571,8 @@ With this :confval:`use_for_https` boolean variable, there are two possibilities
**answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case,
we simply have to point their values ​​in one direction or another depending on this or that context,
that's why it is absolutely not a question of deactivating them. The `manual.https_proxy.address`
and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode.
that's why it is absolutely not a question of disabling them. The `manual.https_proxy.address`
and the `manual.http_proxy.port` variables shall not be disabled in the manual mode.
Let's introduce a new concept here:
@ -541,8 +581,10 @@ Let's introduce a new concept here:
hidden
A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`.
Anyway, these variables can be used if the context evolves. This is the main difference
between the `hidden` and the `disabled` properties (with the `disabled` property, the variables are *deactivated*.
Anyway, these variables can be used if the context evolves.
This is the main difference between the `hidden` and the `disabled` properties
(with the `disabled` property, the variables are *deactivated*.
Now we can set a `hidden` property to the `https_proxy` family:
@ -555,7 +597,7 @@ Here is our new :file:`20-manual.yml` structure file:
We have now a `hidden` property assigned to the `https_proxy` family.
The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has
a `variable` target parameter: `variable: _.use_for_https`
a `variable` target parameter that points to it: `variable: _.use_for_https`.
.. prerequisites:: Reminder
@ -589,16 +631,6 @@ Here, the defaut value of `manual.https_proxy.address` points to `manual.http_pr
This is the same thing for the default value of the `manual.https_proxy.port` variable,
which points to the `manual.http_proxy.port` value.
We also say that the default value is *calculated*.
.. glossary::
calculated
We say that a variable's value or a default variable's value is calculated
when there is a pointer which refers to another variable's value
or if there is some :term:`jinja` code or a python function that calculates it.
To summarize the HTTP and HTTPS configuration in the manual use case context,
here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml` structure files:
@ -663,27 +695,44 @@ here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml`
variable: __.http_proxy.port
...
We can see here that the `address` variable's default value is contitionned by the `__.http_proxy.address` variable's value.
The target variable is `http_proxy.address`.
The `.` notation means the path of the family or subfamily you're currently in.
The `__.` notation means the parent path of the parent path of the current subfamily path.
.. note:: We also say that the `manual.https_proxy.address` and the the `manual.https_proxy.port` default values are *calculated*.
.. glossary::
calculated
We say that a variable's value or a default variable's value is calculated
when there is a pointer which refers to another variable's value
or if there is some :term:`jinja` code or a python function that calculates it.
.. keypoints:: Key points progress
**summary**
We have now the ability to build a contextual setting:
We have now the ability to build *contextual settings*:
- 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
- FIXME add the hidden steps
We have arrived at the end of the proxy's manual configuration's section.
- if the `use_for_https` variable's value is `true`, the HTTP configuration will be reused in the HTTPS situation
and the `https_proxy` familiy will be hidden
- if the `manual.https_proxy.address` has no value set, the defaut value is the same as the `manual.http_proxy.address`'s value
(same behavior with the HTTP port and the HTTPS port variable)
And yes, we did it. We have arrived at the end of the proxy's manual configuration's section.
**Keywords**
- We now know what a *property* is, we have seen in details the :term:`disabled` property
- 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
- The :term:`hidden` property set to a family
- The fact that a property can be set dynamically
- The conditional dependency of a `hidden` property that depends on a `boolean` variable.
- A calculated default value
we call it a variable based contextual disabled family,
- The :term:`hidden` property set to a family,
- The fact that a property can be set dynamically,
- The conditional dependency of a `hidden` property can depends on a `boolean` variable,
- We know whant a calculated default value is.