preliminary -> reviewed
This commit is contained in:
gwen
parent
b22c1817b9
commit
d9ac902740
5 changed files with 68 additions and 68 deletions
|
|
@ -9,12 +9,12 @@ A variable with possible values
|
|||
|
||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||
|
||||
- It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the Rougail-tutorials git repository.
|
||||
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the `rougail-tutorials` git repository.
|
||||
Each tag corresponds to a stage of progress in the tutorial.
|
||||
Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
|
||||
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <src/branch/1.1>`,
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
|
||||
this workshop page corresponds to the tag :tutorial:`v1.1_010 <src/tag/v1.1_010>` in the repository:
|
||||
|
||||
::
|
||||
|
|
@ -30,7 +30,7 @@ In the firefox browser, the proxy mode can be set by this way:
|
|||
.. image:: images/firefox_02.png
|
||||
|
||||
A list of possible values for the `proxy_mode` variable is proposed.
|
||||
With rougail there is the possibility of defining a list of available values
|
||||
With Rougail there is the possibility of defining a list of available values
|
||||
with the `choice` variable's parameter:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||||
|
|
@ -89,7 +89,7 @@ by the possibilities of the `choice` parameter.
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_010/config/03/config.yml>`
|
||||
|
||||
If we run the rougail CLI with this user datas:
|
||||
If we run the Rougail CLI with this user datas:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/03/cmd_ro.txt
|
||||
|
|
@ -115,7 +115,7 @@ We have this output:
|
|||
|
||||
As we set the `proxy_mode` variable from a user data file,
|
||||
we now have specified a value which is **not** a default value, and
|
||||
the output of the rougail CLI explicitly shows that a user data value has been entered,
|
||||
the output of the Rougail CLI explicitly shows that a user data value has been entered,
|
||||
it shows which user data file this value comes from, and it also indicates
|
||||
what the default value is for information purposes.
|
||||
|
||||
|
|
@ -142,7 +142,7 @@ We have the list of the possible (authorized) values:
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_010/config/04/config.yml>`
|
||||
|
||||
If we run the rougail CLI with this user datas:
|
||||
If we run the Rougail CLI with this user datas:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/cmd_ro.txt
|
||||
|
|
@ -160,12 +160,12 @@ We have this output:
|
|||
We can see here that Rougail warns us about an invalid value that is not in the available choices,
|
||||
that's why this value will not be used and it falls back to the original default value.
|
||||
|
||||
But maybe this is not the behavior you need. Maybe you need to stop everything if rougail detects that
|
||||
But maybe this is not the behavior you need. Maybe you need to stop everything if Rougail detects that
|
||||
something is going wrong, maybe you need some kind of a strict mode.
|
||||
|
||||
Indeed, this warning can be transformed into an error.
|
||||
|
||||
If we run the rougail CLI with this `--cli.invalid_user_datas_error` parameter:
|
||||
If we run the Rougail CLI with this `--cli.invalid_user_datas_error` parameter:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/config/04/cmd_invalid.txt
|
||||
|
|
|
|||
|
|
@ -10,12 +10,12 @@ Some suitable types
|
|||
|
||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||
|
||||
- It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the Rougail-tutorials git repository.
|
||||
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the `rougail-tutorials` git repository.
|
||||
Each tag corresponds to a stage of progress in the tutorial.
|
||||
Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
|
||||
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <src/branch/1.1>`,
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
|
||||
this workshop page corresponds to the tags :tutorial:`v1.1_030 <src/tag/v1.1_030>` to :tutorial:`v1.1_033 <src/tag/v1.1_033>`
|
||||
in the repository.
|
||||
|
||||
|
|
@ -69,7 +69,7 @@ Well, with a correct user data like this one,
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_030/config/01/config.yml>`
|
||||
|
||||
if we launch the rougail CLI on it:
|
||||
if we launch the Rougail CLI on it:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/01/cmd_ro.txt
|
||||
|
|
@ -117,7 +117,7 @@ Let's have a look at an example of user setting that does not fit the
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_030/config/03/config.yml>`
|
||||
|
||||
The value is obviously not a domain name, then when we will launch the rougail CLI:
|
||||
The value is obviously not a domain name, then when we will launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/03/cmd_invalid.txt
|
||||
|
|
@ -153,7 +153,7 @@ we then have this output:
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_030/config/02/config.yml>`
|
||||
|
||||
With a value that *is not a domain name* but an IP address, then when we will launch the rougail CLI
|
||||
With a value that *is not a domain name* but an IP address, then when we will launch the Rougail CLI
|
||||
we will see a little problem:
|
||||
|
||||
.. raw:: html
|
||||
|
|
@ -245,7 +245,7 @@ Now we will test with an IP address as the value for our `address` variable.
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_031/config/02/config.yml>`
|
||||
|
||||
if we launch the rougail CLI on it:
|
||||
if we launch the Rougail CLI on it:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_031/config/02/cmd_ro.txt
|
||||
|
|
@ -305,7 +305,7 @@ Let's assing a value to this port:
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_032/config/02/config.yml>`
|
||||
|
||||
If we launch the rougail CLI:
|
||||
If we launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:class: terminal
|
||||
|
|
@ -350,7 +350,7 @@ Now let's assign a value that is outside the allowed ports:
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_032/config/03/config.yml>`
|
||||
|
||||
Again, we launch the rougail CLI:
|
||||
Again, we launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:class: terminal
|
||||
|
|
@ -425,7 +425,7 @@ Let's switch this boolean variable to a `false` value:
|
|||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_033/config/02/config.yml>`
|
||||
|
||||
|
||||
Let's run the rougail CLI:
|
||||
Let's run the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:class: terminal
|
||||
|
|
|
|||
|
|
@ -13,12 +13,12 @@ Group variables inside families
|
|||
|
||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||
|
||||
- It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the Rougail-tutorials git repository.
|
||||
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the `rougail-tutorials` git repository.
|
||||
Each tag corresponds to a stage of progress in the tutorial.
|
||||
Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
|
||||
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <src/branch/1.1>`,
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
|
||||
this workshop page corresponds to the tags :tutorial:`v1.1_020 <src/tag/v1.1_020>` to :tutorial:`v1.1_022 <src/tag/v1.1_022>`
|
||||
in the repository.
|
||||
|
||||
|
|
@ -143,7 +143,6 @@ Putting a variable inside of a family or a sub family
|
|||
|
||||
git switch --detach v1.1_022
|
||||
|
||||
|
||||
We are going to put a variable inside of a family or a sub family
|
||||
|
||||
Let's create a variable in the `http_proxy` family.
|
||||
|
|
@ -247,7 +246,7 @@ Everything is OK:
|
|||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 HTTP address: example.net ◀ loaded from the YAML file "config/02/config.yml"
|
||||
</pre>
|
||||
|
||||
Let's recap about the user datas. We can see in this rougail CLI output that:
|
||||
Let's recap about the user datas. We can see in this Rougail CLI output that:
|
||||
|
||||
- the `proxy_mode` value is set by default by the :term:`integrator`
|
||||
- the `address` value is has been set by an :term:`operator`
|
||||
|
|
|
|||
|
|
@ -13,12 +13,12 @@ Getting started
|
|||
|
||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||
|
||||
- It is possible to retrieve the current state of the various rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the Rougail-tutorials git repository.
|
||||
- It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
|
||||
by checking out the corresponding tag of the `rougail-tutorials` git repository.
|
||||
Each tag corresponds to a stage of progress in the tutorial.
|
||||
Of course, you can also decide to copy/paste or download the tutorial files contents while following the tutorial steps.
|
||||
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <src/branch/1.1>`,
|
||||
If you want to follow this tutorial with the help of the corresponding :tutorial:`rougail-tutorials git repository <src/branch/1.1>`,
|
||||
this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000>` to :tutorial:`v1.1_003 <src/tag/v1.1_003>`
|
||||
in the repository:
|
||||
|
||||
|
|
@ -46,7 +46,7 @@ This is an empty Rougail :term:`structure description file: <structure file>`
|
|||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_000/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: An empty rougail structure file with only the YAML header and the version number
|
||||
:caption: An empty Rougail structure file with only the YAML header and the version number
|
||||
:name: RougailStructVersion
|
||||
|
||||
..
|
||||
|
|
@ -55,7 +55,7 @@ This is an empty Rougail :term:`structure description file: <structure file>`
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_000/firefox/00-proxy.yml>`
|
||||
|
||||
This `version` specification is just the rougail YAML's format version specification.
|
||||
This `version` specification is just the Rougail YAML's format version specification.
|
||||
By now, we have an empty structure file with the format specification in it.
|
||||
|
||||
Let's add our first variable
|
||||
|
|
@ -127,7 +127,7 @@ Rougail expects the `proxy_mode` configuration option's value to be set.
|
|||
|
||||
Describe the variable
|
||||
-------------------------
|
||||
|
||||
|
||||
Let's add a variable's description, which is not mandatory but which is usually a good practice.
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
|
@ -185,7 +185,7 @@ Let's add a default value to this `proxy_mode` variable.
|
|||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/firefox/00-proxy.yml
|
||||
:language: yaml
|
||||
:caption: A rougail structure file with a default value for the variable
|
||||
:caption: A Rougail structure file with a default value for the variable
|
||||
:name: RougailDictionaryVariableDefault
|
||||
|
||||
..
|
||||
|
|
@ -209,44 +209,24 @@ The `proxy_mode` variable requires a value, that's why we have set a `No proxy`
|
|||
</pre>
|
||||
|
||||
As we have set the `proxy_mode`'s value as `No proxy` by default,
|
||||
The chosen value is indicated in the rougail's CLI output as the default choice.
|
||||
The chosen value is indicated in the Rougail's CLI output as the default choice.
|
||||
|
||||
.. glossary::
|
||||
- here is the short-hand default setting and description:
|
||||
|
||||
short-hand notation
|
||||
|
||||
A short-hand notation in rougail is the ability to define a variable in
|
||||
a short-hand way, there are several example:
|
||||
.. code-block:: yaml
|
||||
|
||||
- a default value:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
my_var: true
|
||||
|
||||
instead of:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
my_var:
|
||||
default: true
|
||||
proxy_mode: No proxy # Configure Proxy Access to the Internet
|
||||
|
||||
- a quick description:
|
||||
- here is the verbose way:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
proxy_mode: # Configure Proxy Access to the Internet
|
||||
|
||||
instead of:
|
||||
.. code-block:: yaml
|
||||
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
proxy_mode:
|
||||
description: Configure Proxy Access to the Internet
|
||||
proxy_mode:
|
||||
default: No proxy
|
||||
description: Configure Proxy Access to the Internet
|
||||
|
||||
There are some other short-hand ways with rougail that you may encounter
|
||||
as you read the rougail's documentation and tutorial.
|
||||
There are some other :term:`short-hand ways <short-hand notation>` with Rougail that you may encounter
|
||||
as you read the Rougail's documentation and tutorial.
|
||||
|
||||
.. admonition:: how to set a value -- the assignment
|
||||
|
||||
|
|
@ -254,9 +234,9 @@ The chosen value is indicated in the rougail's CLI output as the default choice.
|
|||
|
||||
Now then how can I assign a normal value to a variable?
|
||||
|
||||
.. type-along:: The different rougail roles and setting a variable's value
|
||||
.. type-along:: The different Rougail roles and setting a variable's value
|
||||
|
||||
So far we have only talked about the guy that writes the :term:`structure files <structure file>`\ .
|
||||
So far we have only talked about the actor that writes the :term:`structure files <structure file>`\ .
|
||||
The one who writes the structure file plays the *role* of the *integrator*.
|
||||
|
||||
.. glossary::
|
||||
|
|
@ -297,7 +277,8 @@ he is responsible of other files called the :term:`user data files <user data fi
|
|||
The consistency field is outside of the user datas scope.
|
||||
The consistency is handled in the :term:`structured datas <structured data>`\ 's scope.
|
||||
|
||||
.. important:: If user datas are not set, default values are mandatory, otherwise Rougail will raise an error.
|
||||
.. important:: For now, we don't know how to disable the default `mandatory` settings,
|
||||
so if neither a default value nor a user value are set for a given variable, Rougail will raise an error.
|
||||
|
||||
.. exercise:: Folder structure update
|
||||
|
||||
|
|
@ -325,7 +306,7 @@ it's up to the operator to do the job in the `config.yml` file:
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/config/02/config.yml>`
|
||||
|
||||
The operator needs to add the `-u yaml -yf config/config.yml` options to the rougail CLI:
|
||||
The operator needs to add the `-u yaml -yf config/config.yml` options to the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/cmd_ro.txt
|
||||
|
|
@ -348,13 +329,13 @@ which gives us this output:
|
|||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yml"
|
||||
</pre>
|
||||
|
||||
Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see in the rougail CLI output that the value
|
||||
Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see in the Rougail CLI output that the value
|
||||
comes from the :file:`config/02/config.yml` user data file. From now on this `proxy_mode` variable's value
|
||||
is a user data value and not a default value (even if it's actually the same value).
|
||||
|
||||
.. type-along:: structure values and user data values
|
||||
|
||||
We can see with the rougail CLI utility where the values come from.
|
||||
We can see with the Rougail CLI utility where the values come from.
|
||||
It can come from an integrator's setting or from an operator's setting.
|
||||
|
||||
.. admonition:: Reminder
|
||||
|
|
|
|||
|
|
@ -73,6 +73,26 @@ Shorthand declaration
|
|||
|
||||
Shorthand declaration is a way to declare a variable in a single line. But you can only define variable name, description, multi or default value.
|
||||
|
||||
.. glossary::
|
||||
|
||||
short-hand notation
|
||||
|
||||
A short-hand notation in Rougail is the ability to define a variable in
|
||||
a short-hand way, there are several example:
|
||||
|
||||
- a default value:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
my_var: true
|
||||
|
||||
instead of:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
my_var:
|
||||
default: true
|
||||
|
||||
To create a variable, just add a key with it's name and default value as value.
|
||||
Be careful not to declare any other attributes.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue