rougail/docs/tutorial/proxymode.rst

The `proxy` 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: `string` (a *domain name*)
   :default: None

   This is a setting that controls the value of the answer.

.. keypoints:: Key points progress

    **Keywords**

    - :term:`family`, and sub families
    - :term:`variable`\ s defined inside of a family

We have two variables :confval:`proxy_mode` and :confval:`address`.