Some suitable types

Objectives

There isn’t just the basic string available type, here we will discover new variable types, for example the boolean type, and even types that are much more suited to our use case, such as domainname or port.

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 tags v1.1_030 to v1.1_033 in the repository.

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

let’s recap how far we’ve come

We have an http_proxy family with an address variable in it.

An address variable in the http_proxy family
%YAML 1.2
---
version: 1.1

manual:  # Manual proxy configuration

  http_proxy:  # HTTP Proxy

    address:  # HTTP address
...

Download this file from the rougail-tutorials git repository

A variable with type domainname

We will add a business types to our address variable:

An address variable in the http_proxy family
%YAML 1.2
---
version: 1.1

manual:  # Manual proxy configuration

  http_proxy:  # HTTP Proxy

    address:
      description: HTTP address
      type: domainname
...

Download this file from the rougail-tutorials git repository

Notice that with this type: domainname we have assigned the domainname business type to this variable. Assigning a type is convenient for reading, but what else does it bring?

Well, with a correct user data like this one:

A domain name user data setting
---
manual:
  http_proxy:
    address: example.net

Download this file from the rougail-tutorials git repository

if we launch the Rougail CLI on it:

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

We have this output:

╭───────────────────── Caption ─────────────────────╮
│ Variable                           Default value  │
│ Undocumented but modified variable Modified value │
╰───────────────────────────────────────────────────╯
Variables:
┣━━ 📓 Configure Proxy Access to the Internet: No proxy
┗━━ 📂 Manual proxy configuration
    ┗━━ 📂 HTTP Proxy
        ┗━━ 📓 HTTP address: example.net ◀ loaded from the YAML file 
            "config/01/config.yml"

And we don’t really see any change associated with the fact that we have assigned a type to this variable. But if we assign this (wrong) user data:

A domain name has no space in it

Let’s have a look at an example of user setting that does not fit the domainname type:

An invalid domain name for the config/03/config.yml user data setting
---
manual:
  http_proxy:
    address: not a valid domain name

Download this file from the rougail-tutorials git repository

The value is obviously not a domain name, then when we will launch the Rougail CLI:

rougail -m firefox/ -u yaml -yf config/03/config.yml --cli.invalid_user_datas_error

we then have this output:

🛑 ERRORS
┗━━ the value "not a valid domain name" is an invalid domain name for 
    "manual.http_proxy.address" (HTTP address), must have dot, it will be 
    ignored when loading from the YAML file "config/03/config.yml"

A variable with type’s parameters

What if we set an IP address instead of a domain name?

A domain name in the config/02/config.yml user data setting with an IP address
---
manual:
  http_proxy:
    address: 192.168.0.1

Download this file from the rougail-tutorials git repository

With a value that is not a domain name but an IP address, then when we will launch the Rougail CLI we will see a little problem:

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

we then have this output:

🛑 ERRORS
┗━━ the value "192.168.0.1" is an invalid domain name for 
    "manual.http_proxy.address" (HTTP address), must not be an IP, it will be 
    ignored when loading from the YAML file "config/02/config.yml"

We observe that an error has been raised because an IP address is not a domain name. Therefore, a type validation is taking place because we declared the type domainname.

Question

OK I agree with the domainname necessary type validation, but what if I want to specify an IP address as a user value for this address variable? Because it is therefore simply impossible to do so now.

Is there a way for my address variable to accept an IP address?

Well, it is possible to configure the type so that it accepts IP addresses. We need to specify whether our variable accepts to be filled using an IP or a domain name only. This is where the ability to parameterize our variable comes in.

For those who follow the tutorial with the help of the git repository

Now you need to checkout the v1.1_031 version:

git switch --detach v1.1_031

Let’s add a type parameter named allow_ip:

The allow_ip type parameter set in the firefox/10-manual.yml structure file
 1%YAML 1.2
 2---
 3version: 1.1
 4
 5manual:  # Manual proxy configuration
 6
 7  http_proxy:  # HTTP Proxy
 8
 9    address:
10      description: HTTP address
11      type: domainname
12      params:
13        allow_ip: true
14...

The params allow the domain name address variable to be set with IPs.

type parameter

A type parameter is a parameter of a variable that can refine its behavior. It is declared by adding the params attribute in the variable’s definition.

Now we will test with an IP address as the value for our address variable.

An IP address as a value in the config/02/config.yml user value
---
manual:
  http_proxy:
    address: 192.168.0.1

Download this file from the rougail-tutorials git repository

if we launch the Rougail CLI on it:

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

We have this output:

╭───────────────────── Caption ─────────────────────╮
│ Variable                           Default value  │
│ Undocumented but modified variable Modified value │
╰───────────────────────────────────────────────────╯
Variables:
┣━━ 📓 Configure Proxy Access to the Internet: No proxy
┗━━ 📂 Manual proxy configuration
    ┗━━ 📂 HTTP Proxy
        ┗━━ 📓 HTTP address: 192.168.0.1 ◀ loaded from the YAML file 
            "config/02/config.yml"

We can see that the IP address value has been accepted.

A variable with type port

For those who follow the tutorial with the help of the git repository

Now you need to checkout the v1.1_032 version:

git switch --detach v1.1_032

After the address variable let’s add, according to our use case, a new variable of type port:

../_images/firefox_port.png

Our structure file looks like this:

The port type variable in the firefox/10-manual.yml structure file
 1%YAML 1.2
 2---
 3version: 1.1
 4
 5manual:  # Manual proxy configuration
 6
 7  http_proxy:  # HTTP Proxy
 8
 9    address:
10      description: HTTP address
11      type: domainname
12      params:
13        allow_ip: true
14
15    port:
16      description: HTTP Port
17      type: port
18      default: 8080
19...

Download this file from the rougail-tutorials git repository

Let’s assign a value to this port:

A user data config/02/config.yml setting a value to the port variable
---
proxy_mode: Manual proxy configuration
manual:
  http_proxy:
    address: example.net
    port: 3128

Download this file from the rougail-tutorials git repository

If we launch the Rougail CLI:

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

We have this output:

╭─────────────────────────── Caption ────────────────────────────╮
│ Variable                           Modified value              │
│ Undocumented but modified variable (⏳ Original default value) │
╰────────────────────────────────────────────────────────────────╯
Variables:
┣━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ 
┃   loaded from the YAML file "config/02/config.yml" (⏳ No proxy)
┗━━ 📂 Manual proxy configuration
    ┗━━ 📂 HTTP Proxy
        ┣━━ 📓 HTTP address: example.net ◀ loaded from the YAML file 
        ┃   "config/02/config.yml"
        ┗━━ 📓 HTTP Port: 3128 ◀ loaded from the YAML file 
            "config/02/config.yml" (⏳ 8080)

How can we know what validations the port type performs on the value assigned to the variable?

There are a number of validations that are carried out with this port type. Now let’s assign a value that is outside the allowed ports:

A user value in config/03/config.yml that is not allowed
---
proxy_mode: Manual proxy configuration
manual:
  http_proxy:
    address: example.net
    port: 100000

Download this file from the rougail-tutorials git repository

Again, we launch the Rougail CLI:

rougail -m firefox/ -u yaml -yf config/03/config.yml --cli.invalid_user_datas_error

And we have this output:

🛑 ERRORS
┗━━ the value "100000" is an invalid port for "manual.http_proxy.port" (HTTP 
    Port), must be between 1 and 65535, it will be ignored when loading from the
    YAML file "config/03/config.yml"

We observe that, as with the domainname type, a number of validations are performed to ensure that the value assigned to this variable conforms to the port type.

A variable with type boolean

For those who follow the tutorial with the help of the git repository

Now you need to checkout the v1.1_033 version:

git switch --detach v1.1_033

Let’s add one more variable in the manual family, with a much more basic type: boolean.

A new structure file firefox/20-manual.yml with one variable
%YAML 1.2
---
version: 1.1

manual:

  use_for_https: true  # Also use this proxy for HTTPS
...

Download this file from the rougail-tutorials git repository

Note

  • it is not necessary to declare the variable as a boolean type this type is inferred by the true default value

  • we have decided to create a new structure file firefox/20-manual.yml. This is not necessary but usefull, please have a look at the structure file organization and naming conventions

  • here we reuse the manual existing family name that has already been declared in the firefox/10-manual.yml structure file. The content in the firefox/20-manual.yml will be added to the existing manual family. Note that if two different structure files are loaded by Rougail and if they declare the same family name, then the declarations are concatenated in the family name.

Let’s switch this boolean variable to a false value, to do this we will add this config/02/config.yml user data file in the configuration:

A config/02/config.yml user data file with false as a value for use_for_https
---
manual:
  http_proxy:
    address: example.net
  use_for_https: false

Download this file from the rougail-tutorials git repository

Let’s run the Rougail CLI:

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

the result is:

╭─────────────────────────── Caption ────────────────────────────╮
│ Variable                           Default value               │
│ Undocumented but modified variable Modified value              │
│                                    (⏳ Original default value) │
╰────────────────────────────────────────────────────────────────╯
Variables:
┣━━ 📓 Configure Proxy Access to the Internet: No proxy
┗━━ 📂 Manual proxy configuration
    ┣━━ 📂 HTTP Proxy
    ┃   ┣━━ 📓 HTTP address: example.net ◀ loaded from the YAML file 
    ┃   ┃   "config/02/config.yml"
    ┃   ┗━━ 📓 HTTP Port: 8080
    ┗━━ 📓 Also use this proxy for HTTPS: false ◀ loaded from the YAML file 
        "config/02/config.yml" (⏳ true)

We could of course perform several tests on type validators, but here the validation is simple: only two values ​​are allowed (true or false).

let’s review the key points

  • we can assign a domainname type to a variable

  • we can set a type parameter to a domainname variable to refine their typing behavior

  • we can assign a port type to a variable

  • we know how to set a boolean type variable to true or false