Homogeneous elements sequence

Objectives

We are going to discuss a new Rougail type, the sequence of homogeneous elements which we will call, more concisely, a sequence. It’s a rather unusual family.

Prerequisites

We assume that Rougail’s library is installed 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 rougail-tutorials git repository, this workshop page corresponds to the tag 1.1_190 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 use case, here is the Foxy Proxy widget:

A family with sequence type

Note

To be precise, we should say: a family with a sequence of homogeneous elements type.

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:

The FoxyProxy structure 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 sequence is not mandatory. This does not mean that the variable is Nullable variable or that the list is empty. In this case, that means that the sequence is empty.

Which we could write in JSON like this:

[]

Now configure the sequence:

A config/02/config.yml user data file with the proxies sequence

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

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

Which we could write in JSON like this:

[
     {
       "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 sequence type.

Let’s launch our Rougail CLI:

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:

╭──────── Caption ────────╮
│ Variable Default value  │
│          Modified value │
╰─────────────────────────╯
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"

A sequence with multiple user data

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

A 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:

[
     {
       "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:

╭──────── Caption ────────╮
│ Variable Default value  │
│          Modified value │
╰─────────────────────────╯
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"