structure files
This commit is contained in:
gwen
parent
fbc0744f61
commit
5dc7d2b630
2 changed files with 61 additions and 47 deletions
|
|
@ -30,15 +30,16 @@ What is a consistency handling system ?
|
|||
Here is the :xref:`tiramisu library`.
|
||||
|
||||
In the Rougail scope, we call it :term:`variable`\ s and :term:`families`.
|
||||
In Rougail, the families and variables are located in the :term:`dictionaries`.
|
||||
In Rougail, the families and variables are located in the :term:`structure files <dictionaries>`.
|
||||
|
||||
And this is what we are going to explain in this page.
|
||||
|
||||
The dictionaries
|
||||
The structure files
|
||||
---------------------
|
||||
|
||||
.. glossary::
|
||||
|
||||
structure file
|
||||
dictionary
|
||||
dictionaries
|
||||
|
||||
|
|
@ -49,6 +50,8 @@ The dictionaries
|
|||
Rougail reads all the dictionaries and loads them into a single object
|
||||
that handles the variables consistency.
|
||||
|
||||
A dictionary file is a structure file, we call a dictionary a structure file.
|
||||
|
||||
.. image:: images/schema.png
|
||||
|
||||
The main advantage is that declaring variables and writing consistency is as simple
|
||||
|
|
@ -57,10 +60,10 @@ It simplifies a lot of things.
|
|||
|
||||
And rather than writing :term:`Tiramisu` code, we can declare variables and describe the relationships between variables in a declarative mode (that is, in a YAML file).
|
||||
|
||||
Once the dictionaries are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool.
|
||||
Once the structure files are loaded by Rougail, we find all the power of the :term:`Tiramisu` configuration management tool.
|
||||
|
||||
The YAML dictionaries format
|
||||
-----------------------------
|
||||
The YAML structure files format
|
||||
------------------------------------
|
||||
|
||||
Before getting started with Rougail we need to learn the specifics of the YAML dictionaries file format (as well as some templating concepts).
|
||||
|
||||
|
|
@ -95,7 +98,7 @@ You can see that there is just a `version` specification.
|
|||
The variables
|
||||
-----------------
|
||||
|
||||
Here is a :term:`dictionary` example with a variable into it:
|
||||
Here is a :term:`structure file <dictionary>` example with a variable into it:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml
|
||||
:linenos:
|
||||
|
|
@ -105,7 +108,7 @@ Here is a :term:`dictionary` example with a variable into it:
|
|||
|
||||
:download:`source file <https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/firefox/00-proxy.yml>`
|
||||
|
||||
Here we declare a **variable** named `proxy_mode` without a :term:`default value`.
|
||||
Here we declare a **variable** named `proxy_mode` without a default value.
|
||||
A variable can be defined with no default value at all.
|
||||
|
||||
Here is the same variable with a description label:
|
||||
|
|
|
|||
|
|
@ -5,7 +5,7 @@ Preliminaries
|
|||
|
||||
We will learn how to:
|
||||
|
||||
- create a Rougail :term:`dictionary` (the structure description file)
|
||||
- create a Rougail :term:`structure description file <dictionary>`
|
||||
- define a Rougail format version
|
||||
- define a Rougail :term:`variable` and set its :term:`value`
|
||||
|
||||
|
|
@ -13,7 +13,7 @@ Preliminaries
|
|||
|
||||
We already learned in other workshops how to:
|
||||
|
||||
- define a Rougail :term:`dictionary`
|
||||
- define a Rougail :term:`structure description file <dictionary>`
|
||||
|
||||
:ref:`Here is an empty Rougail dictionnary <RougailDictionaryEmptyFile>`
|
||||
|
||||
|
|
@ -29,41 +29,6 @@ Preliminaries
|
|||
|
||||
:ref:`Here is a Rougail variable with a default value <RougailDictionaryFirstVariableDefault>`
|
||||
|
||||
Values are mandatory
|
||||
-------------------------
|
||||
|
||||
If, like in this situation:
|
||||
|
||||
.. 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
|
||||
|
||||
<pre>
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_003/config/01/output_ro.html
|
||||
|
||||
.. raw:: html
|
||||
|
||||
</pre>
|
||||
|
||||
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.
|
||||
|
||||
|
||||
The integrator role
|
||||
----------------------
|
||||
|
|
@ -72,7 +37,7 @@ The integrator role
|
|||
|
||||
integrator
|
||||
|
||||
An integrator in the Rougail logic is the person who writes the dictionaries.
|
||||
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**
|
||||
|
|
@ -94,7 +59,7 @@ The operator role
|
|||
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 dictionary structure.
|
||||
by the :term:`structure file <dictionary>`.
|
||||
|
||||
.. image:: images/operator.png
|
||||
|
||||
|
|
@ -108,11 +73,57 @@ 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:`dictionary`: structure description file
|
||||
- :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
|
||||
|
|
|
|||
Loading…
Reference in a new issue