type declarations
This commit is contained in:
gwen
parent
2608958574
commit
9c0ee92892
1 changed files with 158 additions and 16 deletions
|
|
@ -16,7 +16,7 @@ Custom type
|
|||
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_081 <src/tag/v1.1_081>`
|
||||
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.
|
||||
|
||||
::
|
||||
|
|
@ -44,18 +44,18 @@ Our folder structure will be expanded a bit:
|
|||
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.
|
||||
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`
|
||||
In accordance with our :ref:`naming policy <namingconvention>`, we have created a file named :file:`00-type.yml`
|
||||
inside the `proxy` folder.
|
||||
Let's examine this more closely this :file:`types/proxy/00_type.yml` type definition file:
|
||||
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
|
||||
.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_080/types/proxy/00-type.yml
|
||||
:language: yaml
|
||||
:caption: The :file:`types/proxy/00_type.yml` type structure file that defines our new `proxy` type.
|
||||
:caption: The :file:`types/proxy/00-type.yml` type structure file that defines our new `proxy` type.
|
||||
|
||||
..
|
||||
%YAML 1.2
|
||||
|
|
@ -145,13 +145,11 @@ We want the same behavior as usual.
|
|||
|
||||
The type definition adds nothing to the structural logic. It's just a very convenient way to save time when writing structure files.
|
||||
|
||||
.. FIXME Ici nous avons juste changé la valeur des deux variables
|
||||
|
||||
.. 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` defines the :file:`manual.https_proxy` family
|
||||
The :file:`10-manual.yml` structure file defines the :file:`manual.https_proxy` family
|
||||
which is defined with the help of the `proxy` type:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
|
@ -160,7 +158,7 @@ which is defined with the help of the `proxy` type:
|
|||
description: HTTP Proxy
|
||||
type: proxy
|
||||
|
||||
In the :file:`types/proxy/00_type.yml` file we have the `proxy` type definition and its default value setting:
|
||||
In the :file:`types/proxy/00-type.yml` file we have the `proxy` type definition and its default value setting:
|
||||
|
||||
.. code-block:: yaml
|
||||
|
||||
|
|
@ -193,8 +191,9 @@ finally set by the user data file:
|
|||
┃ ┃ file "config/01/config.yml"
|
||||
|
||||
|
||||
HTTPS and SOCKS Proxy
|
||||
-----------------------
|
||||
|
||||
Add a variable in a family with custom type
|
||||
--------------------------------------------------
|
||||
|
||||
.. type-along:: For those who follow the tutorial with the help of the git repository
|
||||
|
||||
|
|
@ -235,7 +234,9 @@ With this use of a type, it is possible to define our HTTPS and SOCKS Proxy in a
|
|||
default: v5
|
||||
...
|
||||
|
||||
In the `socks_proxy` family definition, we can see that we have added a new variable,
|
||||
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
|
||||
|
|
@ -247,15 +248,156 @@ the `version` variable:
|
|||
- v5
|
||||
default: v5
|
||||
|
||||
You can see that the type definition here is flexible : it is perfectly possible
|
||||
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 is therefore not only a template but much more an extensible schema.
|
||||
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
|
||||
|
||||
In this sections we are going to make explicit :term:`redefinitions <redefine>`.
|
||||
|
||||
|
||||
FIXME : redéfinition explicites.
|
||||
|
||||
|
||||
.. keypoints:: Key points
|
||||
|
||||
- the very practical aspects of type declaration
|
||||
- type usage
|
||||
- type usage in the Rougail CLI
|
||||
- more conscious family definition
|
||||
- using a type for an extended family definition
|
||||
- we can redefine things in the structure file and it overloads the type definition file
|
||||
|
||||
We have seen how the definition of type, used effectively, allows for a new expressiveness.
|
||||
|
|
|
|||
Loading…
Reference in a new issue