stove/rougail
3
0
Fork 0
Code Issues 5 Pull requests 1 Projects Releases Wiki Activity

domain name type

Browse source
This commit is contained in:
gwen 2025-12-02 11:08:54 +01:00
parent 920780384d
commit be4983e524
2 changed files with 183 additions and 26 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

204
docs/tutorial/domainname.rst
View file

@ -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 <installation>` 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 <src/branch/1.1>`,
this workshop page corresponds to the tags :tutorial:`v1.1_030 <src/tag/v1.1_030>` to :tutorial:`v1.1_033 <src/tag/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 <src/tag/v1.1_030/firefox/10-manual.yml>`
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 <src/tag/v1.1_030/config/01/config.yml>`
.. 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
..
<pre>╭──────── Caption ────────╮
│ Variable <span style="color: #ffd700">Default value</span> │
│ <span style="color: #00aa00">Modified value</span> │
╰─────────────────────────╯
Variables:
<span style="color: #5c5cff">┣━━ </span>📓 Configure Proxy Access to the Internet: <span style="color: #ffd700">No proxy</span>
<span style="color: #5c5cff">┗━━ </span>📂 Manual proxy configuration
<span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📂 HTTP Proxy
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff">┗━━ </span>📓 HTTP address: <span style="color: #00aa00">example.net</span> ◀ loaded from the YAML file
<span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span><span style="color: #5c5cff"> </span>"config/01/config.yml"
</pre>
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 <src/tag/v1.1_030/config/02/config.yml>`
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
..
<pre><span style="font-weight: bold; color: #ff0000">🛑 ERRORS</span>
<span style="color: #ff0000">┗━━ </span>the value "192.168.0.1" is an invalid domain name for
<span style="color: #ff0000"> </span>"manual.http_proxy.address" (HTTP address), must not be an IP, it will be
<span style="color: #ff0000"> </span>ignored when loading from the YAML file "config/02/config.yml"
</pre>
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 <src/tag/v1.1_030/config/03/config.yml>`
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
..
<pre><span style="font-weight: bold; color: #ff0000">🛑 ERRORS</span>
<span style="color: #ff0000">┗━━ </span>the value "bla bla" is an invalid domain name for
<span style="color: #ff0000"> </span>"manual.http_proxy.address" (HTTP address), must not be an IP, it will be
<span style="color: #ff0000"> </span>ignored when loading from the YAML file "config/02/config.yml"
</pre>
.. 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::

5
docs/tutorial/family.rst
View file

@ -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 <src/tag/v1.1_022/config/03/config.yml>`