224 lines
8.8 KiB
ReStructuredText
224 lines
8.8 KiB
ReStructuredText
.. _tutorial_choice:
|
|
|
|
A variable with possible values
|
|
==================================
|
|
|
|
.. objectives:: Objectives
|
|
|
|
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.
|
|
|
|
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
|
|
by checking out the corresponding tag of the `rougail-tutorials` git repository.
|
|
Each tag corresponds to a stage of progress in the tutorial.
|
|
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 tag :tutorial:`v1.1_010 <src/tag/v1.1_010/README.md>` in the repository:
|
|
|
|
::
|
|
|
|
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
|
git switch --detach v1.1_010
|
|
|
|
A variable with a list of possible values
|
|
---------------------------------------------
|
|
|
|
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 `choices` variable's parameter:
|
|
|
|
.. 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
|
|
:name: RougailDictionaryChoiceType
|
|
|
|
..
|
|
---
|
|
proxy_mode:
|
|
description: Configure Proxy Access to the Internet
|
|
choices:
|
|
- No proxy
|
|
- Auto-detect proxy settings for this network
|
|
- Use system proxy settings
|
|
- Manual proxy configuration
|
|
- Automatic proxy configuration URL
|
|
default: No proxy
|
|
|
|
: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 these available values:
|
|
|
|
.. code-block:: text
|
|
:class: terminal
|
|
|
|
rougail -m firefox/
|
|
|
|
We have an output like this one:
|
|
|
|
.. raw:: html
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_010/config/01/output_ro.html
|
|
:class: output
|
|
|
|
..
|
|
<pre>╭────────────────────────── Caption ──────────────────────────╮
|
|
│ Variable <span style="color: #ffd700">Default value</span> │
|
|
│ <span style="color: #5c5cff">Undocumented variable</span> Modified value │
|
|
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
|
|
│ <span style="color: #ffaf00">Unmodifiable variable</span> │
|
|
╰─────────────────────────────────────────────────────────────╯
|
|
Variables:
|
|
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
|
|
</pre>
|
|
|
|
`No proxy` is an available variable's value. We say that the `proxy_mode` variable is *constrained*
|
|
by the possibilities of the `choice` parameter.
|
|
|
|
.. type-along:: Let's add some user data to this structure
|
|
|
|
.. 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_010/config/03/config.yml>`
|
|
|
|
If we run the Rougail CLI with this user data:
|
|
|
|
.. 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 -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/03/output_ro.html
|
|
:class: output
|
|
|
|
..
|
|
<pre>╭────────────── Caption ───────────────╮
|
|
│ Variable Modified value │
|
|
│ (<span style="color: #00aa00">⏳ Original default value</span>) │
|
|
╰──────────────────────────────────────╯
|
|
Variables:
|
|
<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ <span style="color: #00aa00">No proxy</span>)
|
|
</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 output of the Rougail CLI explicitly shows that a user data value has been entered,
|
|
it shows which user data file this value comes from, and it also indicates
|
|
what the default value is for information purposes.
|
|
|
|
.. type-along:: The constraints that come with the choices
|
|
|
|
The `proxy_mode` variable's possible values is *constrained*.
|
|
|
|
We have the list of the possible (authorized) values:
|
|
|
|
- `No proxy`
|
|
- `Auto-detect proxy settings for this network`
|
|
- `Use system proxy settings`
|
|
- `Manual proxy configuration`
|
|
- `Automatic proxy configuration URL`
|
|
|
|
.. questions:: Question
|
|
|
|
What happens if I set a value that is not available in the choices?
|
|
|
|
.. 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 data:
|
|
|
|
.. 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_data_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_data_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 to different kind of automatic or manual configuration modes.
|
|
The choices, the list of available values for a variable, can help us to handle this situation.
|
|
|
|
**Progress**
|
|
|
|
To sum up, we have arrived at this point in writing a structure file like this:
|
|
|
|
**Structure description file**
|
|
|
|
.. 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.
|
|
|
|
..
|
|
|
|
.. raw:: text
|
|
|
|
---
|
|
proxy_mode:
|
|
description: Configure Proxy Access to the Internet
|
|
choices:
|
|
- No proxy
|
|
- Auto-detect proxy settings for this network
|
|
- Use system proxy settings
|
|
- Manual proxy configuration
|
|
- Automatic proxy configuration URL
|
|
default: No proxy
|
|
|