rougail/docs/tutorial/choice.rst

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