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

Presentation of the Firefox configuration options
--------------------------------------------------

At first glance we can see that we have a selection of five configuration options that we need to fill in, they are highlighted here in this screenshot:

.. image:: images/firefox_01.png

We'll learn in this tutorial how to set the values of the configuration options in a clean way with the Rougail library.

.. objectives:: Objectives of this section

   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.

    - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
      by checking out the corresponding tag of the `rougail-tutorials` git repository.
      Each tag corresponds to a stage of progress in the tutorial.
      Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.

    If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
    this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000/README.md>` to :tutorial:`v1.1_003 <src/tag/v1.1_003/README.md>`
    in the repository:

    ::
   
       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach 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.
YAML files are loaded using a version 1.2 file parser. It is recommended (but not mandatory) to specify this in the file header, especially for linters.
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 :tutorial:`v1.1_001 <src/tag/v1.1_001/README.md>` version::
     
          git switch --detach 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` by default.
    That is to say, it is absolutely necessary to assign a value to this variable.

Rougail expects 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 :tutorial:`v1.1_002 <src/tag/v1.1_002/README.md>` version::
     
          git switch --detach 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 a short-hand way, setting the description using the "`#`" YAML comment notation:

  .. code-block:: yaml

      proxy_mode:  # Configure Proxy Access to the Internet

If we launch the Rougail CLI command:

.. raw:: html
   :class: terminal
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/config/01/cmd_rw.txt

we have this output:

.. raw:: html
   :class: output
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/config/01/output_rw.html

..
    <pre>╭──────────────────── Caption ─────────────────────╮
    │ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #ffd700">Default value</span> │
    ╰──────────────────────────────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">null</span>
    </pre>

We can see here that the variable's description string "Configure Proxy Access to the Internet" is used
to refer to the `proxy_mode` variable.

.. note:: The description is used in UI tools and outputs instead of the variable name.
          The goal here is to provide an explanation of the variable for the user,
          not to show the technical name of the variable as defined by the :term:`integrator`.

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 :tutorial:`v1.1_003 <src/tag/v1.1_003/README.md>` version::
     
          git switch --detach 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>`

The `proxy_mode` variable requires a value, that's why we have set a `No proxy` default value.

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

..
    <pre>╭─────── Caption ────────╮
    │ Variable <span style="color: #ffd700">Default value</span> │
    ╰────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
    </pre>

As we have set the `proxy_mode`'s value as `No proxy` by default,
The chosen value is indicated in the Rougail's CLI output as the default choice.

- here is the short-hand default setting and description:

.. code-block:: yaml

    proxy_mode: No proxy  # Configure Proxy Access to the Internet

- and there is the verbose way of setting a default value:

.. code-block:: yaml

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

There are some other :term:`short-hand ways <short-hand notation>` with Rougail that you may encounter
as you read the Rougail's documentation and tutorial.

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

    A default value has been set, great. This raises a question about what a normal value is.

    Now then how can I assign a normal value to a variable?

.. type-along:: The different Rougail roles and setting a variable's value

So far we have only talked about the actor that writes the :term:`structure files <structure file>`\ .
The one who writes the structure file plays the *role* of the *integrator*.

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

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

.. important:: For now, we don't know how to disable the default `mandatory` settings,
   so if neither a default value nor a user value are set for a given variable, Rougail will raise an error.

.. exercise:: Folder structure update

    Now we add a user data file named :file:`config/config.yml` in our project::

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

.. type-along:: How to set a user data value

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.yml` 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 data file :file:`config/config.yml`, with a 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>`

The operator needs to add the `-u yaml -yf config/config.yml` options to the Rougail CLI:

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/cmd_ro.txt
   :class: terminal

..
    rougail -m firefox/ -u yaml -yf config/02/config.yml

which gives us this output:

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/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.yml"
    </pre>

Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see in the Rougail CLI output that the value
comes from the :file:`config/02/config.yml` user data file. From now on this `proxy_mode` variable's value
is a user data value and not a default value (even if it's actually the same value).

.. type-along:: Structure values and user data values

We can see with the Rougail CLI utility where the values come from.
It can come from an integrator's setting or from an operator's setting.

.. admonition:: Reminder

    - the integrator works on structure files, he can define default value for variables
    - the operator works on user data files, he only can set user data values for variables

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.

.. type-along:: User data files are where the user values live

We need to set the values in separate files, called `user data files`.

.. glossary::

   user data file
   
       A user data file is a file where only :term:`user data` are set.

       A user file is a file where there are only user data in it, users can set values, called user values --
       that is variable's values that have been set by an :term:`operator`\ .
       
       see also :term:`user data`

.. keypoints:: Key points progress

    **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 mandatory value
    - a variable's default value
    - a variable's user value
    - the :term:`integrator` and :term:`operator` roles
    - a :term:`configuration`
