143 lines
4.6 KiB
ReStructuredText
143 lines
4.6 KiB
ReStructuredText
Preliminaries
|
|
================
|
|
|
|
.. objectives:: Objectives
|
|
|
|
We will learn how to:
|
|
|
|
- create a Rougail :term:`structure description file <dictionary>`
|
|
- define a Rougail format version
|
|
- define a Rougail :term:`variable` and set its :term:`value`
|
|
|
|
.. type-along:: Reminders
|
|
|
|
We already learned in other workshops how to:
|
|
|
|
- define a Rougail :term:`structure description file <dictionary>`
|
|
|
|
:ref:`Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`
|
|
|
|
- define a variable and its default value
|
|
|
|
:ref:`Here is a first Rougail variable in a Rougail dictionnary <RougailDictionaryFirstVariable>`
|
|
|
|
- define a variable with a description
|
|
|
|
:ref:`Here is a Rougail variable with a description <RougailDictionaryFirstVariableDescription>`
|
|
|
|
- define a variable with a description and a default value
|
|
|
|
:ref:`Here is a Rougail variable with a default value <RougailDictionaryFirstVariableDefault>`
|
|
|
|
|
|
The integrator role
|
|
----------------------
|
|
|
|
.. 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
|
|
|
|
.. important:: Note that there is a strong consistency, it means that the validation is done across
|
|
the entire structure, not only with a schema (type) validation system.
|
|
|
|
The operator role
|
|
---------------------
|
|
|
|
.. 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 validated
|
|
by the :term:`structure file <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
|
|
|
|
Values are mandatory
|
|
-------------------------
|
|
|
|
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_004/firefox/00-proxy.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The :file:`config/01/config.yaml` rougail dictionnary file, with no default value set.
|
|
:name: RougailDictionaryNoDefaultUseCase
|
|
|
|
In this situation there are no default value set. The rougail CLI will output an error :
|
|
|
|
.. code-block:: shell
|
|
:caption: A rougail Command Line Utility call with the :file:`config/01/config.yaml` rougail dictionnary file
|
|
|
|
foo@bar:~$ rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml
|
|
|
|
.. raw:: html
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/01/output_ro.html
|
|
|
|
|
|
Rougail waits for a value to be set, that's why.
|
|
|
|
.. seealso:: To go further, have a look at the :tiramisu:`mandatory option <glossary.html#term-mandatory-option>` Tiramisu's definition.
|
|
|
|
Type inférence
|
|
-----------------
|
|
|
|
By default, rougail infers a `string` type.
|
|
If the operator sets an option value with the `string` type, like this:
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/05/config.yaml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The :file:`config/05/config.yaml` rougail dictionnary file, with no default value set.
|
|
:name: RougailDictionaryNoDefaultUseCaseIntOptionValue
|
|
|
|
.. raw:: html
|
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/05/output_ro.html
|
|
|
|
.. 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 default value
|
|
- the :term:`integrator` and :term:`operator` roles
|
|
- a mandatory option value
|
|
|
|
|
|
To sum up, we have arrived here
|
|
|
|
**Structure definition file**
|
|
|
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_005/firefox/00-proxy.yml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: A rougail dictionnary file with a variable named `proxy_mode`, with a default value.
|
|
:name: RougailDictionaryDefaultVariabletUseCase
|
|
|