diff --git a/docs/tutorial/domainname.rst b/docs/tutorial/domainname.rst index ad00b667f..9e23c1253 100644 --- a/docs/tutorial/domainname.rst +++ b/docs/tutorial/domainname.rst @@ -272,15 +272,110 @@ A variable with type `port` git checkout v1.1_032 -We will add, according to our use case, a variable of type `port`: +After the `address` variable let's add, according to our use case, .. image:: images/firefox_port.png +a new variable of type `port`. Our structure file looks like this: +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_032/firefox/10-manual.yml + :language: yaml + :caption: The `port` type variable in the :file:`firefox/10-manual.yml` structure file + :linenos: +.. + port: + description: HTTP Port + type: port + default: 8080 + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +Let's assing a value to this port: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/config/02/config.yml + :language: yaml + :caption: A user data :file:`config/02/config.yml` setting a value to the port variable + +.. + proxy_mode: Manual proxy configuration + manual: + http_proxy: + address: example.net + port: 3128 + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +If we launch the rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/config/02/cmd_ro.txt + +We have this output: + +.. raw:: html + :class: output + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/config/02/output_ro.html + +.. +
╭─────────────────────────── Caption ────────────────────────────╮
+    │ Variable                           Modified value              │
+    │ Undocumented but modified variable (⏳ Original default value) │
+    ╰────────────────────────────────────────────────────────────────╯
+    Variables:
+    ┣━━ 📓 Configure Proxy Access to the Internet: Manual proxy configuration ◀ 
+    loaded from the YAML file "config/02/config.yml" (⏳ No proxy)
+    ┗━━ 📂 Manual proxy configuration
+        ┗━━ 📂 HTTP Proxy
+            ┣━━ 📓 HTTP address: example.net ◀ loaded from the YAML file 
+            "config/02/config.yml"
+            ┗━━ 📓 HTTP Port: 3128 ◀ loaded from the YAML file 
+                "config/02/config.yml" (⏳ 8080)
+    
+ +How can we know what validations the port type performs on the value assigned to the variable? + +There are a number of validations that are carried out with this `port` type: + +- well-known ports (1 to 1023) are allowed +- registred ports (1024 to 49151) are allowed + +.. - private ports (greater than 49152) are allowed + +Now let's assign a value that is outside the allowed ports: + +.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/config/03/config.yml + :language: yaml + :caption: A user value in :file:`config/03/config.yml` that is not allowed + +:tutorial:`Download this file from the rougail-tutorials git repository ` + +Again, we launch the rougail CLI: + +.. raw:: html + :class: terminal + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/config/03/cmd_invalid.txt + +.. rougail -m firefox/ -u yaml -yf config/03/config.yml --cli.invalid_user_datas_error + +And we have this output: + +.. raw:: html + :class: error + :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_032/config/03/output_invalid.html + +.. +
🛑 ERRORS
+    ┗━━ the value "100000" is an invalid port for "manual.http_proxy.port" (HTTP 
+        Port), must be between 1 and 65535, it will be ignored when loading from the
+        YAML file "config/03/config.yml"
+    
+ +We observe that, as with the `domainname` type, a number of validations are performed +to ensure that the value assigned to this variable conforms to the `port` type. + .. keypoints:: let's review the key points - **Keywords** - - - we can set a `domainname` type to a variable - - we can add :term:`parameter`\ s to variables to refine their typing behavior - + - we can assign a `domainname` type to a variable + - we can set a :term:`parameter` to a `domainname` variable to refine their typing behavior + - we can assign a `port` type to a variable