Nullable variable
==========================

.. objectives:: 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 setttings have no value (nothing, null, None), 
   that is, neither an assigned value nor a default value.
   
.. 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_090 <src/tag/v1.1_090/README.md>` to :tutorial:`v1.1_091 <src/tag/v1.1_091/README.md>`
    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 :term:`mandatory` by default, 
         meaning that it must either have a default value set or a :term:`user data` value assigned in the :term:`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.

We need to:

- explicitely disable the default :term:`mandatory` behavior (we will set it to `false`,
- redefine the 
- define a default value of None (null).

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_090/firefox/20-manual.yml
   :language: yaml
   :caption: The :file:`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
    ...


Here are somme maybe usefull explanations: 

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