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 ` 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 `, this workshop page corresponds to the tag :tutorial:`v1.1_010 ` 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 ` 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 .. 
╭────────────────────────── Caption ──────────────────────────╮
    │ Variable                           Default value            │
    │ Undocumented variable              Modified value           │
    │ Undocumented but modified variable (Original default value) │
    │ Unmodifiable variable                                       │
    ╰─────────────────────────────────────────────────────────────╯
    Variables:
    ┗━━ 📓 proxy_mode: No proxy
`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 ` 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 .. 
╭────────────── Caption ───────────────╮
    │ Variable Modified value              │
    │          (⏳ Original default value) │
    ╰──────────────────────────────────────╯
    Variables:
    ┗━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ No proxy)
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 ` 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 .. 
🛑 ERRORS
    ┗━━ 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 
        configuration", "No proxy" and "Use system proxy settings" are allowed, it will be ignored when loading from the YAML file "config/04/config.yml"
.. 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