rougail/docs/tutorial/domainname.rst

The `domainname` and `port` types
==================================

.. objectives:: Objectives

   There isn't just the `string` or `integer` type, 
   discover new types of variables, such as `domainname` and `port`.

.. 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_030 <src/tag/v1.1_030>` to :tutorial:`v1.1_033 <src/tag/v1.1_033>` 
    in the repository.

    ::
   
       git clone https://forge.cloud.silique.fr/stove/rougail-tutorials.git
       git checkout v1.1_030

.. type-along:: let's recap how far we've come

We have an `http_proxy` family with an `address` variable in it.

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

A variable with type `domainname`
-----------------------------------

Notice that 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:
      http_proxy:
        address: net.example

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_030/config/01/config.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 associated with the fact that we have assigned
a type to this variable. But if we assign this (wrong) user data:

.. type-along:: A domain name has no space in it

Let's have a look at an 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 for the :file:`config/03/config.yml` 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:: what if we set an IP address instead of a domain name?

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_030/config/02/config.yml
   :language: yaml
   :caption: A domain name in the :file:`config/02/config.yml` 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>`

With a value that *is not a domain name* but an IP address, then when we will launch the rougail CLI 
we will see a little problem:

.. 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 variable with type's parameters

.. questions:: Question

   OK I agree with the `domainname` necessary type validation, 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 now.
   
   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:
..
    ---
    manual:
      description: Manual proxy configuration

      http_proxy:
        description: HTTP Proxy

        address:
          description: HTTP address
          type: domainname
          params:
            allow_ip: true

The params allow the domain name `address` variable to be set with IPs. 

.. glossary::

   parameter
   
       A parameter is a property of a variable that can refine its behavior. 
       It is declared by adding the `params` attribute in the variable's 
       definition.

Now we will test with an IP address as the value for our `address` variable.

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_031/config/02/config.yml
   :language: yaml
   :caption: An IP address as a value in the :file:`config/02/config.yml` user value

.. 
    ---
    manual:
      http_proxy:
        address: 192.168.0.1

:tutorial:`Download this file from the rougail-tutorials git repository <src/tag/v1.1_031/config/02/config.yml>`

if we launch the rougail CLI on it:

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_031/config/02/cmd_ro.txt
   :class: terminal

..
    rougail -m firefox/ -u yaml -yf config/02/config.yml

We have this output: 

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_031/config/02/output_ro.html
   :class: output

We can see that the IP address value has been accepted.

A variable with type `port`
------------------------------

.. type-along:: For those who follow the tutorial with the help of the git repository

    Now you need to checkout the `v1.1_032` version::
     
          git checkout v1.1_032


We will add, according to our use case, a variable of type `port`:

.. image:: images/firefox_port.png


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