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
|
||||
|
||||
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 <installation>` 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 <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:
|
||||
|
||||
::
|
||||
|
||||
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 <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:
|
||||
|
||||
|
|
@ -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 <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
|
||||
|
||||
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:
|
|||
</pre>
|
||||
|
||||
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 <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
|
||||
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
Loading…
Reference in a new issue