rougail/docs/tutorial/disabled.rst

Disabling things
========================

.. objectives:: Objectives

   In this section we will see what a disabled variable or family is, and why it can be interesting 
   to assign the `disabled` property to a variable or a family. We'll also learn the difference 
   between disabling and hiding families or variables.
   
   We will:
   
   - `disable` a whole family here (yes, a family can disapear in the outerspace!)
   - 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

    - 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_044 <src/tag/v1.1_044>` 
    in the repository.

    ::
   
       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git switch --detach v1.1_040

A disabled family
---------------------------------------------

Disabling and hiding are two families or variables properties. Let's begin with
defining what a property is:

.. glossary::

   property
   
       A property is a state (`disabled`, `mandatory`, `frozen`, `hidden`...)
       of a family, a subfamily or a variable. 
       These properties change the usual behavior of a variable or family.

Here we are going to assign the `disabled` property to the `manual` family: 

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml
   :language: yaml
   :caption: The `manual` family has the `disabled` property set in this :file:`firefox/10-manual.yml` structure file

..
    %YAML 1.2
    ---
    version: 1.1

    manual:
      description: Manual proxy configuration
      disabled: true

      http_proxy:  # HTTP Proxy

        address:
          description: HTTP address
          type: domainname
          params:
            allow_ip: true

        port:
          description: HTTP Port
          type: port
          default: 8080

We have this `disabled: true` property assigned to the `manual` family. 

.. raw:: html
   :class: terminal
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/cmd_ro.txt

.. 
    rougail -m firefox/ -u yaml -yf config/02/config.yml

The Rougail CLI outputs this: 

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/01/output_ro.html
   :class: output

We can deduce from the Rougail CLI output that the `manual` family is not taken into account by Rougail.
Let's first examine what this disabled property does.

.. glossary::

   disabled

       The disabled property is a property that can be assigned to a variable or a family.
       It makes the :term:`configuration` act as if the variable or family that has this property has not even been defined. 
       It simply doesn't exist. It is deactivated for the whole configuration.


.. note:: Note that if a family has been disabled, all variables and sub-families that it contains are disabled.

If we still wanna try to assign values to variables that have been disabled:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/config.yml
   :language: yaml
   :caption: Here in the :file:`config/02/config.yml` user data file, we assign values to disabled variables

If we launch the Rougail CLI:

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/cmd_ro.txt
   :class: terminal

It outputs: 

.. raw:: html
  :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/config/02/output_ro.html
  :class: output

We can see that the Rougail CLI is warning us about the variables that we are trying to assign values on which are disabled.
That is to say, they are not taken into account at the :term:`configuration` level.

If we have a closer look at our use case, we have a choice between five options
in order to set the proxy mode:

.. image:: images/firefox_01.png

These five choices are: 

- No proxy
- Auto-detect proxy settings for this network
- Use system proxy settings
- Manual proxy configuration
- Automatic proxy configuration URL

Actually if the `Manual proxy configuration` is not selected, we don't need to set 
these `address` and `port` variables, there is no point in setting them in 
four out of our five use cases.

We could say that we disable them in order to expose the fact that we don't use them,
but it's not just that: if we fill them in, there might be a problem in the overall integrity of the whole :term:`configuration`.
We shall fill and use in these variables in the `Manual proxy configuration` use case context only. 
Otherwise, **we need to disable them when they are not necessary**.

In a practical point of view, if we fill them in, Rougail CLI will output a warning and the :term:`operator` will see it. 
He will wonder : "oh, what am I doing?", I shall fill and use in these variables only in the `Manual proxy configuration` context. 

.. important:: We need to **disable** variables or families that are not used
               in a given usage context.

.. type-along:: Disabling variables one by one can be replaced by disabling a family

If we don't choose the manual mode, we need to **disable** the whole `manual` family, it will disable 
all the subfamilies and the variables in it. 

Note that we've placed theses variables in the `http_proxy`
subfamily. We can then disable it or even the parent `manual` subfamily in order to 
disable the `http_proxy` family and all the variables that are placed in it, because 
the `manual` family variables shall be used only in the manual proxy use case context.

Notice the `disabled: true` parameter set in the `manual` family:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_040/firefox/10-manual.yml
   :linenos:
   :language: yaml
   :caption: The `http_proxy` subfamily in the :file:`firefox/10-manual.yml` structure file is disabled here

.. 
    ---
    manual:
      description: Manual proxy configuration
      disabled: true

      http_proxy:
        description: HTTP Proxy

        address:
          description: HTTP address
          type: domainname
          params:
            allow_ip: true

        port:
          description: HTTP Port
          type: port
          default: 8080

A conditional disabled family
------------------------------

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

What could be usefull here is a *dynamic setting* of the disable/enable property of the `manual` family. 
The idea in this section is to dynamically set the enable/disable property according to the chosen use case context.

In rougail, we can set a property's value **depending on** the value of another variable. **It is conditioned by** another variable. 

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/firefox/10-manual.yml
   :linenos:
   :language: yaml
   :caption: The :file:`firefox/10-manual.yml` structure file. The `manual` family dynamically enabled or disabled

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

Now the `disabled` property has some parameter defined. First, let's explaine the `variable` parameter. 
This parameter specifies the target variable. The value of this target variable 
will be used to dynamically enable or disable our `manual` family.

We can see here that the `manual` family disabled or enabled property is contitionned by the `_.proxy_mode` variable's value. 
The target variable is `_.proxy_mode`. 

The `.` notation means the path of the family or subfamily  you're currently in.
The `_.` notation means the parent path of the current family or subfamily path.

Regarding the `when_not` parameter, it means that if the target variable's value 
is `Manual proxy configuration` then the `manual` **will not** be disabled (that is, it will be enabled). 

Here as the default value for the `proxy_mode`'s variable is `No proxy`, the `manual` familiy is disabled. 


Let's launch the Rougail CLI on an empty user value file:

.. raw:: html
   :class: terminal
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/cmd_ro.txt

.. 
    rougail -m firefox/ -u yaml -yf config/01/config.ym

We have this output: 

.. raw:: html
   :class: output
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/01/output_ro.html

.. 
    <pre>╭──────────────────── Caption ─────────────────────╮
    │ <span style="color: #ff0000">Undocumented but modified variable</span> <span style="color: #ffd700">Default value</span> │
    ╰──────────────────────────────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┗━━ </span>📓 <span style="color: #ff0000">Configure Proxy Access to the Internet</span>: <span style="color: #ffd700">No proxy</span>
    </pre>

We can see that the `manual` family and all the variables into it are not present.

.. type-along:: Dynamically enabling the `manual` family

If the manual mode for the proxy is not selected, then the `manual` family is disabled.
On the other hand, if the manual proxy's configuration mode is selected, 
then the `manual` family is re-activated (enabled).

Now we are going to select the ** manual mode**, that is the `Manual proxy configuration` 
value for the `proxy_mode` variable, and things will become slightly different.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_041/config/02/config.yml
   :linenos:
   :language: yaml
   :caption: The `proxy_mode`'s manual setting in the :file:`config/02/config.yaml` user datas file

..
    ---
    proxy_mode: Manual proxy configuration
    manual:
      http_proxy:
        address: http.proxy.net
        port: 3128
    use_for_https: false

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

.. rubric:: Explanation

Here the `disabled` property **depends on** the value of the `proxy_mode` variable. 
It is the `variable` parameter that allows you to define the name of the target variable on which the `disabled` property depends.

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 

Here is the new :file:`20-manual.yml` file:

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

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/config.yml
   :linenos:
   :language: yaml
   :caption: User datas in the user data file :file:`config/01/config.yml` with `use_for_https` as false

..
    ---
    proxy_mode: Manual proxy configuration
    manual:
      http_proxy:
        address: http.proxy.net
        port: 3128
      use_for_https: false
      https_proxy:
        address: https.proxy.net

If we launch the Rougail CLI: 

.. raw:: html
   :class: terminal
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/cmd_ro.txt

.. 
    rougail -m firefox/ -u yaml -yf config/01/config.yml

We have this output: 

.. raw:: html
   :class: output
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/01/output_ro.html
   
..
    <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"
    <span style="color: #5c5cff">    </span><span style="color: #5c5cff">    </span><span style="color: #5c5cff">┗━━ </span>📓 port (HTTPS Port): <span style="color: #ffd700">8080</span>
    </pre>

Notice that we have a `use_for_https` new variable, this variable is a `boolean` type, its default value is `True`.
We want to offer the possibility of providing an identical or possibly different proxy configuration for the HTTP and for the HTTPS protocols. 

Here is an example with identical HTTP and HTTPS proxy configuration:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/config.yml
   :linenos:
   :language: yaml
   :caption: User datas in the user data file :file:`config/02/config.yml` with `use_for_https` as true

..
    ---
    proxy_mode: Manual proxy configuration
    manual:
      http_proxy:
        address: http.proxy.net
        port: 3128
      use_for_https: true

Let's launch the Rougail CLI:

.. raw:: html
   :class: terminal 
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/cmd_ro.txt

.. 
    rougail -m firefox/ -u yaml -yf config/02/config.yml

We have this output: 

.. raw:: html
   :class: output
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_043/config/02/output_ro.html
   
FIXME: il y a un <span> dans le <pre>

.. 
    <pre>&gt; [!CAUTION]
    &gt; 
    &gt; - manual (Manual proxy configuration)
    &gt;   - https_proxy (HTTPS Proxy)
    &gt;     - address (HTTPS address): :stop_sign: &lt;span style="color: #C23636"&gt;mandatory variable but is inaccessible and has no value&lt;/span&gt;
    </pre>

We are going to see how to point HTTPS variables to HTTPS variables
   
A conditional hidden family
----------------------------

Now we will focus on configuring the HTTPS mode in case of `"Manual proxy configuration"` value has been chosen.

.. image:: images/firefox_manual_https.png

We have added two other variables for the HTTPS use only: 

.. confval:: https_proxy.address
   :type: `domainname`

   This is an address setting for the manual HTTPS configuration

.. confval:: https_proxy.port
   :type: `port`

   This is a port setting for the manual HTTPS configuration

We have now two very similar variables, a `manual.http_proxy.address` variable and a `manual.https_proxy.address` variable
In the same way, we have a `manual.http_proxy.port` variable and a `manual.https_proxy.port` variable.

Let's introduce a new Rougail concept here:

.. glossary:: 

   context
   
       A :term:`configuration` is highly statefull and can change at any moment.
       Sometimes somes minor changes in the :term:`user datas <user data>` may involve chain reactions 
       in the whole :term:`configuration`.
       The **context** is the state of the user datas at one moment, the set of the values of the variables
       at a given moment. This term also refers to the ability of a system to handle 
       the *statefull* state of a configuration. 
       It expresses the transition between one situation to another situation, 
       that is, the deeply **statefull** aspects of a data set.


.. type-along:: A new variable which has the `boolean` type

The best way to reproduce the `"Also use this HTTP proxy variables for HTTPS"` checkbox in the firefox interface
is to add a boolean variable in our structure. A boolean variable can reproduce this binary choice option.

Do we want to reuse, for the HTTPS mode, the same configuration as for the HTTP mode?
Well, it depends on the :term:`context`. 

We have added a new variable, named `use_for_https` here:

.. confval:: use_for_https
   :type: `boolean`
   :default: `true`

   This is a setting that enables to reuse or not the HTTP proxy configuration for HTTPS

.. questions:: Question: how does it work? 

   How will this variable drive the reuse of HTTP data to HTTPS data?

With this :confval:`use_for_https` boolean variable, there are two possibilities, and only two: 

- The http proxy's configuration will be reused for the https proxy's configuration
- The http proxy's will not be reused for the https proxy's configuration

.. questions:: Question: shall we use the `disabled` property here?

   Is it relevant to use the :term:`disabled property <disabled>` here? 
   
   **answer**: No! Because we *need* to use these variables at any :term:`context` of the proxy's manual configuration use case, 
   we simply have to point their values ​​in one direction or another depending on this or that context,
   that's why it is absolutely not a question of deactivating them. The `manual.https_proxy.address` 
   and the `manual.http_proxy.port` variables shall not be disabled (deactivated) in the manual mode. 

Let's introduce a new concept here:

.. glossary:: 

   hidden
   
       A variable or family's property is hidden if its value **shall not be seen** in a given :term:`context`. 
       Anyway, these variables can be used if the context evolves. This is the main difference 
       between the `hidden` and the `disabled` properties (with the `disabled` property, the variables are *deactivated*.

Now we can set a `hidden` property to the `https_proxy` family:

Here is our new :file:`20-manual.yml` structure file:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_043/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.

We have now a `hidden` property assigned to the `https_proxy` family. 
The variable that drives the hidden/show behavior is the `use_for_https` variable because the `hidden` property has 
a `variable` target parameter: `variable: _.use_for_https`

.. prerequisites:: Reminder

   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.

We also say that the default value is *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. 

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


.. keypoints:: Key points progress

    **summary**
    
    We have now the ability to build a contextual setting:

    - if the `proxy_mode` variable's value is not `'Manual proxy configuration'` the `manual` family is disabled
    - if the `proxy_mode` variable's value is `'Manual proxy configuration'` then the `manual` family is enabled

    - FIXME add the hidden steps

    We have arrived at the end of the proxy's manual configuration's section.

    **Keywords**
    
    - We now know what a *property* is, we have seen in details the :term:`disabled` property
    - We can target a variable's value in the `disabled` property's value,
      we call it a variable based contextual disabled family
    - The :term:`hidden` property set to a family
    - The fact that a property can be set dynamically
    - The conditional dependency of a `hidden` property that depends on a `boolean` variable.
    - A calculated default value