From be4983e524517ad0d24aed86f808a42095651c5d Mon Sep 17 00:00:00 2001 From: gwen Date: Tue, 2 Dec 2025 11:08:54 +0100 Subject: [PATCH] domain name type --- docs/tutorial/domainname.rst | 204 +++++++++++++++++++++++++++++++---- docs/tutorial/family.rst | 5 +- 2 files changed, 183 insertions(+), 26 deletions(-) diff --git a/docs/tutorial/domainname.rst b/docs/tutorial/domainname.rst index 3b0a47287..8d0668e67 100644 --- a/docs/tutorial/domainname.rst +++ b/docs/tutorial/domainname.rst @@ -1,43 +1,204 @@ -Variable types and parameters +A variable with type `domainname` ================================== .. objectives:: Objectives - FIXME + Discover new types of variables. +.. prerequisites:: Prerequisites + - We assume that Rougail's library is :ref:`installed ` on your computer. -.. type-along:: Variables can have parameters + - 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. -.. questions:: Question + 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_030 ` to :tutorial:`v1.1_033 ` + in the repository. - **question**: Does our `address` domain name variable accepts IP addresses ? + :: + + git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git + git checkout v1.1_030 - **answer**: Well it depends. +.. type-along:: let's recap how far we've come -We need to specify whether our variable accepts to be filled using an IP or a domain name only. -This is where the ability to parameterize our variable comes in. +We have an `http_proxy` family with an `address` variable -.. type-along:: let's create a variable parameter named `allow_ip` +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/firefox/10-manual.yml + :language: yaml + :caption: An `address` variable in the `http_proxy` family + +.. + manual: # Manual proxy configuration + http_proxy: # HTTP Proxy + address: + description: HTTP address + type: domainname + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +And we have assigned a type to this variable: + +.. code-block:: yaml + :linenos: + :caption: The `address` variable with the `domainname` type assigned + + address: + type: domainname + +Assigning a type is convenient for reading, but what else does it bring? + +Well, with a correct user data like this one, + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/01/config.yml + :language: yaml + :caption: A domain name user data setting .. --- manual: - description: Manual proxy configuration - http_proxy: - description: HTTP Proxy + address: net.example - address: - description: HTTP address - type: domainname - params: - allow_ip: true +:tutorial:`Download this file from the rougail-tutorials git repository ` -.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_034/firefox/10-manual.yml +if we launch the rougail CLI on it: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/01/cmd_ro.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/01/config.yml + +We have this output: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/01/output_ro.html + :class: output +.. + 
╭──────── Caption ────────╮
+    │ Variable Default value  │
+    │          Modified value │
+    ╰─────────────────────────╯
+    Variables:
+    ┣━━ 📓 Configure Proxy Access to the Internet: No proxy
+    ┗━━ 📂 Manual proxy configuration
+        ┗━━ 📂 HTTP Proxy
+            ┗━━ 📓 HTTP address: example.net ◀ loaded from the YAML file 
+                "config/01/config.yml"
+
+ + +And we don't really see any change. But if we assign this user data: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/02/config.yml :language: yaml - :caption: The `address` has a parameter set in the :file:`firefox/10-manual.yml` structure file - :name: RougailAddressParameter + :caption: A domain name user data setting with an IP address + +.. + --- + manual: + http_proxy: + address: 19.168.230.51 + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +that is, with a value that is not a domain name, then when we will launch the rougail CLI +we will see a difference: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/02/cmd_invalid.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/02/config.yml --cli.invalid_user_datas_error + +we then have this output: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/02/output_invalid.html + :class: error + +.. + 
🛑 ERRORS
+    ┗━━ the value "192.168.0.1" is an invalid domain name for 
+        "manual.http_proxy.address" (HTTP address), must not be an IP, it will be 
+        ignored when loading from the YAML file "config/02/config.yml"
+
+ +We observe that an error has been raised because an IP address is not a domain name. +Therefore, a type validation is taking place because we declared the type `domainname`. + +.. type-along:: A domain name has no space in it + +Let's have a look at another example of user setting that does not fit the +`domainname` type: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/03/config.yml + :language: yaml + :caption: An invalid domain name user data setting + +.. + --- + manual: + http_proxy: + address: bla bla + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +The value is obviously not a domain name, then when we will launch the rougail CLI: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/03/cmd_invalid.txt + :class: terminal + +.. + rougail -m firefox/ -u yaml -yf config/03/config.yml --cli.invalid_user_datas_error + +we then have this output: + +.. raw:: html + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/03/output_invalid.html + :class: error + +.. + 
🛑 ERRORS
+    ┗━━ the value "bla bla" is an invalid domain name for 
+        "manual.http_proxy.address" (HTTP address), must not be an IP, it will be 
+        ignored when loading from the YAML file "config/02/config.yml"
+
+ +.. type-along:: A variable with type's parameters + +.. questions:: Question + + OK I agree with the `domainname` type, but what if I want to specify + an IP address as a user value for this `address` variable? + Because it is therefore simply impossible to do so. + + Is there a way for my `address` variable to accept an IP address? + +Well, it is possible to configure the type so that it accepts IP addresses. +We need to specify whether our variable accepts to be filled using an IP or a domain name only. +This is where the ability to parameterize our variable comes in. + +.. rubric:: Let's add a type parameter. + +.. type-along:: For those who follow the tutorial with the help of the git repository + + Now you need to checkout the `v1.1_031` version:: + + git checkout v1.1_031 + +Let's add a type parameter named `allow_ip`: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_031/firefox/10-manual.yml + :language: yaml + :caption: The `allow_ip` type parameter set in the :file:`firefox/10-manual.yml` structure file :linenos: .. --- @@ -53,8 +214,7 @@ This is where the ability to parameterize our variable comes in. params: allow_ip: true -We can see line 11 and 12 that the params allow the domain name `address` variable to be set -with IPs. +The params allow the domain name `address` variable to be set with IPs. .. glossary:: diff --git a/docs/tutorial/family.rst b/docs/tutorial/family.rst index 355984f4a..5ccfb146f 100644 --- a/docs/tutorial/family.rst +++ b/docs/tutorial/family.rst @@ -29,7 +29,7 @@ Group variables inside families .. type-along:: let's recap how far we've come -We have this choice type variable in its structure definition file: +We have this choice variable in its structure definition file: .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_010/firefox/00-proxy.yml :linenos: @@ -272,12 +272,9 @@ Now let's add a `port` variable in the `http_proxy` family: address: description: HTTP address type: domainname - params: - allow_ip: true port: description: HTTP Port - type: port default: 8080 :tutorial:`Download this file from the rougail-tutorials git repository `