167 lines
6.4 KiB
ReStructuredText
167 lines
6.4 KiB
ReStructuredText
A variable with predefined values
|
||
==================================
|
||
|
||
.. objectives:: Objectives
|
||
|
||
We will learn how to define variables with a list of 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>`
|
||
in the repository:
|
||
|
||
::
|
||
|
||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||
git checkout v1.1_004
|
||
|
||
Limits the possible values for the variable
|
||
---------------------------------------------
|
||
|
||
In the firefox browser, the proxy mode can be defined 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:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/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_004/firefox/00-proxy.yml>`
|
||
|
||
Let's run the Rougail CLI with this new structure file:
|
||
|
||
.. 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_004/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>
|
||
|
||
The `proxy_mode` variable requires a value, that's why we have set a `No proxy` default 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".
|
||
|
||
The constraints that come with the `choice` type
|
||
----------------------------------------------------
|
||
|
||
We say that the `proxy_mode` variable is *constrained* by the `choice` parameter.
|
||
|
||
FIXME continuer ici
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/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>`
|
||
|
||
If we run the rougail CLI with this user datas, we have:
|
||
|
||
.. code-block:: text
|
||
:class: terminal
|
||
|
||
rougail -m firefox -u yaml -ff config/03/config.yml
|
||
|
||
FIXME: this output is not the expected output
|
||
|
||
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
|
||
: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 value appears in green, which means : "user data value".
|
||
|
||
FIXME: verifier que cette sortie est bonne (on a des valeurs différentes)
|
||
|
||
.. type-along:: The constraints that come with the `choice` property
|
||
|
||
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`
|
||
|
||
FIXME : essayer de fixer un value qui n'est pas dans la liste et voir le résultat
|
||
|
||
.. 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`).
|
||
|
||
**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_004/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
|
||
|