choice
This commit is contained in:
gwen
parent
1cd89747de
commit
2e99a30e38
2 changed files with 84 additions and 31 deletions
|
|
@ -1,34 +1,34 @@
|
||||||
A variable with predefined values
|
A variable with possible values
|
||||||
==================================
|
==================================
|
||||||
|
|
||||||
.. objectives:: Objectives
|
.. 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
|
.. prerequisites:: Prerequisites
|
||||||
|
|
||||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||||
- If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`,
|
- 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 <src/tag/v1.1_004>` to :tutorial:`FIXME <src/tag/FIXME>`
|
this workshop page corresponds to the tags :tutorial:`v1.1_010 <src/tag/v1.1_010>` to :tutorial:`FIXME <src/tag/FIXME>`
|
||||||
in the repository:
|
in the repository:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
||||||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
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
|
.. image:: images/firefox_02.png
|
||||||
|
|
||||||
A list of possible values for the `proxy_mode` variable is proposed.
|
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 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:
|
:linenos:
|
||||||
:language: yaml
|
:language: yaml
|
||||||
:caption: The `proxy_mode` variable with the `choice` parameter
|
:caption: The `proxy_mode` variable with the `choice` parameter
|
||||||
|
|
@ -46,7 +46,7 @@ with the `choice` parameter:
|
||||||
- Automatic proxy configuration URL
|
- Automatic proxy configuration URL
|
||||||
default: No proxy
|
default: No proxy
|
||||||
|
|
||||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_004/firefox/00-proxy.yml>`
|
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_010/firefox/00-proxy.yml>`
|
||||||
|
|
||||||
Let's run the Rougail CLI with this new structure file:
|
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:
|
We have an output like this one:
|
||||||
|
|
||||||
.. raw:: html
|
.. 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
|
: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
|
.. 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".
|
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_010/config/03/config.yml
|
||||||
|
|
||||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/config.yml
|
|
||||||
:linenos:
|
:linenos:
|
||||||
:language: yaml
|
:language: yaml
|
||||||
:caption: A user data specification
|
:caption: A user data specification
|
||||||
|
|
||||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_004/config/03/config.yml>`
|
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_010/config/03/config.yml>`
|
||||||
|
|
||||||
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
|
:class: terminal
|
||||||
|
|
||||||
rougail -m firefox -u yaml -ff config/03/config.yml
|
..
|
||||||
|
rougail -m firefox/ -u yaml -yf config/03/config.yml
|
||||||
FIXME: this output is not the expected output
|
|
||||||
|
|
||||||
We have this output:
|
We have this output:
|
||||||
|
|
||||||
.. raw:: html
|
.. 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
|
:class: output
|
||||||
|
|
||||||
..
|
..
|
||||||
|
|
@ -116,10 +114,8 @@ We have this output:
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
As we set the `proxy_mode` variable from a user data file,
|
As we set the `proxy_mode` variable from a user data file,
|
||||||
we now have specified a value which is **not** a default value,
|
we now have specified a value which is **not** a default value, and
|
||||||
and the value appears in green, which means : "user data value".
|
the output of the rougail CLI explicitly shows that a user data value has been entered.
|
||||||
|
|
||||||
FIXME: verifier que cette sortie est bonne (on a des valeurs différentes)
|
|
||||||
|
|
||||||
.. type-along:: The constraints that come with the `choice` property
|
.. 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`
|
- `Manual proxy configuration`
|
||||||
- `Automatic proxy configuration URL`
|
- `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 <src/tag/v1.1_010/config/04/config.yml>`
|
||||||
|
|
||||||
|
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
|
||||||
|
|
||||||
|
..
|
||||||
|
<pre><span style="font-weight: bold; color: #ff0000">🛑 ERRORS</span>
|
||||||
|
<span style="color: #ff0000">┗━━ </span>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
|
||||||
|
<span style="color: #ff0000"> </span>configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yml"
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
.. keypoints:: Key points progress
|
.. 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**
|
**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**
|
**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:
|
:linenos:
|
||||||
:language: yaml
|
:language: yaml
|
||||||
:caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
|
:caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
|
||||||
|
|
|
||||||
|
|
@ -18,7 +18,7 @@ Group variables inside families
|
||||||
|
|
||||||
In the structure description file, we have:
|
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:
|
:linenos:
|
||||||
:language: yaml
|
:language: yaml
|
||||||
:caption: The `proxy_mode` choice type variable in the :file:`firefox/00-proxy.yml` structure file
|
:caption: The `proxy_mode` choice type variable in the :file:`firefox/00-proxy.yml` structure file
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue