type declarations

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 <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.