rougail/docs/tutorial/domainname.rst

A variable with type `domainname`
==================================

.. objectives:: Objectives

   Discover new types of variables.

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

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


.. keypoints:: let's review the key points

    **Keywords**
    
    - we can add :term:`parameter`\ s to variables to refine their behavior
    
    **Progress**

    FIXME