222 lines
8.8 KiB
ReStructuredText
222 lines
8.8 KiB
ReStructuredText
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>` in the repository:
|
||
|
||
::
|
||
|
||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||
git checkout 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 `choice` 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 datas 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 datas:
|
||
|
||
.. 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 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 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
|
||
|