305 lines
10 KiB
ReStructuredText
305 lines
10 KiB
ReStructuredText
Group variables inside families
|
||
=================================
|
||
|
||
.. objectives:: Objectives
|
||
|
||
We will learn how to:
|
||
|
||
- create a :term:`family`
|
||
- gather :term:`variable`\ s into a :term:`family`
|
||
- make a variable within a variable, which turns this variable container into being a family
|
||
|
||
.. prerequisites:: Prerequisites
|
||
|
||
- 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.
|
||
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>`,
|
||
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.
|
||
|
||
::
|
||
|
||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||
git checkout v1.1_020
|
||
|
||
.. type-along:: let's recap how far we've come
|
||
|
||
We have this choice type variable in its structure definition file:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml
|
||
:linenos:
|
||
:language: yaml
|
||
:caption: The `proxy_mode` choice type variable in the :file:`firefox/00-proxy.yml` structure file
|
||
|
||
..
|
||
---
|
||
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
|
||
|
||
.. We're gonna put it in a :term:`family`.
|
||
|
||
In short, let's describe our `proxy_mode` variable like this:
|
||
|
||
.. confval:: proxy_mode
|
||
:type: `choice`
|
||
:default: No proxy
|
||
|
||
Proxy mode's settings
|
||
|
||
Now we will define new variables, and other structure definitions.
|
||
For the sake of clarity, we will put the structure definitions in separate files.
|
||
Please have a look at the :ref:`file naming and organizing convention <namingconvention>`.
|
||
|
||
Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make
|
||
a new structure file named :file:`firefox/10-manual.yml`::
|
||
|
||
.
|
||
└── firefox
|
||
├── 00-proxy.yml
|
||
└── 10-manual.yml
|
||
|
||
Creating a new family
|
||
-----------------------
|
||
|
||
Let's create a family named `manual` which obviously corresponds to the proxy's manual configuration choice.
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
|
||
:language: yaml
|
||
:caption: A family structure file description named `manual` in a :file:`firefox/10-manual.yml` file
|
||
:name: RougailManualFamily
|
||
|
||
..
|
||
---
|
||
manual:
|
||
description: Manual proxy configuration
|
||
type: family
|
||
|
||
We can see that we have defined a :term:`family` here, and this family is *empty*
|
||
which means that this family is a container variable that contains no variable yet.
|
||
|
||
.. warning::
|
||
|
||
If a family is empty, we need to specify the :term:`family` type here because if we don't,
|
||
the Rougail's type engine will infer it by default as a :term:`variable`.
|
||
We have to force the family type inference.
|
||
|
||
It's because we don't have set any :term:`variable` inside yet. When we will have a variable inside of this family,
|
||
we will make a YAML block (to create a block in YAML, you just need to indent the lines) and the Rougail's type inference engine will implicitely infer the variable's container as a family type.
|
||
|
||
Or a sub family
|
||
----------------
|
||
|
||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||
|
||
Now you need to checkout the `v1.1_021` version::
|
||
|
||
git checkout v1.1_021
|
||
|
||
.. glossary::
|
||
|
||
sub family
|
||
|
||
A sub family is a family inside a family.
|
||
|
||
Creating a family hierarchy of family container types is very easy, here is an example:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml
|
||
:language: yaml
|
||
:caption: A rougail structure description file with a hierarchy.
|
||
:name: RougailFirstFamilyHierarchy
|
||
|
||
..
|
||
---
|
||
manual:
|
||
description: Manual proxy configuration
|
||
type: family
|
||
|
||
http_proxy:
|
||
description: HTTP Proxy
|
||
type: family
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_021/firefox/00-proxy.yml>`
|
||
|
||
Note that the `http_proxy` family lives inside the `manual` family.
|
||
|
||
Putting a variable inside of a family or a sub family
|
||
-----------------------------------------------------------
|
||
|
||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||
|
||
Now you need to checkout the `v1.1_022` version::
|
||
|
||
git checkout 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.
|
||
This time, the type of this new variable is a `domainname` type:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/firefox/10-manual.yml
|
||
:language: yaml
|
||
:caption: An `address` variable in the `http_proxy` family
|
||
:name: RougailVariableInSubFamily
|
||
|
||
..
|
||
---
|
||
manual:
|
||
description: Manual proxy configuration
|
||
type: family
|
||
|
||
http_proxy:
|
||
description: HTTP Proxy
|
||
type: family
|
||
|
||
address:
|
||
description: HTTP address
|
||
type: domainname
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_022/firefox/10-manual.yml>`
|
||
|
||
Now that the :confval:`address` variable is declared, the :term:`operator` can set :term:`a value <value>` to it.
|
||
|
||
In short, let's describe our `address` variable like this:
|
||
|
||
.. confval:: address
|
||
:type: `domainname`
|
||
:default: None
|
||
|
||
This is the HTTP address of the proxy
|
||
|
||
.. note:: We encountered here a new type of variable there: the `domainname` type.
|
||
There are a bunch of types available in Rougail.
|
||
|
||
We have reached the definition of the address in the `http_proxy` family; there will be other variables to define in this family.
|
||
|
||
.. image:: images/firefox_manual_family.png
|
||
|
||
.. type-along:: Assigning a user value
|
||
|
||
Now we need to set a value for the :confval:`address` variable,
|
||
otherwise we will get an error if we try to access this variable:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/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> - manual.http_proxy.address (HTTP address)
|
||
</pre>
|
||
|
||
.. type-along:: let's set user values in a user data file
|
||
|
||
Here is a user data file sample:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/02/config.yml
|
||
:language: yaml
|
||
:caption: A user file named :file:`config/03/config.yml` with a value set for the `address` variable
|
||
:name: RougailAddresseVariableUserValue
|
||
|
||
..
|
||
---
|
||
proxy_mode: Manual proxy configuration
|
||
manual:
|
||
http_proxy:
|
||
address: example.net
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_022/config/02/config.yml>`
|
||
|
||
Let's validate the consitency of the :term:`configuration`:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/02/cmd_ro.txt
|
||
:class: terminal
|
||
|
||
..
|
||
rougail -m firefox/ -u yaml -yf config/02/config.yml
|
||
|
||
Everything is OK:
|
||
|
||
.. raw:: html
|
||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/02/output_ro.html
|
||
:class: output
|
||
|
||
..
|
||
<pre>╭──────── Caption ────────╮
|
||
│ Variable <span style="color: #ffd700">Default value</span> │
|
||
│ Modified value │
|
||
╰─────────────────────────╯
|
||
Variables:
|
||
<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
|
||
<span style="color: #5c5cff">┗━━ </span>📂 Manual proxy configuration
|
||
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📂 HTTP Proxy
|
||
<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:
|
||
|
||
- the `proxy_mode` value is set by default by the :term:`integrator`
|
||
- the `address` value is has been set by an :term:`operator`
|
||
|
||
.. type-along:: A second variable in the `http_proxy` family
|
||
|
||
Now let's add a `port` variable in the `http_proxy` family:
|
||
|
||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_022/config/03/config.yml
|
||
:language: yaml
|
||
:caption: The :file:`config/03/config.yml` user data file with the `port` number added
|
||
:linenos:
|
||
|
||
..
|
||
---
|
||
manual:
|
||
description: Manual proxy configuration
|
||
|
||
http_proxy:
|
||
description: HTTP Proxy
|
||
|
||
address:
|
||
description: HTTP address
|
||
type: domainname
|
||
params:
|
||
allow_ip: true
|
||
|
||
port:
|
||
description: HTTP Port
|
||
type: port
|
||
default: 8080
|
||
|
||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_022/config/03/config.yml>`
|
||
|
||
In short:
|
||
|
||
.. confval:: port
|
||
:type: `port`
|
||
:default: 8080
|
||
|
||
The HTTP Port
|
||
|
||
.. keypoints:: let's review the key points
|
||
|
||
**Keywords**
|
||
|
||
- we know how to define :term:`variable`\ s inside of a family
|
||
- we now know what a :term:`mandatory` variable is and why it is necessary to assign values to the variables
|
||
- we kwow how to set a variable's :term:`user value <user datas>`
|
||
- we have the big picture : the :term:`configuration`, which is (the structure files + the user data files)
|
||
|
||
**Progress**
|
||
|
||
- we have a :term:`family` named `manual` and a sub family named `http_proxy`
|
||
- And we have now two variables: :confval:`proxy_mode` and :confval:`address`.
|