rougail/docs/tutorial/preliminary.rst

Getting started
====================

.. objectives:: Objectives

   We will learn how to:

   - create a :term:`structure description file <structure file>`
   - add a :term:`structure file <structure file>` format version in the structure file
   - add a :term:`variable` in the structure file and set its default :term:`value`

.. prerequisites:: Prerequisites

    - We assume that Rougail's library is :ref:`installed <installation>` on your computer.
    - If you want to follow with this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`, 
      this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000>` to :tutorial:`v1.1_011 <src/tag/v1.1_011>`
      in the repository:

    ::
   
       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git checkout v1.1_000
      
Creating a structure file 
--------------------------

.. demo:: The folder structure

    Here is the tree structure we want to have::

        rougail-tutorials
        └── firefox
            └── 00-proxy.yml

- Let's make a :file:`rougail-tutorials` directory, with a :file:`firefox` subfolder.
- First, we will create a :term:`structure file <structure file>`, so let's create a :file:`00-proxy.yml` file
  located in the :file:`firefox` subfolder.

This is an empty Rougail :term:`structure description file: <structure file>` 

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

.. 
    ---
    version: 1.1

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_000/firefox/00-proxy.yml>`

This `version` specification is just the rougail YAML's format version specification. 
By now, we have an empty structure file with the format specification in it. 

Let's add our first variable
------------------------------

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the `v1.1_001` version::
     
          git checkout v1.1_001


- A variable is defined at a minimum by its name.
- A :term:`variable` lives in the :term:`structure description file <structure file>`.

Here we define a variable named `proxy_mode`:

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

.. 
    ---
    proxy_mode:

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_001/firefox/00-proxy.yml>`

Let's run the Rougail CLI utility command in a terminal:

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

Well, we notice that we have an error: 

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

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

It's because this first defined variable is :term:`mandatory` and needs to have a value set **but** there's no value yet.

We can therefore deduce the fact that:

.. admonition:: Fact 

    Once defined, an option configuration :term:`value` is :term:`mandatory`.
    That is to say, it is absolutely necessary to assign a value to this variable.
   
Rougail waits for the `proxy_mode` configuration option's value to be set.

.. glossary::

    mandatory

        A variable is mandatory when a value is required, that is, `None` **is not** a possible value.
        It **must** have a defined value.

.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` 
    according to the :xref:`Tiramisu <tiramisu>` underlyning consistency system. 
    You will learn that it is actually possible to disable the mandatory property behavior, 
    but you need to declare it explicitely.

Describe the variable
-------------------------
        
Let's add a variable's description, which is not mandatory but which is usually a good practice.

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the `v1.1_002` version::
     
          git checkout v1.1_002

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

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

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_002/firefox/00-proxy.yml>`

You have two way to define a variable's description: 

- the verbose way:

  .. code-block:: yaml
  
      proxy_mode:  
        description: Configure Proxy Access to the Internet


- or the compact way, using the "`#`" YAML notation:

  .. code-block:: yaml

      proxy_mode:  # Configure Proxy Access to the Internet

Set a default value
---------------------

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the `v1.1_003` version::
     
          git checkout v1.1_003

We will learn different ways to set a value, the first way is setting a *default* value. 

.. glossary::

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

Let's add a default value to this `proxy_mode` variable. 

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
    :language: yaml
    :caption: A rougail structure file with a default value for the variable
    :name: RougailDictionaryVariableDefault

..
    ---
    proxy_mode: No proxy  # Configure Proxy Access to the Internet

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/firefox/00-proxy.yml>`

.. admonition:: how to set a value -- the assignment

    A default value has been set, great. This raises the question of what constitutes a value other than a default value.

    How can I assign a value to a variable?

.. type-along:: The different rougail roles and the default values

So far we have only talked about the one that writes the :term:`structure files <structure file>`\ . It's *role* is called the integrator's role.

.. glossary::

    integrator

        An integrator in the Rougail field is the person who writes the :term:`structure files <structure file>`\ .
        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.

Now we will talk about the one that defines the values. It is called the operator.

.. glossary::

    operator

        An operator in the Rougail field is the person who assigns :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 of course type validated. The type validation is driven by the definitions in the :term:`structure file <structure file>`.

It is the operator's responsibility to set the user datas variables values.
The operator does not handle the structure files, 
he is responsible of other files called the :term:`user data file`\ s. 

.. glossary::

    user datas

        User datas, as opposed to structured datas, are datas that only concern the assignment of values
        and not the consistency of the variables.

        The variable's values are also called **user values**. 
        
        The consistency field is outside of the user datas scope. 
        The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.

.. important:: If user datas are not set, default values are mandatory, otherwise Rougail will raise an error. 

.. exercise:: Folder structure update

    Now we add a :file:`config/config.yaml` file, the :file:`config` folder is where we will place the user datas::

        rougail-tutorials
        ├── firefox
        │   ├── 00-proxy.yml
        └── config
            └── config.yaml

.. type-along:: how to set a value in a user datas file

So for example if the integrator has not set any default value in his structure file, 
it's up to the operator to do the job in the `config.yaml` file:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yml
   :language: yaml
   :caption: A Rougail user datas file :file:`config/config.yaml`, with a default value set.
   :name: RougailConfigDefaultValue

.. 
    ---
    proxy_mode: No proxy

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/config/02/config.yml>`

If you want the user datas to be taken into account, you must provide the `-u yaml -ff config/config.yaml` options
to the rougail CLI: 

.. code-block:: text
   :class: terminal
   :caption: A rougail Command Line Utility call with the :file:`config/config.yaml` Rougail user datas file

   rougail -m firefox -u yaml -ff config/02/config.yaml

which gives us this output:

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/output_ro.html
   :class: output

.. 
    <pre>╭──────── Caption ────────╮
    │ Variable Modified value │
    ╰─────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yaml"
    </pre>

We can see in the output result that the :file:`config/02/config.yml` user data file has been taken into account.

.. admonition:: Important fact

    - the integrator works on structure files
    - the operator works on user data files
    
Most of the time, the integrator and the operator are one and the same person, here we are talking about roles and not necessarily about people.    

Limits the possible values for the variable
-------------------------------------------------

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the `v1.1_004` version::
     
          git checkout v1.1_004

In our firefox use case, we can see that we have different possibilites available for the `proxy_mode` variable values:


.. image:: images/proxy_choices.png

Let's insert these different possible choices with a `choice` variable's property here:

.. 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 different possible choices
   :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 without user datas:

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

We have this output:

.. 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 have specified a value, 
and the value appears in yellow, which means : "set by default". 

.. type-along:: Let's add a user value

Now an integrator decides to set the value of the `proxy_mode` variable to `Manual proxy configuration`.

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

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

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


    **Keywords**

    - :term:`structure file <structure file>`: 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 value
    - the possibility to constrain the possible values of a variable

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