separation of the choice
This commit is contained in:
gwen
parent
4da1408c7f
commit
7fc56b2429
4 changed files with 164 additions and 149 deletions
141
docs/tutorial/choice.rst
Normal file
141
docs/tutorial/choice.rst
Normal file
|
|
@ -0,0 +1,141 @@
|
||||||
|
A variable with a list of possible values
|
||||||
|
=========================================
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
.. type-along:: Defining a choice type
|
||||||
|
|
||||||
|
In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type:
|
||||||
|
|
||||||
|
.. seealso:: Have a look at the definition of the :term:`choice type variable <choice type>`
|
||||||
|
|
||||||
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
||||||
|
:linenos:
|
||||||
|
:language: yaml
|
||||||
|
:caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type
|
||||||
|
:name: RougailDictionaryChoiceType
|
||||||
|
|
||||||
|
..
|
||||||
|
---
|
||||||
|
proxy_mode:
|
||||||
|
description: Configure Proxy Access to the Internet
|
||||||
|
choices:
|
||||||
|
- No proxy
|
||||||
|
- Auto-detect proxy settings for this network
|
||||||
|
- Use system proxy settings
|
||||||
|
- Manual proxy configuration
|
||||||
|
- Automatic proxy configuration URL
|
||||||
|
default: No proxy
|
||||||
|
|
||||||
|
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_004/firefox/00-proxy.yml>`
|
||||||
|
|
||||||
|
- Let's run the Rougail CLI
|
||||||
|
|
||||||
|
.. code-block:: text
|
||||||
|
:class: terminal
|
||||||
|
|
||||||
|
rougail -v 1.1 -m firefox/
|
||||||
|
|
||||||
|
We have an output like this one:
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_004/config/01/output_ro.html
|
||||||
|
:class: output
|
||||||
|
|
||||||
|
..
|
||||||
|
<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>
|
||||||
|
|
||||||
|
The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable.
|
||||||
|
|
||||||
|
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".
|
||||||
|
|
||||||
|
The constraints that come with the `choice` type
|
||||||
|
----------------------------------------------------
|
||||||
|
|
||||||
|
We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
|
||||||
|
|
||||||
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/config.yml
|
||||||
|
:linenos:
|
||||||
|
:language: yaml
|
||||||
|
:caption: A user data specification
|
||||||
|
|
||||||
|
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_004/config/03/config.yml>`
|
||||||
|
|
||||||
|
If we run the rougail CLI with this user datas, we have:
|
||||||
|
|
||||||
|
.. code-block:: text
|
||||||
|
:class: terminal
|
||||||
|
|
||||||
|
rougail -m firefox -u yaml -ff config/03/config.yml
|
||||||
|
|
||||||
|
We have this output:
|
||||||
|
|
||||||
|
.. raw:: html
|
||||||
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/output_ro.html
|
||||||
|
:class: output
|
||||||
|
|
||||||
|
..
|
||||||
|
<pre>╭────────────── Caption ───────────────╮
|
||||||
|
│ Variable Modified value │
|
||||||
|
│ (<span style="color: #00aa00">⏳ Original default value</span>) │
|
||||||
|
╰──────────────────────────────────────╯
|
||||||
|
Variables:
|
||||||
|
<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ <span style="color: #00aa00">No proxy</span>)
|
||||||
|
</pre>
|
||||||
|
|
||||||
|
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 value appears in green, which means : "user data value".
|
||||||
|
|
||||||
|
.. FIXME: verifier que cette sortie est bonne (on a des valeurs différentes)
|
||||||
|
|
||||||
|
.. type-along:: The constraints that come with the `choice` property
|
||||||
|
|
||||||
|
The `proxy_mode` variable's possible values is *constrained*.
|
||||||
|
|
||||||
|
We have the list of the possible (authorized) values:
|
||||||
|
|
||||||
|
- `No proxy`
|
||||||
|
- `Auto-detect proxy settings for this network`
|
||||||
|
- `Use system proxy settings`
|
||||||
|
- `Manual proxy configuration`
|
||||||
|
- `Automatic proxy configuration URL`
|
||||||
|
|
||||||
|
.. 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`).
|
||||||
|
|
||||||
|
**Progress**
|
||||||
|
|
||||||
|
To sum up, we have arrived at this point in writing a structure file like this:
|
||||||
|
|
||||||
|
**Structure description file**
|
||||||
|
|
||||||
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
||||||
|
:linenos:
|
||||||
|
:language: yaml
|
||||||
|
:caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
|
||||||
|
|
||||||
|
..
|
||||||
|
|
||||||
|
.. raw:: text
|
||||||
|
|
||||||
|
---
|
||||||
|
proxy_mode:
|
||||||
|
description: Configure Proxy Access to the Internet
|
||||||
|
choices:
|
||||||
|
- No proxy
|
||||||
|
- Auto-detect proxy settings for this network
|
||||||
|
- Use system proxy settings
|
||||||
|
- Manual proxy configuration
|
||||||
|
- Automatic proxy configuration URL
|
||||||
|
default: No proxy
|
||||||
|
|
||||||
|
|
@ -58,6 +58,7 @@ We'll learn in this tutorial how to set the values of the configuration options
|
||||||
:caption: The firefox tutorial
|
:caption: The firefox tutorial
|
||||||
|
|
||||||
preliminary
|
preliminary
|
||||||
|
choice
|
||||||
proxymode
|
proxymode
|
||||||
disabled
|
disabled
|
||||||
boolean
|
boolean
|
||||||
|
|
|
||||||
|
|
@ -13,7 +13,7 @@ Getting started
|
||||||
|
|
||||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||||
- If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`,
|
- If you want to follow this tutorial with the help of the corresponding :tutorial:`Rougail-tutorials git repository <>`,
|
||||||
this workshop page corresponds to the tags :tutorial:`v1.1_000 <src/tag/v1.1_000>` to :tutorial:`v1.1_011 <src/tag/v1.1_011>`
|
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:
|
in the repository:
|
||||||
|
|
||||||
::
|
::
|
||||||
|
|
@ -249,21 +249,21 @@ he is responsible of other files called the :term:`user data files <user data fi
|
||||||
└── config
|
└── config
|
||||||
└── config.yml
|
└── config.yml
|
||||||
|
|
||||||
.. type-along:: how to set a value in a user datas file
|
.. type-along:: how to set a user data value
|
||||||
|
|
||||||
So for example if the integrator has not set any default value in his structure file,
|
If the integrator has not set any default value in his structure file,
|
||||||
it's up to the operator to do the job in the `config.yml` file:
|
it's up to the operator to do the job in the `config.yml` file:
|
||||||
|
|
||||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yml
|
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/config.yml
|
||||||
:language: yaml
|
:language: yaml
|
||||||
:caption: A Rougail user datas file :file:`config/config.yml`, with a default value set.
|
:caption: A Rougail user datas file :file:`config/config.yml`, with a value set.
|
||||||
:name: RougailConfigDefaultValue
|
:name: RougailConfigDefaultValue
|
||||||
|
|
||||||
..
|
..
|
||||||
---
|
---
|
||||||
proxy_mode: No proxy
|
proxy_mode: No proxy
|
||||||
|
|
||||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_001/config/02/config.yml>`
|
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_003/config/02/config.yml>`
|
||||||
|
|
||||||
With the rougail CLI the operator has to add the `-u yaml -ff config/config.yml` options:
|
With the rougail CLI the operator has to add the `-u yaml -ff config/config.yml` options:
|
||||||
|
|
||||||
|
|
@ -276,7 +276,7 @@ With the rougail CLI the operator has to add the `-u yaml -ff config/config.yml`
|
||||||
which gives us this output:
|
which gives us this output:
|
||||||
|
|
||||||
.. raw:: html
|
.. raw:: html
|
||||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_001/config/02/output_ro.html
|
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_003/config/02/output_ro.html
|
||||||
:class: output
|
:class: output
|
||||||
|
|
||||||
..
|
..
|
||||||
|
|
@ -287,158 +287,32 @@ which gives us this output:
|
||||||
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yml"
|
<span style="color: #5c5cff">┗━━ </span>📓 proxy_mode: No proxy ◀ loaded from the YAML file "config/02/config.yml"
|
||||||
</pre>
|
</pre>
|
||||||
|
|
||||||
.. admonition:: Important fact
|
Now the `proxy_mode`'s new `No proxy` value is the same as the default value but we see 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).
|
||||||
|
|
||||||
- the integrator works on structure files
|
.. type-along:: structure values and user data values
|
||||||
- the operator works on user data files
|
|
||||||
|
|
||||||
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.
|
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.
|
||||||
|
|
||||||
.. type-along:: Defining a choice type
|
.. admonition:: Reminder
|
||||||
|
|
||||||
In our firefox use case, the real type of the `proxy_mode` variable will be now set as a `choice` type:
|
- the integrator works on structure files, he can define default value for variables
|
||||||
|
- the operator works on user data files, he only can set user data values for variables
|
||||||
|
|
||||||
.. seealso:: Have a look at the definition of the :term:`choice type variable <choice type>`
|
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.
|
||||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
|
||||||
:linenos:
|
|
||||||
:language: yaml
|
|
||||||
:caption: The real :file:`firefox/proxy.yml` Rougail structure file with a choice type
|
|
||||||
:name: RougailDictionaryChoiceType
|
|
||||||
|
|
||||||
..
|
|
||||||
---
|
|
||||||
proxy_mode:
|
|
||||||
description: Configure Proxy Access to the Internet
|
|
||||||
choices:
|
|
||||||
- No proxy
|
|
||||||
- Auto-detect proxy settings for this network
|
|
||||||
- Use system proxy settings
|
|
||||||
- Manual proxy configuration
|
|
||||||
- Automatic proxy configuration URL
|
|
||||||
default: No proxy
|
|
||||||
|
|
||||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_004/firefox/00-proxy.yml>`
|
|
||||||
|
|
||||||
- Let's run the Rougail CLI
|
|
||||||
|
|
||||||
.. code-block:: text
|
|
||||||
:class: terminal
|
|
||||||
|
|
||||||
rougail -v 1.1 -m firefox/
|
|
||||||
|
|
||||||
We have an output like this one:
|
|
||||||
|
|
||||||
.. raw:: html
|
|
||||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_004/config/01/output_ro.html
|
|
||||||
:class: output
|
|
||||||
|
|
||||||
..
|
|
||||||
<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>
|
|
||||||
|
|
||||||
The `proxy_mode` variable here, implicitely requires a value. It is a :term:`mandatory` variable.
|
|
||||||
|
|
||||||
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".
|
|
||||||
|
|
||||||
The constraints that come with the `choice` type
|
|
||||||
----------------------------------------------------
|
|
||||||
|
|
||||||
We say that the `proxy_mode` variable is *constrained* (by the `choice` type).
|
|
||||||
|
|
||||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/config.yml
|
|
||||||
:linenos:
|
|
||||||
:language: yaml
|
|
||||||
:caption: A user data specification
|
|
||||||
|
|
||||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_004/config/03/config.yml>`
|
|
||||||
|
|
||||||
If we run the rougail CLI with this user datas, we have:
|
|
||||||
|
|
||||||
.. code-block:: text
|
|
||||||
:class: terminal
|
|
||||||
|
|
||||||
rougail -m firefox -u yaml -ff config/03/config.yml
|
|
||||||
|
|
||||||
We have this output:
|
|
||||||
|
|
||||||
.. raw:: html
|
|
||||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/config/03/output_ro.html
|
|
||||||
:class: output
|
|
||||||
|
|
||||||
..
|
|
||||||
<pre>╭────────────── Caption ───────────────╮
|
|
||||||
│ Variable Modified value │
|
|
||||||
│ (<span style="color: #00aa00">⏳ Original default value</span>) │
|
|
||||||
╰──────────────────────────────────────╯
|
|
||||||
Variables:
|
|
||||||
<span style="color: #5c5cff">┗━━ </span>📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ loaded from the YAML file "config/03/config.yml" (⏳ <span style="color: #00aa00">No proxy</span>)
|
|
||||||
</pre>
|
|
||||||
|
|
||||||
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 value appears in green, which means : "user data value".
|
|
||||||
|
|
||||||
.. FIXME: verifier que cette sortie est bonne (on a des valeurs différentes)
|
|
||||||
|
|
||||||
.. type-along:: The constraints that come with the `choice` property
|
|
||||||
|
|
||||||
The `proxy_mode` variable's possible values is *constrained*.
|
|
||||||
|
|
||||||
We have the list of the possible (authorized) values:
|
|
||||||
|
|
||||||
- `No proxy`
|
|
||||||
- `Auto-detect proxy settings for this network`
|
|
||||||
- `Use system proxy settings`
|
|
||||||
- `Manual proxy configuration`
|
|
||||||
- `Automatic proxy configuration URL`
|
|
||||||
|
|
||||||
.. keypoints:: Key points progress
|
.. 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**
|
**Keywords**
|
||||||
|
|
||||||
- :term:`structure file <structure file>`: structure description file
|
- :term:`structure file <structure file>`: structure description file
|
||||||
- :term:`variable`: an option's name which has a value
|
- :term:`variable`: an option's name which has a value
|
||||||
- a variable's description
|
- a variable's description
|
||||||
- a variable's type
|
- a variable's mandatory value
|
||||||
- a variable's default value
|
- a variable's default value
|
||||||
|
- a variable's user value
|
||||||
- the :term:`integrator` and :term:`operator` roles
|
- the :term:`integrator` and :term:`operator` roles
|
||||||
- a mandatory value
|
|
||||||
- a choice type
|
|
||||||
|
|
||||||
**Progress**
|
|
||||||
|
|
||||||
To sum up, we have arrived at this point in writing a structure file like this:
|
|
||||||
|
|
||||||
**Structure description file**
|
|
||||||
|
|
||||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_004/firefox/00-proxy.yml
|
|
||||||
:linenos:
|
|
||||||
:language: yaml
|
|
||||||
:caption: A Rougail structure file with a variable named `proxy_mode`, with a default value.
|
|
||||||
|
|
||||||
..
|
|
||||||
|
|
||||||
.. raw:: text
|
|
||||||
|
|
||||||
---
|
|
||||||
proxy_mode:
|
|
||||||
description: Configure Proxy Access to the Internet
|
|
||||||
choices:
|
|
||||||
- No proxy
|
|
||||||
- Auto-detect proxy settings for this network
|
|
||||||
- Use system proxy settings
|
|
||||||
- Manual proxy configuration
|
|
||||||
- Automatic proxy configuration URL
|
|
||||||
default: No proxy
|
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -14,7 +14,6 @@ Group variables inside families
|
||||||
- We have an idea of what a :term:`structure description file<structure file>` is
|
- We have an idea of what a :term:`structure description file<structure file>` is
|
||||||
- We have a folder named :file:`firefox` and we are putting all the structure description files into it
|
- We have a folder named :file:`firefox` and we are putting all the structure description files into it
|
||||||
|
|
||||||
|
|
||||||
.. type-along:: let's recap: we have this choice type variable
|
.. type-along:: let's recap: we have this choice type variable
|
||||||
|
|
||||||
In the structure description file, we have:
|
In the structure description file, we have:
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue