A variable with possible values

Objectives

We will learn how to define variables with predefined available values.

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 v1.1_010 in the repository:

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

A variable with a list of possible values

In the firefox browser, the proxy mode can be set by this way:

A list of possible values for the proxy_mode variable is proposed. With Rougail there is the possibility of defining a list of available values with the choices variable’s parameter:

The proxy_mode variable with the choice parameter

%YAML 1.2
---
version: 1.1

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

Download this file from the rougail-tutorials git repository

Let’s run the Rougail CLI with these available values:

 rougail -m firefox/

We have an output like this one:

╭──────────────────── Caption ─────────────────────╮
│ Undocumented but modified variable Default value │
╰──────────────────────────────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: No proxy

No proxy is an available variable’s value. We say that the proxy_mode variable is constrained by the possibilities of the choice parameter.

Let’s add some user datas to this structure

A user data specification

---
proxy_mode: Manual proxy configuration

Download this file from the rougail-tutorials git repository

If we run the Rougail CLI with this user datas:

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

We have this output:

╭─────────────────────────── Caption ────────────────────────────╮
│ Undocumented but modified variable Modified value              │
│                                    (⏳ Original default value) │
╰────────────────────────────────────────────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ 
    loaded from the YAML file "config/03/config.yml" (⏳ No proxy)

As we set the proxy_mode variable from a user data file, we now have specified a value which is not a default value, and the output of the Rougail CLI explicitly shows that a user data value has been entered, it shows which user data file this value comes from, and it also indicates what the default value is for information purposes.

The constraints that come with the choices

The proxy_mode variable’s possible values is constrained.

We have the list of the possible (authorized) values:

No proxy
Auto-detect proxy settings for this network
Use system proxy settings
Manual proxy configuration
Automatic proxy configuration URL

Question

What happens if I set a value that is not available in the choices?

A (false) user data specification

---
proxy_mode: foo

Download this file from the rougail-tutorials git repository

If we run the Rougail CLI with this user datas:

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

We have this output:

🔔 WARNINGS
┗━━ the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy 
    Access to the Internet), only "Auto-detect proxy settings for this network",
    "Automatic proxy configuration URL", "Manual proxy configuration", "No 
    proxy" and "Use system proxy settings" are allowed, it will be ignored when 
    loading from the YAML file "config/04/config.yml"
╭──────────────────── Caption ─────────────────────╮
│ Undocumented but modified variable Default value │
╰──────────────────────────────────────────────────╯
Variables:
┗━━ 📓 Configure Proxy Access to the Internet: No proxy

We can see here that Rougail warns us about an invalid value that is not in the available choices, that’s why this value will not be used and it falls back to the original default value.

But maybe this is not the behavior you need. Maybe you need to stop everything if Rougail detects that something is going wrong, maybe you need some kind of a strict mode.

Indeed, this warning can be transformed into an error.

If we run the Rougail CLI with this --cli.invalid_user_datas_error parameter:

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

Then we have an error output instead of a warning output:

🛑 ERRORS
┗━━ the value "foo" is an invalid choice for "proxy_mode" (Configure Proxy 
    Access to the Internet), only "Auto-detect proxy settings for this network",
    "Automatic proxy configuration URL", "Manual proxy configuration", "No 
    proxy" and "Use system proxy settings" are allowed, it will be ignored when 
    loading from the YAML file "config/04/config.yml"

Key points progress

Indeed, in the Firefox configuration, it is possible to define several configuration modes, from no proxy at all to different kind of automatic or manual configuration modes. The choices, the list of available values for a variable, can help us to handle this situation.

Progress

To sum up, we have arrived at this point in writing a structure file like this:

Structure description file

A Rougail structure file with a variable named proxy_mode, with a default value.

%YAML 1.2
---
version: 1.1

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