From 65009bb6f70c8304da8965bfd968ce7f07e91871 Mon Sep 17 00:00:00 2001
From: gwen <gwenaelremond@free.fr>
Date: Tue, 12 May 2026 12:04:47 +0200
Subject: [PATCH] nullable

---
 docs/tutorial/customtype.rst |   2 +
 docs/tutorial/index.rst      |   1 +
 docs/tutorial/nullable.rst   | 106 +++++++++++++++++++++++++++++++++++
 3 files changed, 109 insertions(+)
 create mode 100644 docs/tutorial/nullable.rst

diff --git a/docs/tutorial/customtype.rst b/docs/tutorial/customtype.rst
index 74363c239..d91b8484a 100644
--- a/docs/tutorial/customtype.rst
+++ b/docs/tutorial/customtype.rst
@@ -208,6 +208,8 @@ Redefine default value in custom type variable
 
 In this section we are going to make an implicit redefinition of variables default values.
 
+.. FIXME deplacer cette definition dans la page generique sur le redefine à venir 
+
 .. glossary::
 
    redefine
diff --git a/docs/tutorial/index.rst b/docs/tutorial/index.rst
index 4b5151fcc..a37ee8903 100644
--- a/docs/tutorial/index.rst
+++ b/docs/tutorial/index.rst
@@ -56,4 +56,5 @@ Let's dive into this **configuration options validation** use case.
    dynfam
    jinja
    customtype
+   nullable
    whatsnext
diff --git a/docs/tutorial/nullable.rst b/docs/tutorial/nullable.rst
new file mode 100644
index 000000000..e98b45266
--- /dev/null
+++ b/docs/tutorial/nullable.rst
@@ -0,0 +1,106 @@
+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.
+