fix: 08*
This commit is contained in:
parent
38fad60219
commit
fe0488b8d3
4 changed files with 306 additions and 297 deletions
|
|
@ -120,6 +120,9 @@ Rougail et ces composants :
|
|||
### Structurals
|
||||
|
||||
Les fichiers de "Structures" sont des fichiers au format Rougail dans laquelle toutes les informations du cycle de vie sont définies.
|
||||
|
||||
Avoir des données structurées veut dire qu'on peut publier une fois et avoir plusieurs rendus.
|
||||
|
||||
Il est important de tout mettre ces informations au même endroit. Ainsi on connaitre toutes les aspects de la variable en lisant ces fichiers.
|
||||
On y retrouve :
|
||||
|
||||
|
|
|
|||
|
|
@ -3,9 +3,9 @@ Custom type
|
|||
|
||||
.. objectives:: Objectives
|
||||
|
||||
In this sections we are going to learn how to create custom types with Rougail.
|
||||
In short, a custom type is nothing more than a kind of a template for a family.
|
||||
|
||||
In this sections we are going to learn how to create custom types with Rougail.
|
||||
In short, a custom type is nothing more than a kind of a template for a variable or a family.
|
||||
|
||||
.. prerequisites:: Prerequisites
|
||||
|
||||
- We assume that Rougail's library is :ref:`installed <installation>` on your computer.
|
||||
|
|
@ -15,49 +15,223 @@ Custom type
|
|||
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_080 <src/tag/v1.1_080>` to :tutorial:`v1.1_083 <src/tag/v1.1_083>`
|
||||
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_080 <src/tag/v1.1_080>` to :tutorial:`v1.1_083 <src/tag/v1.1_083>`
|
||||
in the repository.
|
||||
|
||||
::
|
||||
|
||||
|
||||
git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
|
||||
git switch --detach v1.1_080
|
||||
|
||||
HTTP Proxy with "proxy" type
|
||||
--------------------------------
|
||||
|
||||
Let's look now at the possibilities for adding types.
|
||||
Let's look now at the possibilities for adding types.
|
||||
This feature is essential for having a truly adaptable tool.
|
||||
|
||||
.. note:: It is actually possible to add types,
|
||||
but that involves adding predefined types to the :term:`tiramisu` underlying consistency library itself,
|
||||
.. note:: It is actually possible to add types,
|
||||
but that involves adding predefined types to the :term:`Tiramisu` underlying consistency library itself,
|
||||
and that’s a different matter altogether. There is a simpler way to achieve this with the Rougail type definition feature.
|
||||
|
||||
It is possible in Rougail to create custom types in a very simple way, it is much like defining families.
|
||||
|
||||
It is possible in Rougail to create custom types in a very simple way, it is much like defining variables or families.
|
||||
|
||||
Our folder structure will be expanded a bit:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/tree.html
|
||||
|
||||
|
||||
Notice that we have now a new :file:`types` folder in our tree structure.
|
||||
This is where we will place our new `proxy` type definition.
|
||||
|
||||
.. note:: Choosing the :file:`types/proxy/00-type.yml` file name is not mandatory.
|
||||
.. note:: Choosing the :file:`types/proxy/00-type.yml` file name is not mandatory.
|
||||
You can name this folder whatever you want.
|
||||
It is simply a good practice to separate structure files from type definition files.
|
||||
It is simply a good practice to separate structure files from type definition files.
|
||||
We will see later on how to indicate to Rougail that a file contains a type declaration.
|
||||
|
||||
In accordance with our :ref:`naming policy <namingconvention>`, we have created a file named :file:`00-type.yml`
|
||||
inside the `proxy` folder.
|
||||
inside the `proxy` folder.
|
||||
Let's examine this more closely this :file:`types/proxy/00-type.yml` type definition file:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/types/proxy/00-type.yml
|
||||
:language: yaml
|
||||
:language: yaml
|
||||
:caption: The :file:`types/proxy/00-type.yml` type structure file that defines our new `proxy` type.
|
||||
|
||||
..
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
proxy:
|
||||
|
||||
address:
|
||||
description: Proxy address
|
||||
type: domainname
|
||||
params:
|
||||
allow_ip: true
|
||||
|
||||
port:
|
||||
description: Proxy port
|
||||
type: port
|
||||
default: 8080
|
||||
...
|
||||
|
||||
The new type named `proxy` is declared the same way we declare a family.
|
||||
It's more or less like a family declaration except it will be used as a type definition.
|
||||
If you remember, it's mostly the content as the family `manual.http_proxy` in `firefox/10-manual.yml` file of this tutorial.
|
||||
|
||||
.. questions:: How do we use a new type?
|
||||
|
||||
Very simply. In the usual way: we will add a `type` parameter in our family declaration.
|
||||
|
||||
Let's declare that a family is of type `proxy` as follows:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/10-manual.yml` structure file with less code due to the `proxy` type definition
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
manual:
|
||||
description: Manual proxy configuration
|
||||
disabled:
|
||||
variable: _.proxy_mode
|
||||
when_not: Manual proxy configuration
|
||||
|
||||
http_proxy:
|
||||
description: HTTP Proxy
|
||||
type: proxy
|
||||
...
|
||||
|
||||
|
||||
We can see that the type declared for the `http_proxy` family is now `type: proxy`.
|
||||
It's perfectly natural in the Rougail style.
|
||||
|
||||
But in order to use our new type we need to declare it to Rougail otherwise the new type is not available.
|
||||
The Rougail CLI has the `--types` type declaration command line option for this purpose.
|
||||
Let's launch the Rougail CLI with this command line parameter:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/cmd_ro.txt
|
||||
:class: terminal
|
||||
|
||||
The CLI output is entirely standard and does not specifically mention the call to a new type.
|
||||
The result is the same as usual, as if the type declaration were omitted, which is what we want.
|
||||
We want the same behavior as usual.
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/output_ro.html
|
||||
:class: output
|
||||
|
||||
The type definition adds nothing to the structural logic. It's just a very convenient way to save time when writing structure files.
|
||||
|
||||
Now in the `address` variable it is not necessary to be specified and all parameters (the `domainname` type and the `allow_ip` parameter) are available:
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: We can omit these settings now due to the type definition
|
||||
|
||||
description: HTTP address
|
||||
type: domainname
|
||||
params:
|
||||
allow_ip: true
|
||||
|
||||
HTTPS and SOCKS Proxy with "proxy" type
|
||||
---------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_081` version::
|
||||
|
||||
git switch --detach v1.1_081
|
||||
|
||||
With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a much more conscious way:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_081/firefox/20-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/20-manual.yml` structure file with less code due to the `proxy` type definition
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
manual:
|
||||
|
||||
use_for_https: true # Also use this proxy for HTTPS
|
||||
|
||||
https_proxy:
|
||||
description: HTTPS Proxy
|
||||
type: proxy
|
||||
hidden:
|
||||
variable: _.use_for_https
|
||||
|
||||
socks_proxy:
|
||||
description: SOCKS Proxy
|
||||
type: proxy
|
||||
...
|
||||
|
||||
Now we have two families with the `proxy` type: `https_proxy` and `socks_proxy`.
|
||||
|
||||
FIXME expliqué qu'on n'a pas encore tout ce qu'on avait avant !
|
||||
|
||||
Add a variable in a family with custom type
|
||||
--------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_082` version::
|
||||
|
||||
git switch --detach v1.1_082
|
||||
|
||||
|
||||
In the `socks_proxy` family definition, we need to added a new variable, the `version` variable:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
version:
|
||||
description: SOCKS host version used by proxy
|
||||
choices:
|
||||
- v4
|
||||
- v5
|
||||
default: v5
|
||||
|
||||
You can see that what we call a type definition in Rougail is very flexible, because it is perfectly possible
|
||||
to add to what has been defined in the type.
|
||||
The type definition here is therefore not only a template but much more an extensible schema.
|
||||
|
||||
Redefine default value in custom type variable
|
||||
-----------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_083` version::
|
||||
|
||||
git switch --detach v1.1_083
|
||||
|
||||
In this section we are going to make an implicit redefinition of variables default values.
|
||||
|
||||
.. glossary::
|
||||
|
||||
redefine
|
||||
|
||||
A redefine is a redefinition of all or part of the attributes of a variable as it was previously defined.
|
||||
There are two types of redefine, an implicit and an explicit.
|
||||
An implicit redefinition is a redefinition which has not been declared with the `redefine` attribute.
|
||||
An explicit redefinition is a redefinition which has been declared with the `redefine: true` attribute.
|
||||
|
||||
Only default values can be implicitly redefined (and only in the type definitions), all other attributes
|
||||
need to be explicitely redefined.
|
||||
|
||||
In the type definition file, we are now setting default values for the `address` and `port` variables:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/types/proxy/00-type.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`types/proxy/00-type.yml` type definition file with the default values for `address` and `port`
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
|
@ -78,19 +252,12 @@ Let's examine this more closely this :file:`types/proxy/00-type.yml` type defini
|
|||
default:
|
||||
variable: __.http_proxy.port
|
||||
...
|
||||
|
||||
The new type named `proxy` is declared the same way we declare a family.
|
||||
It's more or less like a family declaration except it will be used as a type definition.
|
||||
|
||||
.. questions:: How do we use a new type?
|
||||
But we don't want theses default values for HTTP definition. We can :term:`redefine` these type settings in the structure file:
|
||||
|
||||
Very simply. In the usual way: we will add a `type` parameter in our family declaration.
|
||||
|
||||
Let's declare that a family is of type `proxy` as follows:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/10-manual.yml` structure file with less code due to the `proxy` type definition
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/10-manual.yml` structure definition file with the **redefined** default values for `address` and `port`
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
|
|
@ -114,43 +281,57 @@ Let's declare that a family is of type `proxy` as follows:
|
|||
default: 8080
|
||||
...
|
||||
|
||||
We can see that the type declared for the `http_proxy` family is `type: proxy`.
|
||||
It's perfectly natural in the rougail style.
|
||||
This means that the default values for these variables will now be those defined
|
||||
in the structure file if the values are defined (and not in the type definitions file).
|
||||
|
||||
Now in the `address` family it is not necessary to specify the `domainname` type nor the `allow_ip` parameter:
|
||||
Let's have a closer look at the behavior here.
|
||||
|
||||
.. code-block:: yaml
|
||||
:caption: We can omit these settings now due to the type definition
|
||||
|
||||
description: HTTP address
|
||||
type: domainname
|
||||
params:
|
||||
allow_ip: true
|
||||
|
||||
But in order to use our new type we need to declare it to Rougail otherwise the new type is not available.
|
||||
The Rougail CLI has the `--types` type declaration command line option for this purpose.
|
||||
Let's launch the rougail CLI with this command line parameter:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/cmd_ro.txt
|
||||
:class: terminal
|
||||
|
||||
The CLI output is entirely standard and does not specifically mention the call to a new type.
|
||||
The result is the same as usual, as if the type declaration were omitted, which is what we want.
|
||||
We want the same behavior as usual.
|
||||
Let's launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/config/01/output_ro.html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/cmd_ro.txt
|
||||
:class: terminal
|
||||
|
||||
..
|
||||
rougail -m firefox/ -u yaml -yf config/01/config.yml
|
||||
|
||||
We have this output:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/output_ro.html
|
||||
:class: output
|
||||
|
||||
The type definition adds nothing to the structural logic. It's just a very convenient way to save time when writing structure files.
|
||||
We can see in the output that
|
||||
|
||||
- the default values of the `port` variable, which is `8080` in the structure file, comes from the strucure file.
|
||||
- the default values of the `address` variable is not set because it is `null` by default in the structure file,
|
||||
so there is not such thing as a default value set for this variable.
|
||||
|
||||
.. questions:: What happens if the default value in the type definition is not suitable for us?
|
||||
|
||||
If we hadn't defined a value in the userdata file, the Rougail CLI would have returned the following error:
|
||||
|
||||
::
|
||||
|
||||
🛑 Caution
|
||||
┗━━ Manual proxy configuration
|
||||
┣━━ HTTP Proxy
|
||||
┃ ┗━━ Proxy address: 🛑 mandatory variable but has no value
|
||||
┗━━ SOCKS Proxy
|
||||
┗━━ Proxy address: 🛑 mandatory variable but has no value
|
||||
|
||||
Therefore, the default value that was taken into account is indeed that of the structure file, and not that of the type definition.
|
||||
|
||||
.. note:: We can see that the Rougail behavior is always very simple, there is no such thing as an MRO
|
||||
(Method Resolution Object) that try fallback to the default value defined in the type definition file.
|
||||
The Rougail behavior is much more simple and transparent.
|
||||
|
||||
.. type-along:: kinematics of setting the `address` value
|
||||
|
||||
Let's take the time to explain how the value of the variable `manual.http_proxy.address` is determined using the type definition.
|
||||
|
||||
The :file:`10-manual.yml` structure file defines the :file:`manual.https_proxy` family
|
||||
which is defined with the help of the `proxy` type:
|
||||
The :file:`10-manual.yml` structure file defines the :file:`manual.http_proxy` family
|
||||
which is defined with the help of the `proxy` type:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -180,222 +361,38 @@ Which is `null` by default but in the :file:`config/01/config.yml` user data fil
|
|||
http_proxy:
|
||||
address: http.proxy.net
|
||||
|
||||
In the CLI standard output we can see that the `http_proxy.address` variable value is
|
||||
In the CLI standard output we can see that the `http_proxy.address` variable value is
|
||||
finally set by the user data file:
|
||||
|
||||
::
|
||||
|
||||
┗━━ 📂 manual (Manual proxy configuration)
|
||||
┣━━ 📂 http_proxy (HTTP Proxy)
|
||||
┃ ┣━━ 📓 address (Proxy address): http.proxy.net ◀ loaded from the YAML
|
||||
┃ ┣━━ 📓 address (Proxy address): http.proxy.net ◀ loaded from the YAML
|
||||
┃ ┃ file "config/01/config.yml"
|
||||
|
||||
|
||||
|
||||
Add a variable in a family with custom type
|
||||
Redefine other parameter in custom type for HTTP
|
||||
--------------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_081` version::
|
||||
|
||||
git switch --detach v1.1_081
|
||||
Now you need to checkout the `v1.1_084` version::
|
||||
|
||||
With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a much more conscious way:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_081/firefox/20-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/20-manual.yml` structure file with less code due to the `proxy` type definition
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
manual:
|
||||
|
||||
use_for_https: true # Also use this proxy for HTTPS
|
||||
|
||||
https_proxy:
|
||||
description: HTTPS Proxy
|
||||
type: proxy
|
||||
hidden:
|
||||
variable: _.use_for_https
|
||||
|
||||
socks_proxy:
|
||||
description: SOCKS Proxy
|
||||
type: proxy
|
||||
|
||||
version:
|
||||
description: SOCKS host version used by proxy
|
||||
choices:
|
||||
- v4
|
||||
- v5
|
||||
default: v5
|
||||
...
|
||||
|
||||
First, now we have two families with the `proxy` type: `type: proxy`, and `socks_proxy`.
|
||||
|
||||
Second, in the `socks_proxy` family definition, we can see that we have added a new variable,
|
||||
the `version` variable:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
version:
|
||||
description: SOCKS host version used by proxy
|
||||
choices:
|
||||
- v4
|
||||
- v5
|
||||
default: v5
|
||||
|
||||
You can see that what we call a type definition in Rougail is very flexible, because it is perfectly possible
|
||||
to add to what has been defined in the type.
|
||||
The type definition here is therefore not only a template but much more an extensible schema.
|
||||
|
||||
Redefine default value in custom type variable
|
||||
--------------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_082` version::
|
||||
|
||||
git switch --detach v1.1_082
|
||||
|
||||
.. glossary::
|
||||
|
||||
redefine
|
||||
|
||||
A redefine is a redefinition of all or part of the attributes of a variable as it was previously defined.
|
||||
There are two types of redefine, an implicit and an explicit.
|
||||
An implicit redefinition is a redefinition which has not been declared with the `redefine` attribute.
|
||||
An explicit redefinition is a redefinition which has been declared with the `redefine: true` attribute.
|
||||
|
||||
Only default values can be implicitly redefined (and only in the type definitions), all other attributes
|
||||
need to be explicitely redefined.
|
||||
|
||||
|
||||
In this section we are going to make an implicit redefinition of variables default values.
|
||||
|
||||
In the type definition file, we have default values defined for the `address` and `port` variables:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/types/proxy/00-type.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`types/proxy/00-type.yml` type definition file with the default values for `address` and `port`
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
proxy:
|
||||
|
||||
address:
|
||||
description: Proxy address
|
||||
type: domainname
|
||||
params:
|
||||
allow_ip: true
|
||||
default:
|
||||
variable: __.http_proxy.address
|
||||
|
||||
port:
|
||||
description: Proxy port
|
||||
type: port
|
||||
default:
|
||||
variable: __.http_proxy.port
|
||||
...
|
||||
|
||||
But we don't want theses default values. We can :term:`redefine` these type settings in the structure file:
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/10-manual.yml` structure definition file with the **redefined** default values for `address` and `port`
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
||||
manual:
|
||||
description: Manual proxy configuration
|
||||
disabled:
|
||||
variable: _.proxy_mode
|
||||
when_not: Manual proxy configuration
|
||||
|
||||
http_proxy:
|
||||
description: HTTP Proxy
|
||||
type: proxy
|
||||
|
||||
address:
|
||||
default: null
|
||||
|
||||
port:
|
||||
default: 8080
|
||||
...
|
||||
|
||||
This means that the default values for these variables will now be those defined
|
||||
in the structure file if the values are defined (and not in the type definitions file).
|
||||
|
||||
Let's have a closer look at the behavior here.
|
||||
|
||||
Let's launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/cmd_ro.txt
|
||||
:class: terminal
|
||||
|
||||
..
|
||||
rougail -m firefox/ -u yaml -yf config/01/config.yml
|
||||
|
||||
We have this output:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_082/config/01/output_ro.html
|
||||
:class: output
|
||||
|
||||
We can see in the output that
|
||||
|
||||
- the default values of the `port` variable, which is `8080` in the structure file, comes from the strucure file.
|
||||
- the default values of the `address` variable is not set because it is `null` by default in the structure file,
|
||||
so there is not such thing as a default value set for this variable.
|
||||
|
||||
.. questions:: What happens if the default value in the type definition is not suitable for us?
|
||||
|
||||
If we hadn't defined a value in the userdata file, the Rougail CLI would have returned the following error:
|
||||
|
||||
::
|
||||
|
||||
🛑 Caution
|
||||
┗━━ Manual proxy configuration
|
||||
┣━━ HTTP Proxy
|
||||
┃ ┗━━ Proxy address: 🛑 mandatory variable but has no value
|
||||
┗━━ SOCKS Proxy
|
||||
┗━━ Proxy address: 🛑 mandatory variable but has no value
|
||||
|
||||
Therefore, the default value that was taken into account is indeed that of the structure file, and not that of the type definition.
|
||||
|
||||
.. note:: We can see that the Rougail behavior is always very simple, there is no such thing as an MRO
|
||||
(Method Resolution Object) that try fallback to the default value defined in the type definition file.
|
||||
The Rougail behavior is much more simple and transparent.
|
||||
|
||||
Redefine other parameter in custom type
|
||||
------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_083` version::
|
||||
|
||||
git switch --detach v1.1_083
|
||||
git switch --detach v1.1_084
|
||||
|
||||
In this sections we are going to make explicit :term:`redefinitions <redefine>`.
|
||||
|
||||
The type definition didn't change, what we're talking about here is modifiying what has been previously defined
|
||||
in the type definition file:
|
||||
The type definition didn't change, what we're talking about here is modifiying what has been previously defined
|
||||
in the type definition file:
|
||||
FIXME : en fait si ! on supprime la description, de address et port qui n'a pas de sens dans le type (suivant le type il faut le redéfinir).
|
||||
et on modifie ici le type pour HTTP.
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/types/proxy/00-type.yml
|
||||
:language: yaml
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_084/types/proxy/00-type.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`types/proxy/00-type.yml` type definition file with the default definitions
|
||||
|
||||
..
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
|
@ -403,7 +400,6 @@ in the type definition file:
|
|||
proxy:
|
||||
|
||||
address:
|
||||
description: Proxy address
|
||||
type: domainname
|
||||
params:
|
||||
allow_ip: true
|
||||
|
|
@ -411,21 +407,20 @@ in the type definition file:
|
|||
variable: __.http_proxy.address
|
||||
|
||||
port:
|
||||
description: Proxy port
|
||||
type: port
|
||||
default:
|
||||
variable: __.http_proxy.port
|
||||
...
|
||||
|
||||
We can see here, for example, that the `address` and `port` variables don't have
|
||||
any `description` atribute. We need to add one, so we need to extend the type
|
||||
defintions.
|
||||
We can see here, for example, that the `address` and `port` variables don't have
|
||||
any `description` attribute. We need to add one, so we need to extend the type
|
||||
definitions.
|
||||
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_084/firefox/10-manual.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`firefox/10-manual.yml` structure definition file with explicit redefinitions
|
||||
|
||||
..
|
||||
..
|
||||
%YAML 1.2
|
||||
---
|
||||
version: 1.1
|
||||
|
|
@ -451,19 +446,18 @@ defintions.
|
|||
description: HTTP proxy port
|
||||
...
|
||||
|
||||
|
||||
.. note:: Transforming an implicit defintion into an explicit redefinition is very simple; you just need to add the `redefine: true` attribute:
|
||||
|
||||
Let's launch the Rougail CLI:
|
||||
|
||||
.. raw:: html
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/config/01/cmd_ro.txt
|
||||
:class: terminal
|
||||
|
||||
..
|
||||
rougail -m firefox/ -u yaml -yf config/01/config.yml
|
||||
|
||||
We have this output:
|
||||
We have this output:
|
||||
|
||||
.. raw:: html
|
||||
:url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_083/config/01/output_ro.html
|
||||
|
|
@ -471,18 +465,18 @@ We have this output:
|
|||
|
||||
..
|
||||
Variables:
|
||||
┣━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀
|
||||
┣━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀
|
||||
┃ loaded from the YAML file "config/01/config.yml" (⏳ No proxy)
|
||||
┗━━ 📂 Manual proxy configuration
|
||||
┣━━ 📂 HTTP Proxy
|
||||
┃ ┣━━ 📓 HTTP proxy address: http.proxy.net ◀ loaded from the YAML file
|
||||
┃ ┣━━ 📓 HTTP proxy address: http.proxy.net ◀ loaded from the YAML file
|
||||
┃ ┃ "config/01/config.yml"
|
||||
┃ ┗━━ 📓 HTTP proxy port: 3128 ◀ loaded from the YAML file
|
||||
┃ ┗━━ 📓 HTTP proxy port: 3128 ◀ loaded from the YAML file
|
||||
┃ "config/01/config.yml" (⏳ 8080)
|
||||
┣━━ 📓 Also use this proxy for HTTPS: false ◀ loaded from the YAML file
|
||||
┣━━ 📓 Also use this proxy for HTTPS: false ◀ loaded from the YAML file
|
||||
┃ "config/01/config.yml" (⏳ true)
|
||||
┣━━ 📂 HTTPS Proxy
|
||||
┃ ┣━━ 📓 HTTPS proxy address: https.proxy.net ◀ loaded from the YAML file
|
||||
┃ ┣━━ 📓 HTTPS proxy address: https.proxy.net ◀ loaded from the YAML file
|
||||
┃ ┃ "config/01/config.yml" (⏳ http.proxy.net)
|
||||
┃ ┗━━ 📓 HTTPS proxy port: 3128
|
||||
┗━━ 📂 SOCKS Proxy
|
||||
|
|
@ -490,8 +484,8 @@ We have this output:
|
|||
┣━━ 📓 SOCKS proxy port: 3128
|
||||
┗━━ 📓 SOCKS host version used by proxy: v5
|
||||
|
||||
We can see in the output that the `address` and `port` variables have default values,
|
||||
and descriptions ("HTTP proxy address", "HTTP proxy port") that weren't present in the
|
||||
We can see in the output that the `address` and `port` variables have default values,
|
||||
and descriptions ("HTTP proxy address", "HTTP proxy port") that weren't present in the
|
||||
type definition file.
|
||||
|
||||
.. keypoints:: Key points
|
||||
|
|
@ -502,5 +496,17 @@ type definition file.
|
|||
- using a type for an extended family definition
|
||||
- we can redefine things in the structure file and it overloads the type definition file
|
||||
- implicit or explicit redefinitions
|
||||
|
||||
|
||||
We have seen how the definition of type, used effectively, allows for a new expressiveness.
|
||||
|
||||
|
||||
Redefine other parameter in custom type for HTTPS and SOCKS
|
||||
-----------------------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
Now you need to checkout the `v1.1_084` version::
|
||||
|
||||
git switch --detach v1.1_084
|
||||
|
||||
FIXME pareil pour https et socks
|
||||
|
|
|
|||
|
|
@ -18,12 +18,12 @@ Group variables inside families
|
|||
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>`
|
||||
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 switch --detach v1.1_020
|
||||
|
||||
|
|
@ -62,7 +62,7 @@ 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
|
||||
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`::
|
||||
|
||||
.
|
||||
|
|
@ -89,17 +89,17 @@ Let's create a family named `manual` which obviously corresponds to the proxy's
|
|||
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::
|
||||
.. 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 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.
|
||||
|
||||
.. important::
|
||||
|
||||
|
||||
Any family that has been declared in a structure file but is empty (i.e., contains neither :term:`variables <variable>` nor :term:`subfamilies <subfamily>`) is deleted by Rougail, that is is not present in the Rougail CLI output.
|
||||
|
||||
Or a sub family
|
||||
|
|
@ -108,7 +108,7 @@ 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 switch --detach v1.1_021
|
||||
|
||||
.. glossary::
|
||||
|
|
@ -136,7 +136,7 @@ Creating a family hierarchy of families (family inside a family) is very easy:
|
|||
|
||||
:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_021/firefox/00-proxy.yml>`
|
||||
|
||||
Here in our use case we used the :term:`short-hand declaration mode <short-hand notation>`
|
||||
Here in our use case we used the :term:`short-hand declaration mode <short-hand notation>`
|
||||
to declare our `manual` family:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -152,7 +152,7 @@ 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 switch --detach v1.1_022
|
||||
|
||||
We are going to put a variable inside of a family or a sub family
|
||||
|
|
@ -194,14 +194,14 @@ We have reached the definition of the address in the `http_proxy` family; there
|
|||
|
||||
.. type-along:: Assigning a user value
|
||||
|
||||
Now we need to set a value for the :confval:`address` variable,
|
||||
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)
|
||||
|
|
@ -209,14 +209,14 @@ otherwise we will get an error if we try to access this variable:
|
|||
|
||||
.. type-along:: Let's set user values in a user data file
|
||||
|
||||
Here is a user data file sample:
|
||||
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:
|
||||
|
|
@ -231,8 +231,8 @@ Let's validate the consitency of the :term:`configuration`:
|
|||
: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
|
||||
..
|
||||
rougail -m firefox/ -u yaml -yf config/02/config.yml
|
||||
|
||||
Everything is OK:
|
||||
|
||||
|
|
@ -240,7 +240,7 @@ Everything is OK:
|
|||
: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 │
|
||||
|
|
@ -260,13 +260,13 @@ Let's recap about the user data. We can see in this Rougail CLI output that:
|
|||
.. 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 data>`
|
||||
- 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`.
|
||||
- And we have now two variables: :confval:`proxy_mode` and :confval:`address`.
|
||||
|
|
|
|||
|
|
@ -3,10 +3,10 @@ To be continued
|
|||
|
||||
**This tutorial is a work in progress!**
|
||||
|
||||
Not all the concepts of rougail are fully explained in this tutorial.
|
||||
You can, of course, refer to the rest of the technical documentation, or look at
|
||||
the `tutorial's code repository <https://forge.cloud.silique.fr/stove/rougail-tutorials>`_
|
||||
Not all the concepts of rougail are fully explained in this tutorial.
|
||||
You can, of course, refer to the rest of the technical documentation, or look at
|
||||
the `tutorial's code repository <https://forge.cloud.silique.fr/stove/rougail-tutorials>`_
|
||||
and try to understand the rest of the tutorial steps on your own.
|
||||
|
||||
.. note:: Please check again the end of the tutorial section to see if the developers
|
||||
.. note:: Please check again the end of the tutorial section to see if the developers
|
||||
have made any progress in writing it.
|
||||
|
|
|
|||
Loading…
Reference in a new issue