diff --git a/docs/tutorial/customtype.rst b/docs/tutorial/customtype.rst index 66d585e56..b7d4ea8eb 100644 --- a/docs/tutorial/customtype.rst +++ b/docs/tutorial/customtype.rst @@ -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 `, - this workshop page corresponds to the tags :tutorial:`v1.1_080 ` to :tutorial:`v1.1_081 ` + this workshop page corresponds to the tags :tutorial:`v1.1_080 ` to :tutorial:`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 `, we have created a file named :file:`00_type.yml` +In accordance with our :ref:`naming policy `, 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 `. + + +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.