From 2e99a30e381d7820139ff0d264ed39aab63bfa5f Mon Sep 17 00:00:00 2001 From: gwen Date: Thu, 27 Nov 2025 11:30:38 +0100 Subject: [PATCH] choice --- docs/tutorial/choice.rst | 113 ++++++++++++++++++++++++++---------- docs/tutorial/proxymode.rst | 2 +- 2 files changed, 84 insertions(+), 31 deletions(-) diff --git a/docs/tutorial/choice.rst b/docs/tutorial/choice.rst index 145880a5a..f637371ef 100644 --- a/docs/tutorial/choice.rst +++ b/docs/tutorial/choice.rst @@ -1,34 +1,34 @@ -A variable with predefined values +A variable with possible values ================================== .. objectives:: Objectives - We will learn how to define variables with a list of available values. + We will learn how to define variables with predefined available values. .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` on your computer. - If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`, - this workshop page corresponds to the tags :tutorial:`v1.1_004 ` to :tutorial:`FIXME ` + this workshop page corresponds to the tags :tutorial:`v1.1_010 ` to :tutorial:`FIXME ` in the repository: :: git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git - git checkout v1.1_004 + git checkout v1.1_010 -Limits the possible values for the variable +A variable with a list of possible values --------------------------------------------- -In the firefox browser, the proxy mode can be defined this way: +In the firefox browser, the proxy mode can be set by this way: .. image:: images/firefox_02.png A list of possible values for the `proxy_mode` variable ​​is proposed. With rougail there is the possibility of defining a list of available values -with the `choice` parameter: +with the `choice` variable's parameter: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: :language: yaml :caption: The `proxy_mode` variable with the `choice` parameter @@ -46,7 +46,7 @@ with the `choice` parameter: - Automatic proxy configuration URL default: No proxy -:tutorial:`Download this file from the rougail-tutorials git repository ` +:tutorial:`Download this file from the rougail-tutorials git repository ` Let's run the Rougail CLI with this new structure file: @@ -58,7 +58,7 @@ Let's run the Rougail CLI with this new structure file: We have an output like this one: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_004/config/01/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_010/config/01/output_ro.html :class: output .. @@ -77,33 +77,31 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy` .. note:: As we have set the `proxy_mode`'s value as `No proxy` by default, we have set a value which appears in yellow in the rougail CLI output, which means : "value set by default". -The constraints that come with the `choice` type ----------------------------------------------------- +`No proxy` is an available variable's value. We say that the `proxy_mode` variable is *constrained* +by the possibilities of the `choice` parameter. -We say that the `proxy_mode` variable is *constrained* by the `choice` parameter. +.. type-along:: Let's add some user datas to this structure -FIXME continuer ici - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/config.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/03/config.yml :linenos: :language: yaml :caption: A user data specification -:tutorial:`Download this file from the rougail-tutorials git repository ` +:tutorial:`Download this file from the rougail-tutorials git repository ` -If we run the rougail CLI with this user datas, we have: +If we run the rougail CLI with this user datas: -.. code-block:: text +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/03/cmd_ro.txt :class: terminal - rougail -m firefox -u yaml -ff config/03/config.yml - -FIXME: this output is not the expected output +.. + rougail -m firefox/ -u yaml -yf config/03/config.yml We have this output: .. raw:: html - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/output_ro.html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/03/output_ro.html :class: output .. @@ -116,10 +114,8 @@ We have this output: As we set the `proxy_mode` variable from a user data file, -we now have specified a value which is **not** a default value, -and the value appears in green, which means : "user data value". - -FIXME: verifier que cette sortie est bonne (on a des valeurs différentes) +we now have specified a value which is **not** a default value, and +the output of the rougail CLI explicitly shows that a user data value has been entered. .. type-along:: The constraints that come with the `choice` property @@ -133,11 +129,68 @@ We have the list of the possible (authorized) values: - `Manual proxy configuration` - `Automatic proxy configuration URL` -FIXME : essayer de fixer un value qui n'est pas dans la liste et voir le résultat +.. questions:: Question + + What happens if I set a value that is not available in the `choice` list? + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/config.yml + :linenos: + :language: yaml + :caption: A (false) user data specification + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +If we run the rougail CLI with this user datas: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/cmd_ro.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/03/config.yml + +We have this output: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/output_ro.html + :class: output + +We can see here that Rougail warns us about an invalid value that is not in the available choices, +that's why this value will not be used and it falls back to the original default value. + +But maybe this is not the behavior you need. Maybe you need to stop everything if rougail detects that +something is going wrong, maybe you need some kind of a strict mode. + +Indeed, this warning can be transformed into an error. + +If we run the rougail CLI with this `--cli.invalid_user_datas_error` parameter: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/cmd_invalid.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/03/config.yml --cli.invalid_user_datas_error + +Then we have an `error` output instead of a `warning` output: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/output_invalid.html + :class: output + +.. + 
🛑 ERRORS
+    ┗━━ the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy Access to the Internet), only "Auto-detect proxy settings for this network", "Automatic proxy configuration URL", "Manual proxy 
+        configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yml"
+
+ + .. keypoints:: Key points progress - Indeed, in the Firefox configuration, it is possible to define several configuration modes, from no proxy at all (`no proxy`) to a kind of automatic configuration mode from a file (`set up proxy configuration from a file`). + Indeed, in the Firefox configuration, it is possible to define several configuration modes, + from no proxy at all to different kind of automatic or manual configuration modes. + The `choice` parameter, that is the list of available values for a variable, can help us to handle this situation. **Progress** @@ -145,7 +198,7 @@ FIXME : essayer de fixer un value qui n'est pas dans la liste et voir le résult **Structure description file** - .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: :language: yaml :caption: A Rougail structure file with a variable named `proxy_mode`, with a default value. diff --git a/docs/tutorial/proxymode.rst b/docs/tutorial/proxymode.rst index b4451330b..186cb09d6 100644 --- a/docs/tutorial/proxymode.rst +++ b/docs/tutorial/proxymode.rst @@ -18,7 +18,7 @@ Group variables inside families In the structure description file, we have: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: :language: yaml :caption: The `proxy_mode` choice type variable in the :file:`firefox/00-proxy.yml` structure file