rougail/docs/tutorial/choice.rst

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.
    - 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_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