rougail/docs/tutorial/choice.rst

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