rougail/docs/tutorial/sequence.rst

Homogeneous elements sequence
==================================

.. objectives:: Objectives

   We are going to discuss a new Rougail type, :term:`the sequence of homogeneous elements <sequence>`
   which we will call, more concisely, a :term:`sequence`. It's a rather unusual :term:`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 tag :tutorial:`1.1_190 <src/tag/1.1_190/README.md>`
    in the repository.

    ::

       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach 1.1_190

As a reminder, we are now talking about the Firefox add-on called 
`Foxy Proxy <https://addons.mozilla.org/en-US/firefox/addon/foxyproxy-standard/>`_ use case,
here is the Foxy Proxy widget:

.. image:: images/foxyproxy.png

A family with sequence type
------------------------------

.. note:: To be precise, we should say: a :term:`family with a sequence of homogeneous elements type <sequence>`.

Our request here is to have a list of homogeneous objects.
Indeed, if we click on "Add proxy" in our Foxy Proxy widget, we will need to specify:

- a proxy type
- a color

(and also enter some other values).
And this applies to each proxy we will define.

Here is the structure file associated with this use case:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_190/foxyproxy/00-foxyproxy.yml
   :language: yaml
   :caption: The FoxyProxy structure file :file:`foxyproxy/00-foxyproxy.yml` with the `proxies` sequence variable

..
    %YAML 1.2
    ---
    version: 1.1

    proxies:
      description: Proxy configuration
      type: sequence

      title:
        description: Title or Description
        mandatory: false

      color:  # Color
    ...

Unsurprisingly, the way to assign the `sequence` type is done with the help of the `type` parameter.
We see here that `proxies` is a family because it contains the variables `title` and `color`.

There is nothing new to say to this two variable:

- `title` is not mandatory string
- `color` is just a string

.. note::

   The first variable of the :term:`sequence` is not mandatory.
   This does not mean that the variable is :ref:`tutorial_nullable` or that the :ref:`list is empty <tutorial_not_mandatory_list>`.
   In this case, that means that the sequence is empty.

Which we could write in JSON like this:

        .. code-block:: json

           []

Now configure the sequence:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_190/config/02/config.yml
   :language: yaml
   :caption: A :file:`config/02/config.yml` user data file with the `proxies` sequence

..
    ---
    foxyproxy:
      proxies:
        - title: My company
          color: '#66cc66'

We can see in the :term:`user data` YAML file that the `proxies` value is a list of mappings.

Which we could write in JSON like this:

        .. code-block:: json

           [
                {
                  "title": "My company",
                  "color": "#66cc66"
                }
           ]

So we can clearly see in the JSON that if there's a `title` key, then there will also be a `color` key.

This is guaranteed by our :term:`sequence` type.

Let's launch our Rougail CLI:

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

..
    rougail -m firefox/ -s Firefox -xn FoxyProxy -xd 0 foxyproxy/ --types types/proxy --modes_level basic standard advanced -u yaml -yf config/02/config.yml

And the Rougail output is:

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

..
    Variables:
    ┣━━ 📂 firefox (Firefox)
    ┃   ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): No proxy
    ┃   ┗━━ 📂 dns_over_https (DNS over HTTPS)
    ┃       ┗━━ 📓 enable_dns_over_https (Enable DNS over HTTPS): false
    ┗━━ 📂 foxyproxy (FoxyProxy)
        ┗━━ 📂 proxies (Proxy configuration)
            ┗━━ 📂 title (Title or Description)
                ┣━━ 📓 title (Title or Description): My company ◀ loaded from the 
                ┃   YAML file "config/02/config.yml"
                ┗━━ 📓 color (Color): #66cc66 ◀ loaded from the YAML file 
                    "config/02/config.yml"

.. type-along:: A sequence with multiple user data

We will now look at the same `proxies` sequence variable, 
to which multiple values ​​are assigned:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_190/config/03/config.yml
   :language: yaml
   :caption: A :file:`config/03/config.yml` user data file with multiple values

..
    ---
    foxyproxy:
      proxies:
        - title: My company
          color: '#66cc66'
        - title: An other company
          color: '#cc66cc'
        - title: WPAD
          color: '#1166cc'


Which we could write in JSON like this:

        .. code-block:: json

           [
                {
                  "title": "My company",
                  "color": "#66cc66"
                },
                {
                  "title": "An other company",
                  "color": "#cc66cc"
                },
                {
                  "title": "WPAD",
                  "color": "#1166cc"
                }

           ]


And now we can clearly see that this `proxies` variable of type `sequence` 
is a container for lists of values ​​of the same shape,
and which contain the same number of elements:

.. raw:: html
  :class: output 
  :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_190/config/03/output_ro.html

..
    Variables:
    ┣━━ 📂 firefox (Firefox)
    ┃   ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): No proxy
    ┃   ┗━━ 📂 dns_over_https (DNS over HTTPS)
    ┃       ┗━━ 📓 enable_dns_over_https (Enable DNS over HTTPS): false
    ┗━━ 📂 foxyproxy (FoxyProxy)
        ┗━━ 📂 proxies (Proxy configuration)
            ┣━━ 📂 title (Title or Description)
            ┃   ┣━━ 📓 title (Title or Description): My company ◀ loaded from the 
            ┃   ┃   YAML file "config/03/config.yml"
            ┃   ┗━━ 📓 color (Color): #66cc66 ◀ loaded from the YAML file 
            ┃       "config/03/config.yml"
            ┣━━ 📂 title (Title or Description)
            ┃   ┣━━ 📓 title (Title or Description): An other company ◀ loaded from 
            ┃   ┃   the YAML file "config/03/config.yml"
            ┃   ┗━━ 📓 color (Color): #cc66cc ◀ loaded from the YAML file 
            ┃       "config/03/config.yml"
            ┗━━ 📂 title (Title or Description)
                ┣━━ 📓 title (Title or Description): WPAD ◀ loaded from the YAML 
                ┃   file "config/03/config.yml"
                ┗━━ 📓 color (Color): #1166cc ◀ loaded from the YAML file 
                    "config/03/config.yml"

.. seealso::

   To go further, you can have a look at the Rougail format pages :ref:`Sequence of homogeneous elements <sequence_family>`

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

   **Keywords**
   
   Sequence.
   We saw a :term:`sequence` type family, which full name is :ref:`Sequence of homogeneous elements <sequence_family>`.

   **Comments**

   What is remarkable here is that we are dealing with a new form of :term:`consistency`
   which focuses on variables that are similar within a family, 
   not because they have the same type, but because, as they are lists,
   they must have the same number of elements.