rougail/docs/tutorial/proxymode.rst

The `manual` family
====================

.. objectives:: Objectives

   We will learn how to:

   - create a :term:`family`
   - gather :term:`variable`\ s into a :term:`family`
   - make a variable within a variable, which turns this variable container into being a family

.. prerequisites:: Reminders

    - We have an idea of what a :term:`structure description file<structure file>` is
    - We have a folder named :file:`firefox` and we are putting all the structure description files into it


.. type-along:: So we have this choice type variable in the structure file

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_013/firefox/00-proxy.yml
   :linenos:
   :language: yaml
   :caption: The `proxy_mode` choice type variable in the :file:`firefox/00-proxy.yml` structure file

..
    ---
    proxy_mode:
      description: Configure Proxy Access to the Internet
      type: choice
      choices:
        - No proxy
        - Auto-detect proxy settings for this network
        - Use system proxy settings
        - Manual proxy configuration
        - Automatic proxy configuration URL
      default: No proxy

.. We're gonna put it in a :term:`family`.

.. note:: The variables, families, etc. will be created in several files for educational purposes.
          Here we made a :file:`firefox/00-proxy.yml` structure file and we're gonna make 
          a new structure file named :file:`firefox/10-manual.yml`
          We could of course have put everything in one file, we decided to separate the files for reasons of ordering and clarity

So we have now a `proxy_mode` variable.

.. confval:: proxy_mode
   :type: `choice`
   :default: No proxy

   This is a setting that controls the proxy's type

A family named `manual`
-------------------------

Let's create a family named `manual`

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_020/firefox/10-manual.yml
   :language: yaml
   :caption: A family structure file description named `manual` in a :file:`firefox/10-manual.yml` file
   :name: RougailManualFamily

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

We can see that we have defined a :term:`family` here, and this family is *empty*
(that is the family which is a container variable contains no variable yet).

.. admonition:: If a family is empty

    We need to specify the :term:`family` type here because if we don't,
    the Rougail's type engine will infer it by default as a :term:`variable`.

    It's because we don't have set any :term:`variable` inside. If we have a variable inside of a family, 
    we make a YAML block (that is, we indent) and the Rougail's type inference engine will implicitely infer it as a family.

.. type-along::  A family inside a family

Creating a family hierarchy is very easy, here is an example:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_021/firefox/10-manual.yml
   :language: yaml
   :caption: A rougail structure description file with a hierarchy.
   :name: RougailFirstFamilyHierarchy

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

      http_proxy:
        description: HTTP Proxy
        type: family

Here the `http_proxy` family lives inside the `manual` family.

Putting a variable inside of a family or a sub family
----------------------------------------------------------

Let's create a variable in its family.
The type of this variable is a `choice` type:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/firefox/10-manual.yml
   :language: yaml
   :caption: An `address` variable in the `http_proxy` family
   :name: RougailVariableInSubFamily

..
    ---
    manual:
      description: Manual proxy configuration
      type: family

      http_proxy:
        description: HTTP Proxy
        type: family

        address:
          description: HTTP address
          type: domainname

The :term:`operator` can now then set :term:`a value <value>` to the :confval:`address` variable

So we have now an `address` variable.

.. confval:: address
   :type: `domainname`
   :default: None

   This is the HTTP address of the proxy

.. note:: We encountered here a new type of variable there: the `domainname` type


Assigning a user value
------------------------------------

Now we need to set a value ​​for the :confval:`address` variable, 
otherwise we will get an error if we try to access this variable:

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/config/01/output_rw.html
   :class: error-box

.. 
    <pre>🛑 ERRORS
    <span style="color: #ff0000">┣━━ </span>The following variables are mandatory but have no value:
    <span style="color: #ff0000">┗━━ </span>  - manual.http_proxy.address (HTTP address)
    </pre>

Because this variable is mandatory. 

