preliminary file in the tutorial ok
This commit is contained in:
gwen
parent
b4efbf1d71
commit
cc54cf675f
1 changed files with 82 additions and 74 deletions
|
|
@ -23,7 +23,7 @@ Preliminaries
|
|||
|
||||
workplace
|
||||
├── firefox
|
||||
│ ├── dictionary.yml
|
||||
│ └── 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
|
||||
|
|
@ -62,14 +62,14 @@ This is a first Rougail variable in a Rougail dictionnary.
|
|||
---
|
||||
proxy_mode:
|
||||
|
||||
- Then we will run this command
|
||||
- Then if we run the Rougail CLI utility command
|
||||
|
||||
.. code-block:: text
|
||||
:class: terminal
|
||||
|
||||
rougail -v 1.1 -m firefox/
|
||||
|
||||
which actually outputs an error:
|
||||
we will actually have an error:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/01/output_ro.html
|
||||
|
|
@ -82,8 +82,21 @@ which actually outputs an error:
|
|||
|
||||
Because this variable is :term:`mandatory` and needs to be set **but** there's no value yet.
|
||||
|
||||
So we can therefore see this consequence:
|
||||
|
||||
Here we juste add a variable's description, which is a good practice.
|
||||
.. 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.
|
||||
|
||||
Then we just 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
|
||||
|
|
@ -137,8 +150,6 @@ So far we have only talked about the one that writes the structure files. It is
|
|||
(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::
|
||||
|
|
@ -150,73 +161,57 @@ Now we will talk about the one that defines the values. It is called the operato
|
|||
|
||||
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.
|
||||
It is the operator's responsibility to set configuration options values.
|
||||
He does not work with the dictionary (the structure file),
|
||||
he is responsible for other files, called the configuration files.
|
||||
|
||||
.. glossary::
|
||||
|
||||
mandatory
|
||||
configuration file
|
||||
|
||||
A configuration file is a file where only the values of the configuration options are assigned. The structure, the consistency of the variables between them is not the responsibility of these files (but of the dictionary files).
|
||||
|
||||
A variable is mandatory when a value is required, that is, `None` is not an option.
|
||||
.. exercise:: Folder structure update
|
||||
|
||||
Now we add a :file:`config/config.yml` file in our project::
|
||||
|
||||
workplace
|
||||
├── firefox
|
||||
│ ├── dictionary.yml
|
||||
└── config
|
||||
└── config.yml
|
||||
|
||||
.. type-along:: how to set a default value in a configuration file
|
||||
|
||||
So for example if the integrator has not set any default value in his structure file,
|
||||
the operator can do it like this:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_011/config/02/config.yaml
|
||||
:language: yaml
|
||||
:caption: The Rougail configuration file :file:`config/config.yml`, with a default value set.
|
||||
:name: RougailConfigDefaultValue
|
||||
|
||||
..
|
||||
---
|
||||
proxy_mode: No proxy
|
||||
|
||||
With the rougail CLI the operator has to add the `-u file -ff config/config.yml` options:
|
||||
|
||||
.. code-block:: text
|
||||
:class: terminal
|
||||
:caption: A rougail Command Line Utility call with the :file:`config/config.yml` Rougail configuration file
|
||||
|
||||
rougail -v 1.1 -m firefox -u file -ff config/01/config.yaml
|
||||
|
||||
Let us clarify this essential point:
|
||||
|
||||
- the integrator works on dictionaries
|
||||
- the operator works on configuration files
|
||||
|
||||
.. note:: 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.
|
||||
|
||||
Variable's type
|
||||
-----------------
|
||||
|
|
@ -233,13 +228,18 @@ If the operator sets an option value for example with the `number` type, like th
|
|||
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:
|
||||
In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type:
|
||||
|
||||
.. type-along:: Defining a choice type
|
||||
|
||||
A choice type variable is a variable where the content is constrained by a list
|
||||
|
||||
|
||||
.. 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
|
||||
:caption: The real :file:`firefox/proxy.yml` Rougail dictionnary file with a choice type
|
||||
:name: RougailDictionaryChoiceType
|
||||
|
||||
..
|
||||
---
|
||||
|
|
@ -254,6 +254,15 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice
|
|||
- Automatic proxy configuration URL
|
||||
default: No proxy
|
||||
|
||||
- Then if we run the Rougail CLI
|
||||
|
||||
.. code-block:: text
|
||||
:class: terminal
|
||||
|
||||
rougail -v 1.1 -m firefox/
|
||||
|
||||
We will have an output like this:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_013/config/01/output_ro.html
|
||||
:class: output
|
||||
|
|
@ -271,8 +280,7 @@ In our firefox use case, the real type of the `proxy_mode` variable is a `choice
|
|||
|
||||
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.
|
||||
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".
|
||||
|
||||
Container type
|
||||
-----------------
|
||||
|
|
@ -294,11 +302,11 @@ We have the list of the possible (authorized) values:
|
|||
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
|
||||
|
||||
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 <dictionary>`: structure description file
|
||||
|
|
|
|||
Loading…
Reference in a new issue