rougail/docs/tutorial/calculated.rst

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 

As a reminder, here is the :file:`20-manual.yml` structure file, which looks like the :file:`10-manual.yml` file
except that it is dedicated to the HTTPS protocol :ref:`and a boolean variable that we saw earlier <boolean_variable>`:

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

A default value calculated from another variable
--------------------------------------------------

.. 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 `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.
       
        :ref:`Other types of calculations exists <calculated_variable>`, in which this type of behavior does not occur 
        (the "pointer" behavior, notably type copying). 

The other types of calculation we will be explained later in this tutorial.

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>

The `https_proxy` variable's value is indeed modified, but the default value is still a calculated value (so the default value is indeed the value of the variable `http_proxy.address`, i.e., `"http.proxy.net"`), while the value defined by the user is `https.proxy.net`.

Here we see that the variable's default value is not changed, but rather its actual value.
   
.. keypoints:: Key points progress

    **summary**

    We have learned how to set the default value of the `https_proxy.address` variable 
    with the 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.