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

hidden

Browse source
This commit is contained in:
gwen 2026-01-08 15:47:23 +01:00
parent c0a6ef2223
commit b1f0e7e3de
1 changed files with 171 additions and 134 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

305
docs/tutorial/disabled.rst
View file

@ -12,7 +12,6 @@ Define access to variable or family
- create a `disabled` family
- use a new family or variable's property: the `hidden` property
.. prerequisites:: Prerequisites
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
@ -23,16 +22,16 @@ Define access to variable or family
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>`
this workshop page corresponds to the tags :tutorial:`v1.1_050 <src/tag/v1.1_050>` to :tutorial:`v1.1_053 <src/tag/v1.1_053>`
in the repository.
::
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
git switch --detach v1.1_040
git switch --detach v1.1_050
A disabled family
---------------------------------------------
------------------
Disabling and hiding are two families or variables properties. Let's begin with
defining what a property is:
@ -47,7 +46,7 @@ defining what a property is:
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
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/firefox/10-manual.yml
:language: yaml
:caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file
@ -78,7 +77,7 @@ Let's launch the Rougail CLI on this structure file (whith an empty user data fi
.. raw:: html
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/01/cmd_ro.txt
..
rougail -m firefox/ -u yaml -yf config/02/config.yml
@ -86,7 +85,7 @@ Let's launch the Rougail CLI on this structure file (whith an empty user data fi
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
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/01/output_ro.html
:class: output
We can deduce from the Rougail CLI output that the `manual` family is not taken into account by Rougail.
@ -104,20 +103,20 @@ So what does this disabled property exactly?
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
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/02/config.yml
:language: yaml
: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:
.. raw:: html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/cmd_ro.txt
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/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
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/config/02/output_ro.html
: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.
@ -164,7 +163,7 @@ the `manual` family variables shall be used only in the manual proxy use case co
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
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_050/firefox/10-manual.yml
:linenos:
:language: yaml
:caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file is disabled here
@ -194,9 +193,9 @@ A conditional disabled family
.. 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::
Now you need to checkout the `v1.1_051` version::
git switch --detach v1.1_041
git switch --detach v1.1_051
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.
@ -204,7 +203,7 @@ The idea in this section is to dynamically set the enable/disable property accor
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
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/firefox/10-manual.yml
:linenos:
:language: yaml
:caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled
@ -253,7 +252,7 @@ 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
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/01/cmd_ro.txt
..
rougail -m firefox/ -u yaml -yf config/01/config.ym
@ -262,7 +261,7 @@ 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
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/01/output_ro.html
..
<pre>╭──────────────────── Caption ─────────────────────╮
@ -283,7 +282,7 @@ If the manual mode for the proxy is not selected, then the `manual` family is di
On the other hand, if the manual proxy's configuration mode is selected,
then the `manual` family **is enabled**:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/config.yml
:linenos:
:language: yaml
:caption: The `proxy_mode`'s manual setting in the :file:`config/02/config.yaml` user datas file
@ -300,7 +299,7 @@ then the `manual` family **is enabled**:
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
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/cmd_ro.txt
:class: terminal
..
@ -309,7 +308,7 @@ Let's launch the Rougail CLI to verify this:
It outputs:
.. raw:: html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/output_ro.html
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_051/config/02/output_ro.html
:class: output
..
@ -340,119 +339,81 @@ 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.
A 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_052` version::
FIXME
git switch --detach v1.1_052
Let's introduce a new property here:
.. glossary::
hidden
Here is an example with different user values for handling HTTP and HTTPS:
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.
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/config.yml
This is the main difference between the `hidden` and the `disabled` properties:
- with the `disabled` property, the variables are *deactivated*
- with the `hidden` property, the variables are just not seen.
Now we can set a `hidden` property to the `https_proxy` family:
Here is our new :file:`20-manual.yml` structure file:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_052/firefox/20-manual.yml
:linenos:
:language: yaml
:caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false
:caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
..
%YAML 1.2
---
proxy_mode: Manual proxy configuration
version: 1.1
manual:
http_proxy:
address: http.proxy.net
port: 3128
use_for_https: false
use_for_https: true # Also use this proxy for HTTPS
https_proxy:
address: https.proxy.net
description: HTTPS Proxy
hidden: true
If we launch the Rougail CLI:
address:
description: HTTPS address
default:
variable: __.http_proxy.address
.. raw:: html
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/cmd_ro.txt
port:
description: HTTPS Port
default:
variable: __.http_proxy.port
...
..
rougail -m firefox/ -u yaml -yf config/01/config.yml
We have this output:
.. raw:: html
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/output_ro.html
..
<pre>╭────────────── Caption ───────────────╮
│ Variable <span style="color: #ffd700">Default value</span> │
│ <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/01/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/01/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/01/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/01/config.yml" (⏳ true)
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📂 https_proxy (HTTPS Proxy)
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTPS address): <span style="color: #00aa00">https.proxy.net</span> ◀ loaded from the YAML
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span>file "config/01/config.yml"
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTPS Port): <span style="color: #ffd700">8080</span>
</pre>
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 an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols.
Here is an example with identical HTTP and HTTPS proxy configuration:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/config.yml
:linenos:
:language: yaml
:caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true
..
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: http.proxy.net
port: 3128
use_for_https: true
Let's launch the Rougail CLI:
.. raw:: html
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/cmd_ro.txt
..
rougail -m firefox/ -u yaml -yf config/02/config.yml
We have this output:
.. raw:: html
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html
..
<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>
Which is logical, HTTPS proxy variables have no values set yet.
We are going to see how to point HTTPS variables to HTTP variables.
We have now a `hidden` property assigned to the `https_proxy` family.
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_053` version::
git switch --detach v1.1_053
The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has
a `variable` target parameter that points to it: `variable: _.use_for_https`.
.. prerequisites:: Reminder
The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the parent
family.
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:
@ -490,12 +451,16 @@ Let's introduce a new Rougail concept here:
It expresses the transition between one situation to another situation,
that is, the deeply **statefull** aspects of a data set.
.. 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 this `use_for_https` variable in our structure file. This boolean variable can reproduce this binary choice option.
- if the use of the proxy variables for https are the same of the proxy variables for http,
that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK.
- if the use of the proxy variables for https **are not** the same of the proxy variables for http,
we would like to set their default values to the http proxy variables values.
Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
Well, it depends on the :term:`context`.
@ -525,35 +490,107 @@ With this :confval:`use_for_https` boolean variable, there are two possibilities
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:
Here is an example with different user values for handling HTTP and HTTPS:
.. glossary::
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*.
Now we can set a `hidden` property to the `https_proxy` family:
Here is our new :file:`20-manual.yml` structure file:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_043/firefox/20-manual.yml
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/config.yml
:linenos:
:language: yaml
:caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family.
:caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false
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 that points to it: `variable: _.use_for_https`.
..
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: http.proxy.net
port: 3128
use_for_https: false
https_proxy:
address: https.proxy.net
.. prerequisites:: Reminder
If we launch the Rougail CLI:
The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the parent
family.
.. raw:: html
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/cmd_ro.txt
..
rougail -m firefox/ -u yaml -yf config/01/config.yml
We have this output:
.. raw:: html
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/01/output_ro.html
..
<pre>╭────────────── Caption ───────────────╮
│ Variable <span style="color: #ffd700">Default value</span> │
│ <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/01/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/01/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/01/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/01/config.yml" (⏳ true)
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📂 https_proxy (HTTPS Proxy)
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTPS address): <span style="color: #00aa00">https.proxy.net</span> ◀ loaded from the YAML
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┃ </span>file "config/01/config.yml"
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTPS Port): <span style="color: #ffd700">8080</span>
</pre>
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 an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols.
Here is an example with identical HTTP and HTTPS proxy configuration:
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/config.yml
:linenos:
:language: yaml
:caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true
..
---
proxy_mode: Manual proxy configuration
manual:
http_proxy:
address: http.proxy.net
port: 3128
use_for_https: true
Let's launch the Rougail CLI:
.. raw:: html
:class: terminal
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/cmd_ro.txt
..
rougail -m firefox/ -u yaml -yf config/02/config.yml
We have this output:
.. raw:: html
:class: output
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_053/config/02/output_ro.html
..
<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>
Which is logical, HTTPS proxy variables have no values set yet.
We are going to see how to point HTTPS variables to HTTP variables.
.. keypoints:: Key points progress