Getting started ==================== .. objectives:: Objectives We will learn how to: - create a :term:`structure description file ` - add a :term:`structure file format version ` - add a :term:`variable` and set its :term:`value` .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` on your computer. - If you want to follow with this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`, this workshop page corresponds to the tags :tutorial:`v1.1_000 ` to :tutorial:`v1.1_011 ` in the repository: :: git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch v1.1_000 Creating a structure file -------------------------- .. demo:: The folder structure Here is the tree structure we want to have:: rougail-tutorials └── firefox    └── 00-proxy.yml - Let's make a :file:`rougail-tutorials` directory, with a :file:`firefox` subfolder. - First, we will create a :term:`structure file `, so let's create a :file:`00-proxy.yml` file located in the :file:`firefox` subfolder. .. type-along:: An empty structure file This is an empty Rougail :term:`structure description file: ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml :language: yaml :caption: An empty rougail dictionnary file with the version number only :name: RougailStructVersion .. --- version: 1.1 :tutorial:`Download this file from the rougail-tutorials git repository ` Let's add our first variable ------------------------------ .. note:: A variable is defined at a minimum by its name. A :term:`variable` in the :term:`structure description file ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/firefox/00-proxy.yml :language: yaml :caption: A Rougail structure file with only one variable :name: RougailDictionaryFirstVariableName .. --- proxy_mode: :tutorial:`Download this file from the rougail-tutorials git repository ` Let's run the Rougail CLI utility command: .. code-block:: text :class: terminal rougail -m firefox/ we will actually have an error: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/01/output_ro.html :class: error-box .. 🛑 ERRORS ┣━━ The following variables are mandatory but have no value: ┗━━ - proxy_mode Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet. We can therefore deduce the fact that: .. admonition:: Fact Once defined, an option configuration :term:`value` is :term:`mandatory`. That is to say, it is absolutely necessary to assign a value to this variable. Rougail waits for the `proxy_mode` configuration option's value to be set. .. glossary:: mandatory A variable is mandatory when a value is required, that is, `None` is not a possible value. It **must** have a defined value. .. seealso:: To go further, have a look at the :tiramisu:`mandatory option ` according to the definition of Tiramisu. Let's add a variable's description, which is not mandatory but which is a good practice: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_002/firefox/00-proxy.yml :language: yaml :caption: A Rougail dictionnary file with a variable and a description :name: RougailStructFirstVariableDescription .. --- proxy_mode: # Configure Proxy Access to the Internet :tutorial:`Download this file from the rougail-tutorials git repository ` .. type-along:: how to set a value -- the default value We need to set a value to this `proxy_mode` variable. A first way to do it is *to set a value by default*. .. glossary:: default value A default value is a variable value that is predefined, that is, this value is placed right in the structure file. So let's define a variable with a description -- **and a default value** .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml :language: yaml :caption: A rougail dictionnary file with a default value for the variable :name: RougailDictionaryVariableDefault .. --- proxy_mode: No proxy # Configure Proxy Access to the Internet :tutorial:`Download this file from the rougail-tutorials git repository ` .. type-along:: how to set a value -- the assignment A default value has been set, great. Now how do I assign a value to a variable? The different rougail roles and the default values ------------------------------------------------------ So far we have only talked about the one that writes the :term:`structure files `\ . It's *role* is called the integrator's role. .. glossary:: integrator An integrator in the Rougail field is the person who writes the :term:`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. .. glossary:: operator An operator in the Rougail field is the person who assigns :term:`value`\ s to the pre-defined variables, his responsabilities are to set variable values correctly. The user :term:`value`\ s, 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 :term:`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 :term:`user data file`\ s. .. glossary:: 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. 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 :term:`structured datas `\ 's scope. .. important:: If user datas are not set, default values are mandatory, otherwise Rougail will raise an error. .. exercise:: Folder structure update Now we add a :file:`config/config.yaml` file in our project:: rougail-tutorials ├── firefox │   ├── 00-proxy.yml └── config └── config.yaml .. type-along:: 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, it's up to the operator to do the job in the `config.yaml` file: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/config.yaml :language: yaml :caption: A Rougail user datas file :file:`config/config.yaml`, with a default value set. :name: RougailConfigDefaultValue .. --- proxy_mode: No proxy :tutorial:`Download this file from the rougail-tutorials git repository ` With the rougail CLI the operator has to add the `-u file -ff config/config.yaml` options: .. code-block:: text :class: terminal :caption: A rougail Command Line Utility call with the :file:`config/config.yaml` Rougail user datas file rougail -m firefox -u yaml -ff config/02/config.yaml which gives us this output: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/output_ro.html :class: output .. 
╭──────── Caption ────────╮
    │ Variable Modified value │
    ╰─────────────────────────╯
    Variables:
    ┗━━ 📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yaml"
.. admonition:: Important fact - the integrator works on structure files - the operator works on user data files 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. .. type-along:: Defining a choice type In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type: .. seealso:: Have a look at the definition of the :term:`choice type variable ` .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml :linenos: :language: yaml :caption: The real :file:`firefox/proxy.yml` Rougail dictionnary file with a choice type :name: RougailDictionaryChoiceType .. --- 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 - Let's run the Rougail CLI .. code-block:: text :class: terminal rougail -v 1.1 -m firefox/ We have an output like this one: .. raw:: html :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_004/config/01/output_ro.html :class: output .. 
╭────────────────────────── 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 :term:`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". The constraints that come with the `choice` 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` .. keypoints:: 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** - :term:`structure file `: structure description file - :term:`variable`: an option's name which has a value - a variable's description - a variable's type - a variable's default value - the :term:`integrator` and :term:`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** .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml :linenos: :language: yaml :caption: A Rougail dictionnary file with a variable named `proxy_mode`, with a default value. .. .. raw:: text --- 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