rougail/docs/tutorial/family.rst

Group variables inside families
=================================

.. objectives:: Objectives

   We will learn how to:

   - create a :term:`family`
   - gather :term:`variable`\ s into a :term:`family`
   - make a variable within a variable, which turns this variable container into being a family

.. 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_020 <src/tag/v1.1_020/README.md>` to :tutorial:`v1.1_022 <src/tag/v1.1_022/README.md>`
    in the repository.

    ::

       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach v1.1_020

.. type-along:: Let's recap how far we've come

We have this choice variable in its structure definition file:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: The `proxy_mode` choice variable in the :file:`firefox/00-proxy.yml` structure file

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

.. We're gonna put it in a :term:`family`.

In short, let's describe our `proxy_mode` variable like this:

.. confval:: proxy_mode
   :type: `choice`
   :default: No proxy

   Proxy mode's settings

Now we will define new variables, and other structure definitions.
For the sake of clarity, we will put the structure definitions in separate files.
Please have a look at the :ref:`file naming and organizing convention <namingconvention>`.

Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make
a new structure file named :file:`firefox/10-manual.yml`::

    .
    └── firefox
        ├── 00-proxy.yml
        └── 10-manual.yml

Creating a new family
-----------------------

Let's create a family named `manual` which obviously corresponds to the proxy's manual configuration choice.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
   :language: yaml
   :caption: A family structure file description named `manual` in a :file:`firefox/10-manual.yml` file
   :name: RougailManualFamily

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

We can see that we have defined a :term:`family` here, and this family is *empty*
which means that this family is a container variable that contains no variable yet.

.. warning::

    If a family is empty, we need to specify the :term:`family` type here because if we don't,
    the Rougail's type engine will infer it by default as a :term:`variable`.
    We have to force the family type inference.

    It's because we don't have set any :term:`variable` inside yet. When we will have a variable inside of this family,
    we will make a YAML block (to create a block in YAML, you just need to indent the lines) and the Rougail's type inference engine will implicitely infer the variable's container as a family type.

.. important::

    Any family that has been declared in a structure file but is empty (i.e., contains neither :term:`variables <variable>` nor :term:`subfamilies <subfamily>`) is not taken into account by the low level :term:`Tiramisu <tiramisu>` consistency engine.

Or a sub family
----------------

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

    Now you need to checkout the :tutorial:`v1.1_021 <src/tag/v1.1_021/README.md>` version::

          git switch --detach v1.1_021

.. glossary::

   sub family

       A sub family is a family inside a family.

Creating a family hierarchy of families (family inside a family) is very easy:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml
   :language: yaml
   :caption: A rougail structure description file with a hierarchy.
   :name: RougailFirstFamilyHierarchy

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

      http_proxy:
        description: HTTP Proxy
        type: family

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

Here in our use case we used the :term:`short-hand declaration mode <short-hand notation>`
to declare our `manual` family:

.. code-block:: yaml

    manual:  # Manual proxy configuration

And the `http_proxy` family lives inside of this `manual` family.
We therefore created a hierarchy of families.

Putting a variable inside of a family or a sub family
-----------------------------------------------------------

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

    Now you need to checkout the :tutorial:`v1.1_022 <src/tag/v1.1_022/README.md>` version::

          git switch --detach v1.1_022

We are going to put a variable inside of a family or a sub family

Let's create a variable in the `http_proxy` family.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml
   :language: yaml
   :caption: An `address` variable in the `http_proxy` family
   :name: RougailVariableInSubFamily

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

      http_proxy:
        description: HTTP Proxy
        type: family

        address:
          description: HTTP address

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_022/firefox/10-manual.yml>`

Now that the :confval:`address` variable is declared, the :term:`operator` can set :term:`a value <value>` to it.

In short, let's describe our `address` variable like this:

.. confval:: address
   :default: None

   This is the HTTP address of the proxy

We have reached the definition of the address in the `http_proxy` family; there will be other variables to define in this family.

.. image:: images/firefox_manual_family.png

.. type-along:: Assigning a user value

Now we need to set a value ​​for the :confval:`address` variable,
otherwise we will get an error if we try to access this variable:

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

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

.. type-along:: Let's set user values in a user data file

Here is a user data file sample:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/02/config.yml
   :language: yaml
   :caption: A user file named :file:`config/03/config.yml` with a value set for the `address` variable
   :name: RougailAddresseVariableUserValue

..
    ---
    proxy_mode: Manual proxy configuration
    manual:
      http_proxy:
        address: example.net

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

Let's validate the consitency of the :term:`configuration`:

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

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

Everything is OK:

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

..
    <pre>╭──────── Caption ────────╮
    │ Variable <span style="color: #ffd700">Default value</span>  │
    │          Modified value │
    ╰─────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
    <span style="color: #5c5cff">┗━━ </span>📂 Manual proxy configuration
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📂 HTTP Proxy
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 HTTP address: example.net ◀ loaded from the YAML file "config/02/config.yml"
    </pre>

Let's recap about the user data. We can see in this Rougail CLI output that:

- the `proxy_mode` value is set by default by the :term:`integrator`
- the `address` value is has been set by an :term:`operator`

.. keypoints:: Let's review the key points

    **Keywords**

    - we know how to define :term:`variable`\ s inside of a family
    - we now know what a :term:`mandatory` variable is and why it is necessary to assign values to the variables
    - we kwow how to set a variable's :term:`user value <user data>`
    - we have the big picture : the :term:`configuration`, which is (the structure files + the user data files)

    **Progress**

    - we have a :term:`family` named `manual`  and a sub family named `http_proxy`
    - And we have now two variables: :confval:`proxy_mode` and :confval:`address`.

.. seealso::

   The full documentation about a :term:`family`.