rougail/docs/tutorial/preliminary.rst

Preliminaries
================

.. objectives:: Objectives

   We will learn how to:

   - create a Rougail :term:`structure description file <dictionary>`
   - define a Rougail :term:`structure description file <dictionary>` format version
   - define a Rougail :term:`variable` and set its :term:`value`

.. prerequisites:: Prerequisites

    We assume that Rougail's library is :ref:`already installed <installation>` on your computer (or in a virtual environment).

.. type-along:: an empty dictionary

    An empty structure description file

.. exercise:: The folder structure

    Here is the tree structure we want to have::

        workplace
        ├── firefox
        │   ├── dictionary.yml

- Let's make a :file:`workplace` directory, with a :file:`firefox` subfolder.
- First, we wil make a :term:`dictionary`, so let's create a :file:`dictionary.yml` file
  located in the :file:`firefox` subfolder.

The dictionary
----------------

This is an empty Rougail dictionnary

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
   :language: yaml
   :caption: An empty rougail dictionnary file with the version number only
   :name: RougailDictionaryEmptyFile

.. 
    ---
    version: 1.1

.. type-along:: a first variable

    Let's put a variable in the Rougail :term:`structure description file <dictionary>`


Defining a variable and its default value
----------------------------------------------

This is a first Rougail variable in a Rougail dictionnary.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
   :language: yaml
   :caption: A Rougail dictionnary file with only one variable
   :name: RougailDictionaryFirstVariableName

.. 
    ---
    proxy_mode:

- Then we will run this command 

.. code-block:: text
   :class: terminal
   
    rougail -v 1.1 -m firefox/

which actually outputs an error: 

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/01/output_ro.html
   :class: error-box

..
    🛑 ERRORS
    ┣━━ The following variables are mandatory but have no value:
    ┗━━   - proxy_mode

Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.


Here we juste add a variable's description, which is a good practice.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
   :language: yaml
   :caption: A Rougail dictionnary file with a variable and a description
   :name: RougailDictionaryFirstVariableDescription

.. 
    ---
    proxy_mode:
      description: Configure Proxy Access to the Internet

We need a **default value**. 

.. glossary::

    default values
        
        A default value is a variable value that is predefined, that is, this value is placed 
        right in the structure file.

So let's define a variable with a description -- **and a default value**


.. FIXME trouver une url qui corresponde à une valeur par défaut **dans le dictionnaire**

.. code-block:: yaml

    ---
    proxy_mode:
      description: Configure Proxy Access to the Internet
      default: No proxy


 :ref:`Here is a Rougail variable with a default value <RougailDictionaryFirstVariableDefault>`

.. type-along:: how to set a value

    A default value has been set, great. Now how do I assign a value to a variable?

The integrator role
----------------------

.. glossary::

    integrator

        An integrator in the Rougail logic is the person who writes the :term:`structure files <dictionaries>`\ .
        He has the responsibilité of the integration process, that is,
        defines the variables and the relationship between them, the variables that are allowed
        (or not) to be set, and so on. His responsabilites are the **structuration** and the **consistency**
        of the variables.

        .. image:: images/integrator.png

.. important:: Note that there is a strong consistency, it means that the validation is done across
               the entire structure, not only with a schema (type) validation system.

The operator role
---------------------

.. glossary::

    operator

        An operator ih the Rougail logic is the person who gives :term:`value`\ s to the pre-defined variables,
        his responsabilities are to set variable values correctly.

        The user :term:`value`\ s, that is the values that have been set by the operator, are validated
        by the :term:`structure file <dictionary>`.

        .. image:: images/operator.png

The operator can use the Rougail CLI interface:

.. image:: images/QuestionaryChoice.png

.. index:: Rougail CLI

The Rougail CLI can output a rather complete view of the dataset:

.. image:: images/UserDataOutput.png

Values are mandatory
-------------------------

.. important:: It is the operator's responsibility to set configuration options values.

So, if :

- there is no default value set in the structure file,
- no value is set in the value file:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: The :file:`firefox/00-proxy.yaml` Rougail structure file, with no default value set.
   :name: RougailDictionaryNoDefault

..
    ---
    proxy_mode:

Then the rougail CLI will output an error :

.. code-block:: shell
   :caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` Rougail dictionnary file

   rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_010/config/01/output_ro.html

..
    <pre>🛑 ERRORS
    <span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
    <span style="color: #ff0000">┗━━ </span>  - proxy_mode
    </pre>

.. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`.

Rougail waits for the `proxy_mode` configuration option's value to be set.

.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` Tiramisu's definition.

.. glossary::

    mandatory

        A variable is mandatory when a value is required, that is, `None` is not an option.

Variable's type
-----------------

If the `type` attribute is not set, Rougail infers a `string` type for the `proxy_mode` configuration option variable type as defined in the structure file.

If the operator sets an option value for example with the `number` type, like this:

.. code-block:: yaml

    ---
    example_var:
      description: Configure Proxy Access to the Internet
      type: number

Then Rougail will expect a `int` or a `float` as a value for the `example_var` variable.
In our firefox use case, the real type of the `proxy_mode` variable is a `choice` type:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: The :file:`firefox/00-proxy.yml` Rougail dictionnary file, with a default value set.
   :name: RougailDictionaryChoiceTypeWitheDefault

..
    ---
    proxy_mode:
      description: Configure Proxy Access to the Internet
      type: choice
      choices:
        - No proxy
        - Auto-detect proxy settings for this network
        - Use system proxy settings
        - Manual proxy configuration
        - Automatic proxy configuration URL
      default: No proxy

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/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.

It shall have a value, but what if the user *does not* specify any value?
There is a possibility of setting a default value, wich is set as `No proxy` by default.

Container type
-----------------

We say that the `proxy_mode` variable is *constrained* (by the `choice` type).

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`

.. glossary::

    choice type

        The `proxy_mode` setting is "choice" (`type: choice`) means that
        there is a list of available values that can be selected.

.. note:: 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`).

.. keypoints:: Key points progress

    **Keywords**

    - :term:`structure file <dictionary>`: structure description file
    - :term:`variable`: an option's name which has a value
    - a variable's description
    - a variable's type
    - a variable's default value
    - the :term:`integrator` and :term:`operator` roles
    - a mandatory value
    - a choice type

    To sum up, we have arrived at this point in writing the structure file:

    **Structure description file**

    .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
       :linenos:
       :language: yaml
       :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value.

..

   .. raw:: text

    ---
    proxy_mode:
      description: Configure Proxy Access to the Internet
      type: choice
      choices:
        - No proxy
        - Auto-detect proxy settings for this network
        - Use system proxy settings
        - Manual proxy configuration
        - Automatic proxy configuration URL
      default: No proxy