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

The :term:`sequence` type ensures that in the `proxies` family, if a proxy type is specified, then an associated color will also be specified.
Let's launch the Rougail CLI on this structured data:

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

.. raw:: html
   :class: terminal
   :url: 

..
    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"
                    
FIXME: je ne comprends pas bien pourquoi on a title qui est une espèce de multi à elle seule dans le output 

::

            ┗━━ 📂 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"
                    

.. seealso::

   You can have a look at the Rougail format pages :ref:`Sequence of homogeneous elements <sequence_family>`


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

   We saw a :term:`sequence` type family.