141 lines
5.5 KiB
ReStructuredText
141 lines
5.5 KiB
ReStructuredText
A variable with a list of possible values
|
|
=========================================
|
|
|
|
|
|
|
|
.. type-along:: Defining a choice type
|
|
|
|
In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type:
|
|
|
|
.. seealso:: Have a look at the definition of the :term:`choice type variable <choice type>`
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type
|
|
: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
|
|
|
|
.. code-block:: text
|
|
:class: terminal
|
|
|
|
rougail -v 1.1 -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 here, implicitely requires a value. It is a :term:`mandatory` variable.
|
|
|
|
As we set the `proxy_mode` variable as `No proxy` by default, we actually have specified a value, and the value appears in yellow, which means : "set by default".
|
|
|
|
The constraints that come with the `choice` type
|
|
----------------------------------------------------
|
|
|
|
We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
|
|
|
|
.. 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
|
|
|
|
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`
|
|
|
|
.. 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
|
|
|