diff --git a/docs/tutorial/calculated.rst b/docs/tutorial/calculated.rst index 75e3d2e6c..a252fe651 100644 --- a/docs/tutorial/calculated.rst +++ b/docs/tutorial/calculated.rst @@ -4,7 +4,9 @@ Calculated default value for a variable .. objectives:: Objectives - FIXME + In this section we will reuse a value of a variable for another variable. + In fact in this use case we will reuse the default value of a variable + in order to define a default value of another variable. .. prerequisites:: Prerequisites @@ -24,4 +26,214 @@ Calculated default value for a variable git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git git switch --detach v1.1_040 +HTTPS family +------------- + +We have split the definition of the `manual` familiy into two specific files, +the :file:`10-manual.yml` and the :file:`20-manual.yml` structure file: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html + +Here is the new :file:`20-manual.yml` file, which looks like the :file:`10-manual.yml` file +except that it is dedicated to the HTTPS protocol: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_040/firefox/20-manual.yml + :linenos: + :language: yaml + :caption: The updated `manual` family in the :file:`firefox/20-manual.yml` structure file with the `https_proxy` family. + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + https_proxy: # HTTPS Proxy + + address: + description: HTTPS address + type: domainname + params: + allow_ip: true + + port: + description: HTTPS Port + type: port + default: 8080 + +This `https_proxy` family is identical to the `http_proxy` family except that it defines variables intended for the HTTPS protocol. + +Calculated default values +------------------------------ + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_041` version:: + + git switch --detach v1.1_041 + +.. discussion:: A contextualized default value + + A contextualized default value is a default value of a variable that has the value of another variable. + This variable type and its parameters type are copied in the default value's target variable. + +The dynamic setting of a default can be expressed this way: the default value is a pointer to another variable's value. +Here, the defaut value of `manual.https_proxy.address` points to the default value of `manual.http_proxy.address`. + +This is the same thing for the default value of the `manual.https_proxy.port` variable, +which points to the `manual.http_proxy.port` default value. + +Reminder: here is the HTTP :file:`firefox/10-manual.yml` structure file: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_041/firefox/10-manual.yml + :linenos: + :language: yaml + :caption: The :file:`firefox/10-manual.yml` structure file with the `http_proxy` family and the `disabled` property + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: # Manual proxy configuration + + http_proxy: # HTTP Proxy + + address: + description: HTTP address + type: domainname + params: + allow_ip: true + + port: + description: HTTP Port + type: port + default: 8080 + ... + + +And here is the :file:`firefox/20-manual.yml` structure files where the calculated default values are: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_041/firefox/20-manual.yml + :linenos: + :language: yaml + :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family. + +.. + %YAML 1.2 + --- + version: 1.1 + + manual: + + use_for_https: true # Also use this proxy for HTTPS + + https_proxy: # HTTPS Proxy + + address: + description: HTTPS address + default: + variable: __.http_proxy.address + + port: + description: HTTPS Port + default: + variable: __.http_proxy.port + ... + +We can see here that the `address` variable's default value is contitionned by the `__.http_proxy.address` variable's value. +The target variable is `http_proxy.address`. + +.. note:: The `__.` notation means the parent path of the current subfamily path. + +We then say that the `manual.https_proxy.address` and the the `manual.https_proxy.port` default values are *calculated*. + +.. glossary:: + + calculated + + We say that a variable's value or a default variable's value is calculated + when there is a pointer which refers to another variable's value + or if there is some :term:`jinja` code or a python function that calculates it. + +Notice that the default value is not changed when :term:`user data ` are settled. + +If we set this :term:`user data`: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_041/config/01/config.yml + :linenos: + :language: yaml + :caption: The :file:`config/01/config.yml` user data + +.. + --- + proxy_mode: Manual proxy configuration + manual: + http_proxy: + address: http.proxy.net + port: 3128 + use_for_https: false + https_proxy: + address: https.proxy.net + +Let's launch the Rougail CLI on it: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_041/config/01/cmd_ro.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/01/config.yml + +We have this result: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_041/config/01/output_ro.html + :class: output + +.. + 
╭────────────── Caption ───────────────╮
+    │ Variable Default value               │
+    │          Modified value              │
+    │          (⏳ Original default value) │
+    ╰──────────────────────────────────────╯
+    Variables:
+    ┣━━ 📓 proxy_mode (Configure Proxy Access to the Internet): Manual proxy 
+    ┃   configuration ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
+    ┃   proxy)
+    ┗━━ 📂 manual (Manual proxy configuration)
+        ┣━━ 📂 http_proxy (HTTP Proxy)
+        ┃   ┣━━ 📓 address (HTTP address): http.proxy.net ◀ loaded from the YAML 
+        ┃   ┃   file "config/01/config.yml"
+        ┃   ┗━━ 📓 port (HTTP Port): 3128 ◀ loaded from the YAML file 
+        ┃       "config/01/config.yml" (⏳ 8080)
+        ┣━━ 📓 use_for_https (Also use this proxy for HTTPS): false ◀ loaded from 
+        ┃   the YAML file "config/01/config.yml" (⏳ true)
+        ┗━━ 📂 https_proxy (HTTPS Proxy)
+            ┣━━ 📓 address (HTTPS address): https.proxy.net ◀ loaded from the YAML 
+            ┃   file "config/01/config.yml" (⏳ http.proxy.net)
+            ┗━━ 📓 port (HTTPS Port): 3128
+
+ +We see that the default value is not changed. + +.. keypoints:: Key points progress + + **summary** + + We have learned how to set the default value of the `https_proxy.address` variable + with the default value of the `http_proxy.address` variable. We did the same + `https_proxy.port` and the `https_proxy.port` variables. + + **notation** + + We have learned a notation very usefull for the subfamilies traversal: + + - the `_.` notation means the current path of the family you're currently in + - the `__.` notation means the parent path of the current subfamily path. diff --git a/docs/tutorial/disabled.rst b/docs/tutorial/disabled.rst index 8123378c4..b3bd998e6 100644 --- a/docs/tutorial/disabled.rst +++ b/docs/tutorial/disabled.rst @@ -11,8 +11,6 @@ Define access to variable or family - create a `disabled` family - use a new family or variable's property: the `hidden` property - - reuse a value of a variable for another variable - (in this use case we will reuse the HTTP configuration variables values for the configuration of the HTTPS). .. prerequisites:: Prerequisites @@ -342,59 +340,13 @@ Please remember that this activation/deactivation of the `manual` family depends on the value of the `proxy_mode` variable. Here we have chosen the `Manual proxy configuration` value, so the `address` and `port` variables appear. -Copy HTTP manual proxy to HTTPS manual proxy ---------------------------------------------- - -.. type-along:: For those who follow the tutorial with the help of the git repository - - Now you need to checkout the `v1.1_042` version:: - - git switch --detach v1.1_042 -We have split the definition of the `manual` familiy into two specific files: -.. raw:: html - :class: output - :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/tree.html +FIXME -Here is the new :file:`20-manual.yml` file, which looks like the :file:`10-manual.yml` file -except that it is dedicated to the HTTPS protocol: -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_042/firefox/20-manual.yml - :linenos: - :language: yaml - :caption: The updated `manual` family in the :file:`firefox/20-manual.yml` structure file with the `https_proxy` family. -.. - %YAML 1.2 - --- - version: 1.1 - - manual: - - use_for_https: true # Also use this proxy for HTTPS - - https_proxy: # HTTPS Proxy - - address: - description: HTTPS address - type: domainname - params: - allow_ip: true - - port: - description: HTTPS Port - type: port - default: 8080 - -This `https_proxy` family is identical to the `http_proxy` family except that it defines variables intended for the HTTPS protocol. - -.. type-along:: For those who follow the tutorial with the help of the git repository - - Now you need to checkout the `v1.1_043` version:: - - git switch --detach v1.1_043 Here is an example with different user values for handling HTTP and HTTPS: @@ -603,111 +555,6 @@ a `variable` target parameter that points to it: `variable: _.use_for_https`. The underscore and the point before the variable (`_.use_for_https`) points to the variable that lives in the parent family. -Variable type and parameters type are copied with default value ------------------------------------------------------------------- - -.. type-along:: For those who follow the tutorial with the help of the git repository - - Now you need to checkout the `v1.1_044` version:: - - git switch --detach v1.1_044 - -.. discussion:: A contextualized default value - - A contextualized default value is a default value (of a variable) that is driven by another variable. - This variable type and its parameters type are copied in the default value's target variable. - -There is something left in the https configuration mode of the proxy: - -- if the use of the proxy variables for https are the same of the proxy variables for http, - that is, if `use_for_https` is true, the https configuration variables are hidden, that's OK. -- if the use of the proxy variables for https **are not** the same of the proxy variables for http, - we would like to set their default values to the http proxy variables values. - -The dynamic setting of a default can be achieved in this way: the default value is a pointer to another variable's value. -Here, the defaut value of `manual.https_proxy.address` points to `manual.http_proxy.address`. - -This is the same thing for the default value of the `manual.https_proxy.port` variable, -which points to the `manual.http_proxy.port` value. - -To summarize the HTTP and HTTPS configuration in the manual use case context, -here are the two :file:`firefox/10-manual.yml` and :file:`firefox/20-manual.yml` structure files: - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/10-manual.yml - :linenos: - :language: yaml - :caption: The :file:`firefox/10-manual.yml` structure file with the `http_proxy` family and the `disabled` property - -.. - %YAML 1.2 - --- - version: 1.1 - - manual: - description: Manual proxy configuration - disabled: - variable: _.proxy_mode - when_not: Manual proxy configuration - - http_proxy: # HTTP Proxy - - address: - description: HTTP address - type: domainname - params: - allow_ip: true - - port: - description: HTTP Port - type: port - default: 8080 - ... - - -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_044/firefox/20-manual.yml - :linenos: - :language: yaml - :caption: The :file:`firefox/20-manual.yml` structure file with the `hidden` property on the `https_proxy` family. - -.. - %YAML 1.2 - --- - version: 1.1 - - manual: - - use_for_https: true # Also use this proxy for HTTPS - - https_proxy: - description: HTTPS Proxy - hidden: - variable: _.use_for_https - - address: - description: HTTPS address - default: - variable: __.http_proxy.address - - port: - description: HTTPS Port - default: - variable: __.http_proxy.port - ... - -We can see here that the `address` variable's default value is contitionned by the `__.http_proxy.address` variable's value. -The target variable is `http_proxy.address`. - -The `__.` notation means the parent path of the current subfamily path. - -.. note:: We also say that the `manual.https_proxy.address` and the the `manual.https_proxy.port` default values are *calculated*. - -.. glossary:: - - calculated - - We say that a variable's value or a default variable's value is calculated - when there is a pointer which refers to another variable's value - or if there is some :term:`jinja` code or a python function that calculates it. .. keypoints:: Key points progress