.. glossary::

   mandatory
   
       A variable is defined as mandatory if it **must** have a value.

.. type-along:: user files are where the user values lives

And we need to set the values ​​in separate files too, called `user files`.

.. glossary::

   user file
   
       A user file is a file where users can set values, called user values -- 
       that is variable's values that have been set by an :term:`operator`\ . 

Let's set user values in user files

Here is a user file sample: 

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/config/03/config.yaml
   :language: yaml
   :caption: A user file named :file:`config/config.yaml` with a value set for the `address` variable
   :name: RougailAddresseVariableUserValue
       
.. 
    ---
    proxy_mode: Manual proxy configuration
    manual:
      http_proxy:
        address: example.net

.. glossary::

   configuration 
   
       We call configuration the whole system structure and user values,
       and when we speak of consistency, it is in relation to this whole set. 

Let's validate the consitency of the configuration:

.. code-block:: text
   :class: terminal
   
    rougail -v 1.1 -m firefox/ -u file -ff config/config.yaml

Everything is OK:

.. raw:: html
   :url: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_024/config/03/output_rw.html
   :class: output

.. 
    <pre>╭────────────────────────── Caption ──────────────────────────╮
    │ Variable                           <span style="color: #ffd700">Default value</span>            │
    │ <span style="color: #5c5cff">Undocumented variable</span>              Modified value           │
    │ <span style="color: #ff0000">Undocumented but modified variable</span> (<span style="color: #00aa00">Original default value</span>) │
    ╰─────────────────────────────────────────────────────────────╯
    Variables:
    <span style="color: #5c5cff">┣━━ </span>📓 proxy_mode: Manual proxy configuration (<span style="color: #00aa00">No proxy</span>)
    <span style="color: #5c5cff">┗━━ </span>📂 manual
    <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>📓 address: example.net
    </pre>

- the `proxy_mode` value is in green because its value is set by default
- the `address` value is in black because its value has been set by a user

Variables can have parameters
---------------------------------

.. questions:: Question

   **question**: Does our `address` domain name variable accepts IP addresses ? 

   **answer**: Well it depends.

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.

.. 
    ---
    manual:
      description: Manual proxy configuration

      http_proxy:
        description: HTTP Proxy

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

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_025/firefox/10-manual.yml
   :language: yaml
   :caption: The `address` has a parameter set in the :file:`firefox/10-manual.yml` structure file
   :name: RougailAddressParameter
   :linenos:
..
    ---
    manual:
      description: Manual proxy configuration

      http_proxy:
        description: HTTP Proxy

        address:
          description: HTTP address
          type: domainname
          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. 

.. type-along:: One more variable

Let's create a `port` variable in the `http_proxy` family:

.. confval:: port
   :type: `port`
   :default: 8080

   The HTTP Port

Here is the new :file:`firefox/10-manual.yml` structure file:

.. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/tag/v1.1_026/firefox/10-manual.yml
   :language: yaml
   :caption: A rougail structure description file with a hierarchy.
   :name: RogailPortVariable
   :linenos:
   
.. 
    ---
    manual:
      description: Manual proxy configuration

      http_proxy:
        description: HTTP Proxy

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

        port:
          description: HTTP Port
          type: port
          default: 8080

Take a look at lines 14 to 17.

.. glossary::

   parameter
   
       A parameter is a property of a variable that can refine its behavior

.. keypoints:: Key points progress

    **Keywords**
    
    - we know how to define :term:`variable`\ s inside of a family
    - we now know what a :term:`mandatory` variable is
    - we kwow how to set a variable's user value (in a :term:`user file`)
    - we have the big picture : the :term:`configuration`, which is (the structure files + the user files)
    - we can add :term:`parameters` to variables to refine their behavior
    
    **Progress**

    - we have a :term:`family` named `manual`  and a sub family named `http_proxy`
    - And we have now two variables: :confval:`proxy_mode` and :confval:`address`.