Calculated default value for a variable
============================================


.. objectives:: Objectives

   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

    - We assume that Rougail's library is :ref:`installed <installation>` on your computer.

    - It is possible to retrieve the current state of the various Rougail files manipulated in this tutorial step
      by checking out the corresponding tag of the `rougail-tutorials` git repository.
      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_040 <src/tag/v1.1_040>` to :tutorial:`v1.1_041 <src/tag/v1.1_041>` 
    in the repository.

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

..
    <pre>╭────────────── Caption ───────────────╮
    │ Variable <span style="color: #ffd700">Default value</span>               │
    │          <span style="color: #00aa00">Modified value</span>              │
    │          (⏳ Original default value) │
    ╰──────────────────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┣━━ </span>📓 proxy_mode (Configure Proxy Access to the Internet): <span style="color: #00aa00">Manual proxy </span>
    <span style="color: #5c5cff">┃   </span><span style="color: #00aa00">configuration</span> ◀ loaded from the YAML file "config/01/config.yml" (⏳ No 
    <span style="color: #5c5cff">┃   </span>proxy)
    <span style="color: #5c5cff">┗━━ </span>📂 manual (Manual proxy configuration)
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📂 http_proxy (HTTP Proxy)
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTP address): <span style="color: #00aa00">http.proxy.net</span> ◀ loaded from the YAML 
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┃   </span>file "config/01/config.yml"
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTP Port): <span style="color: #00aa00">3128</span> ◀ loaded from the YAML file 
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span><span style="color: #5c5cff">    </span>"config/01/config.yml" (⏳ 8080)
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📓 use_for_https (Also use this proxy for HTTPS): <span style="color: #00aa00">false</span> ◀ loaded from 
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span>the YAML file "config/01/config.yml" (⏳ true)
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📂 https_proxy (HTTPS Proxy)
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┣━━ </span>📓 address (HTTPS address): <span style="color: #00aa00">https.proxy.net</span> ◀ loaded from the YAML 
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┃   </span>file "config/01/config.yml" (⏳ http.proxy.net)
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTPS Port): <span style="color: #ffd700">3128</span>
    </pre>

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.