Preliminaries

Objectives

We will learn how to:

create a Rougail structure description file
define a Rougail structure file format version
define a Rougail variable and set its value

Prerequisites

We assume that Rougail’s library is globally installed on your computer or locally in a virtual environment.

an empty structure file

An empty structure description file

The folder structure

Here is the tree structure we want to have:

workplace
├── firefox
│   └── struct.yml

Let’s make a workplace directory, with a firefox subfolder.
First, we wil make a structure file, so let’s create a struct.yml file located in the firefox subfolder.

The structure file

This is an empty Rougail dictionnary

An empty rougail dictionnary file with the version number only

---
version: 1.1

a first variable

Let’s put a variable in the Rougail structure description file

Defining a variable and its default value

This is a first Rougail variable in a Rougail dictionnary.

A Rougail dictionnary file with only one variable

---
proxy_mode:

Then if we run the Rougail CLI utility command

 rougail -v 1.1 -m firefox/

we will actually have an error:

🛑 ERRORS
┣━━ The following variables are mandatory but have no value:
┗━━   - proxy_mode

Because this variable is mandatory and needs to be set but there’s no value yet.

So we can therefore see this consequence:

Important

Once defined, an option configuration value is mandatory.

Rougail waits for the proxy_mode configuration option’s value to be set.

How to set a value

So far we have only talked about the one that writes the structure files. It’s role is called the integrator’s role.

integrator: An integrator in the Rougail logic is the person who writes the structure files. He has the responsibilité of the integration process, that is, defines the variables and the relationship between them, the variables that are allowed (or not) to be set, and so on. His responsabilites are the structuration and the consistency of the variables.

Now we will talk about the one that defines the values. It is called the operator.

operator

An operator ih the Rougail logic is the person who gives values to the pre-defined variables, his responsabilities are to set variable values correctly.

The user values, that is the values that have been set by the operator, are of course type validated. The type validation is driven by the definitions in the structure file.

Values are mandatory

It is the operator’s responsibility to set the user datas variables values. The operator does not toutch the structure files, he is responsible for other files called the user data files.

user datas: User datas, as opposed to structured datas, means datas where the consistency of the variables is not concerned, not in the scope (the consistency in the structured datas scope’s). For example, variable’s values (which are also called user values).

Folder structure update

Now we add a config/config.yml file in our project:

workplace
├── firefox
│   ├── struct.yml
└── config
    └── config.yml

how to set a value in a user datas file

So for example if the integrator has not set any default value in his structure file, the operator can do it like this:

A Rougail user datas file config/config.yml, with a default value set.

---
proxy_mode: No proxy

With the rougail CLI the operator has to add the -u file -ff config/config.yml options:

A rougail Command Line Utility call with the config/config.yml Rougail user datas file

rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml

Let us clarify this essential point:

the integrator works on structure files
the operator works on user data files

Note

Most of the time, the integrator and the operator are one and the same person, here we are talking about roles and not necessarily about people.

Variable’s type

If the type attribute is not set, Rougail infers a string type for the proxy_mode configuration option variable type as defined in the structure file.

If the operator sets an option value for example with the number type, like this:

---
example_var:
  description: Configure Proxy Access to the Internet
  type: number

Then Rougail will expect a int or a float as a value for the example_var variable. In our firefox use case, the real type of the proxy_mode variable will be now set as a choice type:

Defining a choice type

A choice type variable is a variable where the content is constrained by a list

The real firefox/proxy.yml Rougail dictionnary file with a choice type

---
proxy_mode:
  description: Configure Proxy Access to the Internet
  type: choice
  choices:
    - No proxy
    - Auto-detect proxy settings for this network
    - Use system proxy settings
    - Manual proxy configuration
    - Automatic proxy configuration URL
  default: No proxy

Then if we run the Rougail CLI

 rougail -v 1.1 -m firefox/

We will have an output like this:

╭────────────────────────── Caption ──────────────────────────╮
│ Variable                           Default value            │
│ Undocumented variable              Modified value           │
│ Undocumented but modified variable (Original default value) │
│ Unmodifiable variable                                       │
╰─────────────────────────────────────────────────────────────╯
Variables:
┗━━ 📓 proxy_mode: No proxy

The proxy_mode variable here, implicitely requires a value. It is a mandatory variable.

As we set the proxy_mode variable as No proxy by default, we actually have specified a value, and the value appears in yellow, which means : “set by default”.

Container type

We say that the proxy_mode variable is constrained (by the choice type).

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

choice type: The proxy_mode setting is “choice” (type: choice) means that there is a list of available values that can be selected.

Key points progress

Indeed, in the Firefox configuration, it is possible to define several configuration modes, from no proxy at all (no proxy) to a kind of automatic configuration mode from a file (set up proxy configuration from a file).

Keywords

structure file: structure description file
variable: an option’s name which has a value
a variable’s description
a variable’s type
a variable’s default value
the integrator and operator roles
a mandatory value
a choice type

Progress

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

Structure description file

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

---
proxy_mode:
  description: Configure Proxy Access to the Internet
  type: choice
  choices:
    - No proxy
    - Auto-detect proxy settings for this network
    - Use system proxy settings
    - Manual proxy configuration
    - Automatic proxy configuration URL
  default: No proxy