337 lines
11 KiB
ReStructuredText
337 lines
11 KiB
ReStructuredText
Preliminaries
|
||
================
|
||
|
||
.. objectives:: Objectives
|
||
|
||
We will learn how to:
|
||
|
||
- create a Rougail :term:`structure description file <dictionary>`
|
||
- define a Rougail :term:`structure description file <dictionary>` format version
|
||
- define a Rougail :term:`variable` and set its :term:`value`
|
||
|
||
.. prerequisites:: Prerequisites
|
||
|
||
We assume that Rougail's library is :ref:`already installed <installation>` on your computer (or in a virtual environment).
|
||
|
||
.. type-along:: an empty dictionary
|
||
|
||
An empty structure description file
|
||
|
||
.. exercise:: The folder structure
|
||
|
||
Here is the tree structure we want to have::
|
||
|
||
workplace
|
||
├── firefox
|
||
│ ├── dictionary.yml
|
||
|
||
- Let's make a :file:`workplace` directory, with a :file:`firefox` subfolder.
|
||
- First, we wil make a :term:`dictionary`, so let's create a :file:`dictionary.yml` file
|
||
located in the :file:`firefox` subfolder.
|
||
|
||
The dictionary
|
||
----------------
|
||
|
||
This is an empty Rougail dictionnary
|
||
|
||
.. 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: RougailDictionaryEmptyFile
|
||
|
||
..
|
||
---
|
||
version: 1.1
|
||
|
||
.. type-along:: a first variable
|
||
|
||
Let's put a variable in the Rougail :term:`structure description file <dictionary>`
|
||
|
||
|
||
Defining a variable and its default value
|
||
----------------------------------------------
|
||
|
||
This is a first Rougail variable in a Rougail dictionnary.
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||
:language: yaml
|
||
:caption: A Rougail dictionnary file with only one variable
|
||
:name: RougailDictionaryFirstVariableName
|
||
|
||
..
|
||
---
|
||
proxy_mode:
|
||
|
||
- Then we will run this command
|
||
|
||
.. code-block:: text
|
||
:class: terminal
|
||
|
||
rougail -v 1.1 -m firefox/
|
||
|
||
which actually outputs an error:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/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.
|
||
|
||
|
||
Here we juste add a variable's description, which is a good practice.
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/firefox/00-proxy.yml
|
||
:language: yaml
|
||
:caption: A Rougail dictionnary file with a variable and a description
|
||
:name: RougailDictionaryFirstVariableDescription
|
||
|
||
..
|
||
---
|
||
proxy_mode:
|
||
description: Configure Proxy Access to the Internet
|
||
|
||
We need a **default value**.
|
||
|
||
.. glossary::
|
||
|
||
default values
|
||
|
||
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**
|
||
|
||
.. FIXME trouver une url qui corresponde à une valeur par défaut **dans le dictionnaire**
|
||
|
||
.. code-block:: yaml
|
||
:caption: A rougail dictionnary file with a default value for the variable
|
||
:name: RougailDictionaryVariableDefault
|
||
|
||
---
|
||
proxy_mode:
|
||
description: Configure Proxy Access to the Internet
|
||
default: No proxy
|
||
|
||
|
||
.. type-along:: how to set a value
|
||
|
||
A default value has been set, great. Now how do I assign a value to a variable?
|
||
|
||
How to set a value
|
||
----------------------
|
||
|
||
So far we have only talked about the one that writes the structure files. It is called the integrator.
|
||
|
||
.. glossary::
|
||
|
||
integrator
|
||
|
||
An integrator in the Rougail logic is the person who writes the :term:`structure files <dictionaries>`\ .
|
||
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.
|
||
|
||
.. image:: images/integrator.png
|
||
|
||
Now we will talk about the one that defines the values. It is called the operator.
|
||
|
||
.. glossary::
|
||
|
||
operator
|
||
|
||
An operator ih the Rougail logic is the person who gives :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 by the :term:`structure file definition <dictionary>`.
|
||
|
||
.. image:: images/operator.png
|
||
|
||
The operator can use the Rougail CLI interface:
|
||
|
||
.. image:: images/QuestionaryChoice.png
|
||
|
||
.. index:: Rougail CLI
|
||
|
||
The Rougail CLI can output a rather complete view of the dataset:
|
||
|
||
.. image:: images/UserDataOutput.png
|
||
|
||
.. FIXME GWEN j'en suis là
|
||
|
||
Values are mandatory
|
||
-------------------------
|
||
|
||
.. important:: It is the operator's responsibility to set configuration options values.
|
||
|
||
So, if :
|
||
|
||
- there is no default value set in the structure file,
|
||
- no value is set in the value file:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: The :file:`firefox/00-proxy.yaml` Rougail structure file, with no default value set.
|
||
:name: RougailDictionaryNoDefault
|
||
|
||
..
|
||
---
|
||
proxy_mode:
|
||
|
||
Then if we lauch the rougail CLI command:
|
||
|
||
.. code-block:: text
|
||
:class: terminal
|
||
:caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` Rougail dictionnary file
|
||
|
||
rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml
|
||
|
||
It will output an error :
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_010/config/01/output_ro.html
|
||
:class: error-box
|
||
|
||
..
|
||
<pre>🛑 ERRORS
|
||
<span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
|
||
<span style="color: #ff0000">┗━━ </span> - proxy_mode
|
||
</pre>
|
||
|
||
And we can deduce the following result:
|
||
|
||
.. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
|
||
|
||
Rougail waits for the `proxy_mode` configuration option's value to be set.
|
||
|
||
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` Tiramisu's definition.
|
||
|
||
.. glossary::
|
||
|
||
mandatory
|
||
|
||
A variable is mandatory when a value is required, that is, `None` is not an option.
|
||
|
||
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:
|
||
|
||
.. code-block:: yaml
|
||
|
||
---
|
||
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 is a `choice` type:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: The :file:`firefox/00-proxy.yml` Rougail dictionnary file, with a default value set.
|
||
:name: RougailDictionaryChoiceTypeWitheDefault
|
||
|
||
..
|
||
---
|
||
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
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/01/output_ro.html
|
||
:class: output
|
||
|
||
..
|
||
<pre>╭────────────────────────── Caption ──────────────────────────╮
|
||
│ Variable <span style="color: #ffd700">Default value</span> │
|
||
│ <span style="color: #5c5cff">Undocumented variable</span> Modified value │
|
||
│ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
|
||
│ <span style="color: #ffaf00">Unmodifiable variable</span> │
|
||
╰─────────────────────────────────────────────────────────────╯
|
||
Variables:
|
||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: <span style="color: #ffd700">No proxy</span>
|
||
</pre>
|
||
|
||
The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable.
|
||
|
||
It shall have a value, but what if the user *does not* specify any value?
|
||
There is a possibility of setting a default value, wich is set as `No proxy` 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`
|
||
|
||
.. glossary::
|
||
|
||
choice type
|
||
|
||
The `proxy_mode` setting is "choice" (`type: choice`) means that
|
||
there is a list of available values that can be selected.
|
||
|
||
.. note:: 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`).
|
||
|
||
.. keypoints:: Key points progress
|
||
|
||
**Keywords**
|
||
|
||
- :term:`structure file <dictionary>`: 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
|
||
|
||
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_013/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
|
||
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
|
||
|