Getting started

Objectives

We will learn how to:

create a structure description file
add a structure file format version in the structure file
add a variable in the structure file and set its default value

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_000 to v1.1_003 in the repository:

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

Creating a structure file

The folder structure

Here is the tree structure we want to have:

rougail-tutorials
└── firefox
    └── 00-proxy.yml

Let’s make a rougail-tutorials directory, with a firefox subfolder.
First, we will create a structure file, so let’s create a 00-proxy.yml file located in the firefox subfolder.

This is an empty Rougail structure description file:

An empty Rougail structure file with only the YAML header and the version number

%YAML 1.2
---
version: 1.1
...

Download this file from the rougail-tutorials git repository

This version specification is just the Rougail YAML’s format version specification. By now, we have an empty structure file with the format specification in it.

Let’s add our first variable

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

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

git switch --detach v1.1_001

A variable is defined at a minimum by its name.
A variable lives in the structure description file.

Here we define a variable named proxy_mode:

A Rougail structure file with only one variable in it

%YAML 1.2
---
version: 1.1

proxy_mode:
...

Download this file from the rougail-tutorials git repository

Let’s run the Rougail CLI utility command in a terminal:

 rougail -m firefox/

Well, we notice that we have an error:

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

It’s because this first defined variable is mandatory and needs to have a value set but there’s no value yet.

We can therefore deduce the fact that:

Fact

Once defined, an option configuration value is mandatory. That is to say, it is absolutely necessary to assign a value to this variable.

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

mandatory: A variable is mandatory when a value is required, that is, None is not a possible value. It must have a defined value.

Describe the variable

Let’s add a variable’s description, which is not mandatory but which is usually a good practice.

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

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

git switch --detach v1.1_002

A Rougail structure file with a variable and a description

%YAML 1.2
---
version: 1.1

proxy_mode:  # Configure Proxy Access to the Internet
...

Download this file from the rougail-tutorials git repository

You have two way to define a variable’s description:

the verbose way:

proxy_mode:
  description: Configure Proxy Access to the Internet

or a short-hand way, setting the description using the “#” YAML comment notation:
```
proxy_mode:  # Configure Proxy Access to the Internet
```

Set a default value

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

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

git switch --detach v1.1_003

We will learn different ways to set a value, the first way is setting a default value.

default value: A default value is a variable value that is predefined, that’s why this value is placed right in the structure file.

Let’s add a default value to this proxy_mode variable.

A Rougail structure file with a default value for the variable

%YAML 1.2
---
version: 1.1

proxy_mode: No proxy  # Configure Proxy Access to the Internet
...

Download this file from the rougail-tutorials git repository

The proxy_mode variable requires a value, that’s why we have set a No proxy default value.

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

As we have set the proxy_mode’s value as No proxy by default, The chosen value is indicated in the Rougail’s CLI output as the default choice.

here is the short-hand default setting and description:

proxy_mode: No proxy # Configure Proxy Access to the Internet

here is the verbose way:

proxy_mode:
  default: No proxy
  description: Configure Proxy Access to the Internet

There are some other short-hand ways with Rougail that you may encounter as you read the Rougail’s documentation and tutorial.

how to set a value – the assignment

A default value has been set, great. This raises a question about what a normal value is.

Now then how can I assign a normal value to a variable?

The different Rougail roles and setting a variable’s value

So far we have only talked about the actor that writes the structure files. The one who writes the structure file plays the role of the integrator.

integrator: An integrator in the Rougail field is the person who writes the structure files. He has the responsibility of the integration process, that is, he 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 organisation of the variables between them.

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

operator

An operator in the Rougail field is the person who assigns 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.

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

user datas

User datas, as opposed to structured datas, are datas that only concern the assignment of values and not the consistency of the variables between them.

The variable’s values are also called user values.

The consistency field is outside of the user datas scope. The consistency is handled in the structured datas‘s scope.

Important

For now, we don’t know how to disable the default mandatory settings, so if neither a default value nor a user value are set for a given variable, Rougail will raise an error.

Folder structure update

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

rougail-tutorials
├── firefox
│   ├── 00-proxy.yml
└── config
    └── config.yml

how to set a user data value

If the integrator has not set any default value in his structure file, it’s up to the operator to do the job in the config.yml file:

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

---
proxy_mode: No proxy

Download this file from the rougail-tutorials git repository

The operator needs to add the -u yaml -yf config/config.yml options to the Rougail CLI:

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

which gives us this output:

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

Now the proxy_mode’s new No proxy value is the same as the default value but we see in the Rougail CLI output that the value comes from the config/02/config.yml user data file. From now on this proxy_mode variable’s value is a user data value and not a default value (even if it’s actually the same value).

structure values and user data values

We can see with the Rougail CLI utility where the values come from. It can come from an integrator’s setting or from an operator’s setting.

Reminder

the integrator works on structure files, he can define default value for variables
the operator works on user data files, he only can set user data values for variables

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.

user data files are where the user values live

We need to set the values in separate files, called user data files.

user data file

A user data file is a file where only user datas are set.

A user file is a file where there are only user datas in it, users can set values, called user values – that is variable’s values that have been set by an operator.