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 will disable a whole family here (yes, a family can disapear in the outerspace). .. prerequisites:: Prerequisites - We assume that Rougail's library is :ref:`installed ` 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 `, this workshop page corresponds to the tags :tutorial:`v1.1_040 ` to :tutorial:`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 --------------------------------------------- First, a definition: .. 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 that the variables we are trying to assign values on 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 .. 
╭──────────────────── Caption ─────────────────────╮
    │ Undocumented but modified variable Default value │
    ╰──────────────────────────────────────────────────╯
    Variables:
    ┗━━ 📓 Configure Proxy Access to the Internet: No proxy
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 :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. 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 the same proxy configuration for the HTTP and the HTTPS requests. A conditional hidden family ---------------------------- .. 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 .. 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 **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