Nullable variable

Objectives

Now in this section we would like to make it possible that it is not necessary to specify a value for a variable.

With Rougail, it is possible for a variable’s settings to have no value (nothing, null, None), that is, neither a default value nor a user assigned value.

Prerequisites

  • We assume that Rougail’s library is 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 rougail-tutorials git repository, this workshop page corresponds to the tags v1.1_090 to v1.1_091 in the repository.

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

Variable with the value “null”

Note

It is important to keep in mind that in Rougail a variable is mandatory by default, meaning that it must either have a default value set or a user data value assigned for example in a user data file. This is Rougail’s default behavior.

Besides, note that the explicit keyword to express the setting “no value, nothing” in YAML is the null explicit keyword.

Here is how we are going to specify a “no value” (nothing, null) as a possible setting for the address variable in the socks_proxy family.

There are a few things to set in the variable. We need to:

  • explicitely disable the default mandatory behavior of the address variable (just by setting it to false),

  • redefine the address variable inside the socks_proxy because this family uses the proxy type definition,

  • finally removes the address default value as determined in the proxy type definition.

The firefox/20-manual.yml structure file with the mandatory set to false and the null (nothing) setting
%YAML 1.2
---
version: 1.1

manual:

  use_for_https: true  # Also use this proxy for HTTPS

  https_proxy:
    description: HTTPS Proxy
    type: proxy
    hidden:
      variable: _.use_for_https

    address:
      redefine: true
      description: HTTPS proxy address

    port:
      redefine: true
      description: HTTPS proxy port

  socks_proxy:
    description: SOCKS Proxy
    type: proxy

    address:
      redefine: true
      description: SOCKS proxy address
      default: null
      mandatory: false

    port:
      redefine: true
      description: SOCKS proxy port
      default: 1080

    version:
      description: SOCKS host version used by proxy
      choices:
        - v4
        - v5
      default: v5
...

Some more, maybe usefull, explanations about our address variable in the socks_proxy family:

  • Allowing the “no value, nothing” behavior is easy, we just add the mandatory: false attribute,

  • we explicitely need to set the redefine: true attribute because in the type proxy type setting we didn’t set the mandatory attribute to false, this is then a type redefinition,

  • finally we can set the default: null that means that we can set no value to our address variable.

Note too that is is necessary to redefine (to set a redefine attribute) as soon as you modify the type definition. Here we have set a default value to our socks_proxy’s port variable. We need then to redefine not only because of the description attribute but because of the default value too.

Variables disabled when condition is null

For those who follow the tutorial with the help of the git repository

Now you need to checkout the v1.1_091 version:

git switch --detach v1.1_091

Question

But actually, why did we want a variable to be non-mandatory?

Well, what we need is to be able to disable either the port and the version in case of the address has no value set:

The firefox/20-manual.yml structure file with the disabled set in case of the address has no value set
%YAML 1.2
---
version: 1.1

manual:

  use_for_https: true  # Also use this proxy for HTTPS

  https_proxy:
    description: HTTPS Proxy
    type: proxy
    hidden:
      variable: _.use_for_https

    address:
      redefine: true
      description: HTTPS proxy address

    port:
      redefine: true
      description: HTTPS proxy port

  socks_proxy:
    description: SOCKS Proxy
    type: proxy

    address:
      redefine: true
      description: SOCKS proxy address
      default: null
      mandatory: false

    port:
      redefine: true
      description: SOCKS proxy port
      default: 1080
      disabled:
        variable: _.address
        when: null

    version:
      description: SOCKS host version used by proxy
      choices:
        - v4
        - v5
      default: v5
      disabled:
        variable: _.address
        when: null
...

For the disabled property to trigger, the condition when: null must appear, pointing to the _.address variable, that is the socks_proxy.address variable.

Note

The _. notation means the current path (of the current family).

As we are in the socks_proxy family, we can say:

_.address == socks_proxy.address

Key points

As one of the main objectives of Rougail is to determine if a variable has a value, therefore the value of a variable is in principle required. We say that a value is mandatory by default. However, it is possible to change this default behavior with the mandatory: false parameter explicitely declared in a variable. In this section we learned how to define a variable as having no value; it’s possible with Rougail.

In this section we also continued using some type redefinition, which we learned in the previous section. And we have disabled a variable depending this on the presence or absence of a value.