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

.. objectives:: Objectives

   We will learn how to:

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

.. type-along:: Reminders

   We already learned in other workshops how to:

   - define a Rougail :term:`structure description file <dictionary>`

     :ref:`Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`

   - define a variable and its default value

     :ref:`Here is a first Rougail variable in a Rougail dictionnary <RougailDictionaryFirstVariable>`

   - define a variable with a description

     :ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDescription>`

   - define a variable with a description and a default value

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


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

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_004/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: The :file:`config/01/config.yaml` rougail dictionnary file, with no default value set.
   :name: RougailDictionaryNoDefaultUseCase

In this situation there are no default value set. 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

   foo@bar:~$ 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_003/config/01/output_ro.html


Rougail waits for a value to be set, that's why.

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

Type inférence
-----------------

By default, rougail infers a `string` type.
If the operator sets an option value with the `string` type, like this:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/05/config.yaml
   :linenos:
   :language: yaml
   :caption: The :file:`config/05/config.yaml` rougail dictionnary file, with no default value set.
   :name: RougailDictionaryNoDefaultUseCaseIntOptionValue

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

.. 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 default value
    - the :term:`integrator` and :term:`operator` roles
    - a mandatory option value


    To sum up, we have arrived here

    **Structure definition file**

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