206 lines
7 KiB
ReStructuredText
206 lines
7 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
|
|
-------------------------
|
|
|
|
.. 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:`struct/config.yaml` rougail structure file, with no default value set.
|
|
:name: RougailDictionaryNoDefault
|
|
|
|
..
|
|
---
|
|
proxy_mode:
|
|
|
|
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_010/config/01/output_ro.html
|
|
|
|
..
|
|
<pre>🛑 ERRORS
|
|
<span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
|
|
<span style="color: #ff0000">┗━━ </span> - proxy_mode
|
|
</pre>
|
|
|
|
.. important:: Once defined, an option configuration :term:`value` is :term:`mandatory`.
|
|
|
|
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 inference
|
|
-----------------
|
|
|
|
By default, 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/commit/v1.1_013/config/05/config.yaml
|
|
:linenos:
|
|
:language: yaml
|
|
:caption: The :file:`config/05/config.yaml` 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
|
|
|
|
..
|
|
<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>
|
|
|
|
|
|
.. 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
|
|
|
|
To sum up, we have arrived at this point in writing the structure file:
|
|
|
|
**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
|
|
|